Class EntityManager<CC, CF>

The EntityManager class applies a configuration-driven sharded data model & query strategy to NoSql data.

Remarks

While the query method is public, normally it should not be called directly. The query method is used by a platform-specific QueryBuilder.query method to provide a fluent query API.

Type Parameters

CC extends BaseConfigMap
ConfigMap that defines the configuration's EntityMap, key properties, and TranscodeRegistry. If omitted, defaults to BaseConfigMap.
CF = unknown
Values-first config literal type captured at construction time (phantom generic; type-only). This is used by downstream adapters to infer index-token unions (ITS) and per-index page key shapes.

Index

Constructors

constructor

new EntityManager<CC extends BaseConfigMap, CF = unknown>(
config: Config<CC>,
logger?: Pick<Console, "debug" | "error">,
): EntityManager<CC, CF>
Create an EntityManager instance.
Type Parameters
- CC extends BaseConfigMap
  ConfigMap that defines the configuration's EntityMap, key properties, and TranscodeRegistry. If omitted, defaults to BaseConfigMap.
- CF = unknown
  Values-first config literal type captured at construction time (phantom generic; type-only). This is used by downstream adapters to infer index-token unions (ITS) and per-index page key shapes.
Parameters
- config: Config<CC>
  EntityManager Config object.
- logger: Pick<Console, "debug" | "error"> = console
  Logger object (defaults to console, must support debug & error methods).
Returns EntityManager<CC, CF>
- Defined in EntityManager/EntityManager.ts:55

Properties

`Readonly`logger

logger: Pick<Console, "debug" | "error">

Logger object (defaults to console, must support debug & error methods).

Accessors

config

get config(): ParsedConfig
Get the current EntityManager Config object.

Returns ParsedConfig
Current Config object.
- Defined in EntityManager/EntityManager.ts:78
set config(value: ParsedConfig): void
Set the current EntityManager Config object.
Parameters
- value: ParsedConfig
  Config object.
Returns void
- Defined in EntityManager/EntityManager.ts:87

Methods

addKeys

addKeys<ET extends string | number | symbol>(
    entityToken: ET,
    item: EntityItemPartial<CC, ET>,
    overwrite?: boolean,
): EntityRecord<CC, ET>
Update generated properties, hash key, and range key on an EntityItem object.
Type Parameters
- ET extends string | number | symbol
Parameters
- entityToken: ET
  Entity token (narrows types by token).
- item: EntityItemPartial<CC, ET>
  Single item to update with generated keys/properties.
- Optionaloverwrite: boolean
  Overwrite existing keys/properties (default false).
Returns EntityRecord<CC, ET>
EntityRecord object with updated properties.

Throws
Error if entityToken is invalid.
- Defined in EntityManager/EntityManager.ts:121
addKeys<ET extends string | number | symbol>(
    entityToken: ET,
    item: Partial<EntityItem<CC, ET>>[],
    overwrite?: boolean,
): EntityRecord<CC, ET>[]
Update generated properties, hash key, and range key on an array of EntityItem objects.
Type Parameters
- ET extends string | number | symbol
Parameters
- entityToken: ET
  Entity token (narrows types by token).
- item: Partial<EntityItem<CC, ET>>[]
  Items to update with generated keys/properties.
- Optionaloverwrite: boolean
  Overwrite existing keys/properties (default false).
Returns EntityRecord<CC, ET>[]
Array of EntityRecord objects with updated properties.

Throws
Error if entityToken is invalid.
- Defined in EntityManager/EntityManager.ts:139

encodeGeneratedProperty

encodeGeneratedProperty(
property: CC["ShardedKeys"] | CC["UnshardedKeys"],
item: StorageItem<CC>,
): string | undefined
Encode a generated property value. Returns a string or undefined if atomicity requirement of sharded properties not met.
Parameters
- property: CC["ShardedKeys"] | CC["UnshardedKeys"]
  Config generatedProperties key.
- item: StorageItem<CC>
  StorageItem object.
Returns string | undefined
Encoded generated property value.

Throws
Error if property is not a Config generatedProperties key.
- Defined in EntityManager/EntityManager.ts:101

findIndexToken

findIndexToken(
    hashKeyToken: CC["HashKey"] | CC["ShardedKeys"],
    rangeKeyToken:
        | CC["RangeKey"]
        | CC["UnshardedKeys"]
        | CC["TranscodedProperties"],
    suppressError?: false,
): IndexTokensOf<CF>
Find an index token based on the configured hash and range key tokens.
Parameters
- hashKeyToken: CC["HashKey"] | CC["ShardedKeys"]
  Index hash key token (global hashKey or a sharded generated key).
- rangeKeyToken: CC["RangeKey"] | CC["UnshardedKeys"] | CC["TranscodedProperties"]
  Index range key token (global rangeKey, unsharded generated key, or a transcodable scalar).
- OptionalsuppressError: false
  When false (default), throws if no match; when true, returns undefined instead.
Returns IndexTokensOf<CF>
A configured index token (narrowed to the CF.indexes key union) or undefined when allowed.

Throws
Error if no match is found and suppressError is not true.
- Defined in EntityManager/EntityManager.ts:272
findIndexToken(
    hashKeyToken: CC["HashKey"] | CC["ShardedKeys"],
    rangeKeyToken:
        | CC["RangeKey"]
        | CC["UnshardedKeys"]
        | CC["TranscodedProperties"],
    suppressError: true,
): IndexTokensOf<CF> | undefined
Find an index token based on the configured hash and range key tokens.
Parameters
- hashKeyToken: CC["HashKey"] | CC["ShardedKeys"]
  Index hash key token (global hashKey or a sharded generated key).
- rangeKeyToken: CC["RangeKey"] | CC["UnshardedKeys"] | CC["TranscodedProperties"]
  Index range key token (global rangeKey, unsharded generated key, or a transcodable scalar).
- suppressError: true
  When false (default), throws if no match; when true, returns undefined instead.
Returns IndexTokensOf<CF> | undefined
A configured index token (narrowed to the CF.indexes key union) or undefined when allowed.

Throws
Error if no match is found and suppressError is not true.
- Defined in EntityManager/EntityManager.ts:278

getPrimaryKey

getPrimaryKey<ET extends string | number | symbol>(
    entityToken: ET,
    item: EntityItemPartial<CC, ET>,
    overwrite?: boolean,
): EntityKey<CC>[]
Convert one or more EntityItem objects into an array of EntityKey values.
Type Parameters
- ET extends string | number | symbol
Parameters
- entityToken: ET
  Entity token (narrows types by token).
- item: EntityItemPartial<CC, ET>
  Single item to derive primary keys for.
- Optionaloverwrite: boolean
  Overwrite existing keys on the item before deriving (default false).
Returns EntityKey<CC>[]
Array of EntityKey values derived from item.

Throws
Error if entityToken is invalid.
- Defined in EntityManager/EntityManager.ts:170
getPrimaryKey<ET extends string | number | symbol>(
    entityToken: ET,
    items: Partial<EntityItem<CC, ET>>[],
    overwrite?: boolean,
): EntityKey<CC>[]
Convert an array of EntityItem objects into EntityKey values.
Type Parameters
- ET extends string | number | symbol
Parameters
- entityToken: ET
  Entity token (narrows types by token).
- items: Partial<EntityItem<CC, ET>>[]
  Array of items to derive primary keys for.
- Optionaloverwrite: boolean
  Overwrite existing keys on each item before deriving (default false).
Returns EntityKey<CC>[]
Array of EntityKey values derived from all items.

Throws
Error if entityToken is invalid.
- Defined in EntityManager/EntityManager.ts:188

`Protected`query

query<
    ET extends string
    | number
    | symbol,
    ITS extends string,
    CF = unknown,
    K = unknown,
>(
    options: QueryOptions<CC, ET, ITS, CF, K>,
): Promise<QueryResult<CC, ET, ITS, K>>
Protected
Query a database entity across shards in a provider-generic fashion.
Type Parameters
- ET extends string | number | symbol
- ITS extends string
- CF = unknown
- K = unknown
Parameters
- options: QueryOptions<CC, ET, ITS, CF, K>
  QueryOptions object.
Returns Promise<QueryResult<CC, ET, ITS, K>>
QueryResult object.

Remarks
The provided shardQueryMap performs the actual query of individual data pages on individual index/shard combinations.

Individual shard query results will be combined, deduped by Config uniqueProperty value, and sorted by sortOrder.

In queries on sharded data, expect the leading and trailing edges of returned data pages to interleave somewhat with preceding & following pages.

Unsharded query results should sort & page as expected.

Normally this method should not be called directly! It is used by a platform-specific QueryBuilder.query method to provide a fluent query API.

Throws
Error if options pageKeyMap pageKeyMap keys do not match shardQueryMap keys.
- Defined in EntityManager/EntityManager.ts:318

removeKeys

removeKeys<ET extends string | number | symbol>(
entityToken: ET,
item: EntityRecord<CC, ET>,
): EntityItem<CC, ET>
Strips generated properties, hash key, and range key from an EntityRecord object.
Type Parameters
- ET extends string | number | symbol
Parameters
- entityToken: ET
  Config entities key.
- item: EntityRecord<CC, ET>
  EntityRecord object.
Returns EntityItem<CC, ET>
EntityItem with generated properties, hash key & range key removed.

Throws
Error if entityToken is invalid.

Overloads:
- Defined in EntityManager/EntityManager.ts:220
removeKeys<ET extends string | number | symbol, K = unknown>(
entityToken: ET,
item: EntityRecordPartial<CC, ET, K>,
): EntityItemPartial<CC, ET, K>
Strips generated properties, hash key, and range key from an EntityRecord object.
Type Parameters
- ET extends string | number | symbol
- K = unknown
Parameters
- entityToken: ET
  Config entities key.
- item: EntityRecordPartial<CC, ET, K>
  EntityRecord object.
Returns EntityItemPartial<CC, ET, K>
EntityItem with generated properties, hash key & range key removed.

Throws
Error if entityToken is invalid.

Overloads:
- Defined in EntityManager/EntityManager.ts:224
removeKeys<ET extends string | number | symbol>(
entityToken: ET,
items: EntityRecord<CC, ET>[],
): EntityItem<CC, ET>[]
Strips generated properties, hash key, and range key from an EntityRecord object.
Type Parameters
- ET extends string | number | symbol
Parameters
- entityToken: ET
  Config entities key.
- items: EntityRecord<CC, ET>[]
Returns EntityItem<CC, ET>[]
EntityItem with generated properties, hash key & range key removed.

Throws
Error if entityToken is invalid.

Overloads:
- Defined in EntityManager/EntityManager.ts:228
removeKeys<ET extends string | number | symbol, K = unknown>(
entityToken: ET,
items: EntityRecordPartial<CC, ET, K>[],
): EntityItemPartial<CC, ET, K>[]
Strips generated properties, hash key, and range key from an EntityRecord object.
Type Parameters
- ET extends string | number | symbol
- K = unknown
Parameters
- entityToken: ET
  Config entities key.
- items: EntityRecordPartial<CC, ET, K>[]
Returns EntityItemPartial<CC, ET, K>[]
EntityItem with generated properties, hash key & range key removed.

Throws
Error if entityToken is invalid.

Overloads:
- Defined in EntityManager/EntityManager.ts:232

Class EntityManager<CC, CF>

Remarks

Type Parameters

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns EntityManager<CC, CF>

Properties

Readonlylogger

Accessors

config

Returns ParsedConfig

Parameters

Returns void

Methods

addKeys

Type Parameters

Parameters

Returns EntityRecord<CC, ET>

Throws

Type Parameters

Parameters

Returns EntityRecord<CC, ET>[]

Throws

encodeGeneratedProperty

Parameters

Returns string | undefined

Throws

findIndexToken

Parameters

Returns IndexTokensOf<CF>

Throws

Parameters

Returns IndexTokensOf<CF> | undefined

Throws

getPrimaryKey

Type Parameters

Parameters

Returns EntityKey<CC>[]

Throws

Type Parameters

Parameters

Returns EntityKey<CC>[]

Throws

Protectedquery

Type Parameters

Parameters

Returns Promise<QueryResult<CC, ET, ITS, K>>

Remarks

Throws

removeKeys

Type Parameters

Parameters

Returns EntityItem<CC, ET>

Throws

Type Parameters

Parameters

Returns EntityItemPartial<CC, ET, K>

Throws

Type Parameters

Parameters

Returns EntityItem<CC, ET>[]

Throws

Type Parameters

Parameters

Returns EntityItemPartial<CC, ET, K>[]

Throws

Settings

On This Page

`Readonly`logger

`Protected`query