> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/korean/development/api-reference/classes/memorystoresortedmap.md).

# MemoryStoreSortedMap

MemoryStoreSortedMap : `Instance`

## Overview

MemoryStoreSortedMap은 같은 월드의 여러 서버가 공유하는, 정렬된 키-값 형태의 메모리 저장소입니다. 실시간 순위표처럼 항목을 정해진 순서로 조회해야 하는 데이터를 다룰 때 사용합니다.

MemoryStoreService:GetSortedMap() 메서드를 통해서만 가져올 수 있으며, Instance.new()로 생성할 수 없습니다.

이 객체는 서버 Script에서만 사용할 수 있으며, LocalScript에서 호출하면 오류가 발생합니다.

**키와 정렬 키**

각 항목은 키(key)와 별도로 정렬 키(sortKey)를 가질 수 있습니다. 키는 항목을 구분하는 변하지 않는 이름이고, 정렬 키는 항목이 정렬되는 기준 값입니다.

오름차순 기준으로 항목은 다음 순서로 정렬됩니다.

1. 정렬 키가 숫자인 항목 (값 순서)
2. 정렬 키가 문자열인 항목 (사전 순서)
3. 정렬 키가 없는 항목 (키 순서)

정렬 키가 같은 항목끼리는 키 순서로 정렬됩니다.

**저장 규칙**

* 키는 1 \~ 128자의 문자열이어야 합니다.
* 값은 직렬화했을 때 1 \~ 32,768바이트여야 합니다. 순환 참조가 있는 테이블이나 저장할 수 없는 타입의 값을 저장하면 오류가 발생합니다.
* 문자열 정렬 키는 최대 128자입니다.
* 모든 항목에는 만료 시간(초)이 있으며, 0 \~ 3,888,000초(45일) 범위로 지정합니다. 만료된 항목은 없는 항목과 같이 취급됩니다.

**주의사항**

* 휘발성 저장소이므로 저장소가 재시작되면 데이터가 사라질 수 있습니다.
* 캐시를 사용하지 않으므로 모든 읽기와 쓰기는 호출할 때마다 새로 요청됩니다.
* 이 객체의 Async 메서드는 결과를 받을 때까지 호출한 스크립트를 일시 중단(yield)합니다. 요청이 실패하면 오류가 발생하므로 pcall로 감싸 호출하는 것이 좋습니다.

## Properties

## Methods

### GetAsync

지정한 키에 저장된 값과 정렬 키를 반환합니다.

키에 해당하는 항목이 없거나 만료되었으면 오류 없이 nil을 반환합니다. 서버 오류 등으로 요청이 실패하면 nil을 반환하지 않고 오류가 발생합니다.

이 메서드는 결과를 받을 때까지 호출한 스크립트를 일시 중단(yield)합니다.

#### Parameters

| `string` InKey | 값을 가져올 항목의 키입니다. 1 \~ 128자여야 합니다. |
| -------------- | --------------------------------- |

#### Return

| `Tuple` | <p>값과 정렬 키를 함께 반환합니다.</p><ul><li>첫 번째 값은 키에 저장된 값입니다.</li><li>두 번째 값은 항목의 정렬 키(number 또는 string)이며, 정렬 키가 없으면 nil입니다.</li><li>항목이 없거나 만료되었으면 두 값 모두 nil입니다.</li></ul> |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### Code Samples

### GetRangeAsync

정렬 순서에 따라 지정한 범위의 항목을 배열로 반환합니다.

결과는 Pages 객체가 아니라 한 번의 요청으로 받은 배열이며, 최대 InCount개의 항목을 담습니다.

이 메서드는 결과를 받을 때까지 호출한 스크립트를 일시 중단(yield)합니다.

**범위 지정 규칙**

* InLowerBound는 정렬 순서의 앞쪽, InUpperBound는 뒤쪽 경계이며, 정렬 방향과 관계없이 같은 의미입니다.
* 경계에 sortKey만 지정하면 그 정렬 키를 가진 항목은 모두 결과에서 제외됩니다.
* 경계에 sortKey와 key를 함께 지정하면 그 키의 항목 하나만 결과에서 제외됩니다.
* 예를 들어 정렬 키가 20인 항목만 조회하려면 InLowerBound에 { sortKey = 10 }, InUpperBound에 { sortKey = 30 }처럼 바로 앞뒤 정렬 키를 경계로 지정합니다.

#### Parameters

| `Value` InDirection  | <p>정렬 방향입니다.</p><ul><li>Enum.SortDirection.Ascending 또는 Enum.SortDirection.Descending을 지정합니다.</li><li>문자열 "Ascending" 또는 "Descending"도 사용할 수 있으며, 대소문자를 구분하지 않습니다.</li></ul> |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `number` InCount     | <p>반환할 최대 항목 수입니다.</p><ul><li>1 \~ 200 사이의 값을 지정해야 하며, 범위를 벗어나면 오류가 발생합니다.</li><li>소수를 지정하면 올림한 값이 적용됩니다.</li></ul>                                                          |
| `Value` InLowerBound | <p>(선택 사항) 조회 범위의 앞쪽 경계입니다.</p><ul><li>{ key = ..., sortKey = ... } 형태의 테이블로 지정합니다.</li><li>생략하거나 nil을 전달하면 앞쪽 경계 없이 조회합니다.</li></ul>                                        |
| `Value` InUpperBound | <p>(선택 사항) 조회 범위의 뒤쪽 경계입니다.</p><ul><li>{ key = ..., sortKey = ... } 형태의 테이블로 지정합니다.</li><li>생략하거나 nil을 전달하면 뒤쪽 경계 없이 조회합니다.</li></ul>                                        |

#### Return

| `Value` | <p>조회된 항목의 배열입니다.</p><ul><li>각 항목은 key, value, sortKey 필드를 가진 테이블입니다.</li><li>항목은 InDirection에 지정한 방향으로 정렬됩니다.</li><li>조건에 맞는 항목이 없으면 nil이 아니라 빈 테이블을 반환합니다.</li></ul> |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### Code Samples

### GetSizeAsync

저장된 항목의 개수를 반환합니다.

만료된 항목은 개수에서 제외됩니다. 개수를 세는 도중 추가되거나 삭제된 항목은 포함될 수도 있고 포함되지 않을 수도 있습니다.

이 메서드는 결과를 받을 때까지 호출한 스크립트를 일시 중단(yield)합니다.

#### Parameters

#### Return

| `Value` | 저장된 항목의 개수(number)입니다. 아직 아무것도 저장되지 않은 저장소는 0입니다. |
| ------- | ------------------------------------------------- |

#### Code Samples

### RemoveAsync

지정한 키의 항목을 삭제합니다. 정렬 순서에서도 함께 제거됩니다.

존재하지 않는 키를 삭제해도 오류 없이 성공합니다.

이 메서드는 삭제가 완료될 때까지 호출한 스크립트를 일시 중단(yield)합니다.

#### Parameters

| `string` InKey | 삭제할 항목의 키입니다. 1 \~ 128자여야 합니다. |
| -------------- | ------------------------------ |

#### Return

| `Value` | 반환값이 없습니다(nil). |
| ------- | --------------- |

#### Code Samples

### SetAsync

지정한 키에 값과 정렬 키를 저장합니다. 키에 이미 값이 있으면 조건 없이 덮어씁니다.

값과 정렬 키는 함께 갱신됩니다. 만료 시간은 저장할 때마다 새로 적용됩니다.

이 메서드는 저장이 완료될 때까지 호출한 스크립트를 일시 중단(yield)합니다. 저장에 실패하면 오류가 발생합니다.

**주의사항**

* InSortKey를 생략하면 기존 정렬 키가 유지되지 않고 삭제됩니다. 값만 바꾸려면 기존 정렬 키를 다시 전달해야 합니다.

#### Parameters

| `string` InKey       | 값을 저장할 항목의 키입니다. 1 \~ 128자여야 합니다.                                                                                                                                                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Value` InValue      | <p>저장할 값입니다.</p><ul><li>직렬화했을 때 1 \~ 32,768바이트여야 합니다.</li><li>생략하거나 nil을 전달하면 오류가 발생합니다.</li></ul>                                                                                                                                                           |
| `Value` InExpiration | <p>항목의 만료 시간(초)입니다.</p><ul><li>0 \~ 3,888,000초(45일) 사이의 값을 지정해야 하며, 소수도 지정할 수 있습니다.</li><li>0을 지정하면 항목이 즉시 만료되어 삭제됩니다.</li><li>기본값이 없으므로 생략하거나 nil을 전달하면 오류가 발생합니다.</li></ul>                                                                                |
| `Value` InSortKey    | <p>(선택 사항) 항목의 정렬 키입니다.</p><ul><li>number 또는 string(최대 128자)을 지정합니다.</li><li>boolean은 true가 1, false가 0으로, NaN이나 무한대는 0으로 변환됩니다.</li><li>빈 문자열을 지정하거나 생략하면 정렬 키가 없는 항목이 됩니다.</li><li>table, function, Vector3, EnumItem 등 그 밖의 타입을 전달하면 오류가 발생합니다.</li></ul> |

#### Return

| `Value` | 저장하기 전에 키에 항목이 이미 있었으면 true, 없었으면 false입니다. |
| ------- | ------------------------------------------- |

#### Code Samples

### UpdateAsync

지정한 키의 현재 값과 정렬 키를 읽어 콜백 함수로 변환한 뒤, 그 결과를 저장합니다.

값을 읽은 뒤 저장하기 전에 다른 서버나 스크립트가 같은 키를 변경하면, 최신 값을 다시 읽어 콜백을 다시 실행합니다. 이 재시도는 최대 5회 또는 10초까지 수행되며, 그 안에 저장하지 못하면 오류가 발생합니다.

이 메서드는 저장이 완료될 때까지 호출한 스크립트를 일시 중단(yield)합니다.

**주의사항**

* 콜백이 정렬 키를 반환하지 않으면(반환값이 하나뿐이면) 정렬 키가 삭제됩니다. 정렬 키를 유지하려면 콜백이 받은 두 번째 인자를 그대로 반환해야 합니다.
* 콜백은 재시도할 때마다 다시 실행되므로 실행 횟수가 보장되지 않습니다. 콜백 안에서 외부 동작을 수행하지 않아야 합니다.
* 콜백 안에서 오류가 발생하면 값은 변경되지 않고 UpdateAsync에서 오류가 발생합니다.
* 콜백 안에서 같은 키에 대해 다시 UpdateAsync를 호출하면 오류가 발생합니다.
* 만료 시간은 기존 항목의 만료 시간을 유지하지 않고, 갱신할 때마다 InExpiration 값으로 새로 적용됩니다.

#### Parameters

| `string` InKey              | 값을 갱신할 항목의 키입니다. 1 \~ 128자여야 합니다.                                                                                                                                                                                                                           |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Value` InTransformFunction | <p>현재 값과 정렬 키를 받아 새 값과 새 정렬 키를 반환하는 함수입니다.</p><ul><li>항목이 없거나 만료되었으면 두 인자 모두 nil을 받습니다.</li><li>첫 번째 반환값으로 nil을 반환하면 갱신을 취소하며, 이때 UpdateAsync는 오류 없이 nil을 반환합니다.</li><li>두 번째 반환값을 생략하거나 nil을 반환하면 정렬 키가 삭제됩니다.</li><li>함수가 아닌 값을 전달하면 오류가 발생합니다.</li></ul> |
| `Value` InExpiration        | <p>갱신된 항목의 만료 시간(초)입니다.</p><ul><li>0 \~ 3,888,000초(45일) 사이의 값을 지정해야 합니다.</li><li>항목이 이미 있어도 이 값이 새 만료 시간으로 적용됩니다.</li><li>0을 지정하면 항목이 즉시 만료되어 삭제됩니다.</li><li>기본값이 없으므로 생략하거나 nil을 전달하면 오류가 발생합니다.</li></ul>                                                 |

#### Return

| `Tuple` | <p>저장된 새 값과 새 정렬 키를 함께 반환합니다.</p><ul><li>콜백이 nil을 반환해 갱신을 취소했으면 두 값 모두 nil입니다.</li></ul> |
| ------- | ---------------------------------------------------------------------------------------- |

#### Code Samples

## Events
