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
- CF = unknown
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 src/EntityManager/EntityManager.ts:50

Properties

`Readonly`logger

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

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

Accessors

config

get config(): {
    entities: Record<
        string,
        {
            defaultLimit: number;
            defaultPageSize: number;
            shardBumps: { charBits: number; chars: number; timestamp: number }[];
            timestampProperty: string;
            uniqueProperty: string;
        },
    >;
    generatedKeyDelimiter: string;
    generatedProperties: {
        sharded: Record<string, string[]>;
        unsharded: Record<string, string[]>;
    };
    generatedValueDelimiter: string;
    hashKey: string;
    indexes: Record<
        string,
        { hashKey: string; projections?: string[]; rangeKey: string },
    >;
    propertyTranscodes: Record<string, string>;
    rangeKey: string;
    shardKeyDelimiter: string;
    throttle: number;
    transcodes: Record<string, { decode: unknown; encode: unknown }>;
}
Get the current EntityManager Config object.

Returns {
    entities: Record<
        string,
        {
            defaultLimit: number;
            defaultPageSize: number;
            shardBumps: { charBits: number; chars: number; timestamp: number }[];
            timestampProperty: string;
            uniqueProperty: string;
        },
    >;
    generatedKeyDelimiter: string;
    generatedProperties: {
        sharded: Record<string, string[]>;
        unsharded: Record<string, string[]>;
    };
    generatedValueDelimiter: string;
    hashKey: string;
    indexes: Record<
        string,
        { hashKey: string; projections?: string[]; rangeKey: string },
    >;
    propertyTranscodes: Record<string, string>;
    rangeKey: string;
    shardKeyDelimiter: string;
    throttle: number;
    transcodes: Record<string, { decode: unknown; encode: unknown }>;
}
Current Config object.
- Defined in src/EntityManager/EntityManager.ts:73
set config(
    value: {
        entities: Record<
            string,
            {
                defaultLimit: number;
                defaultPageSize: number;
                shardBumps: { charBits: number; chars: number; timestamp: number }[];
                timestampProperty: string;
                uniqueProperty: string;
            },
        >;
        generatedKeyDelimiter: string;
        generatedProperties: {
            sharded: Record<string, string[]>;
            unsharded: Record<string, string[]>;
        };
        generatedValueDelimiter: string;
        hashKey: string;
        indexes: Record<
            string,
            { hashKey: string; projections?: string[]; rangeKey: string },
        >;
        propertyTranscodes: Record<string, string>;
        rangeKey: string;
        shardKeyDelimiter: string;
        throttle: number;
        transcodes: Record<string, { decode: unknown; encode: unknown }>;
    },
): void
Set the current EntityManager Config object.
Parameters
- value: {
      entities: Record<
          string,
          {
              defaultLimit: number;
              defaultPageSize: number;
              shardBumps: { charBits: number; chars: number; timestamp: number }[];
              timestampProperty: string;
              uniqueProperty: string;
          },
      >;
      generatedKeyDelimiter: string;
      generatedProperties: {
          sharded: Record<string, string[]>;
          unsharded: Record<string, string[]>;
      };
      generatedValueDelimiter: string;
      hashKey: string;
      indexes: Record<
          string,
          { hashKey: string; projections?: string[]; rangeKey: string },
      >;
      propertyTranscodes: Record<string, string>;
      rangeKey: string;
      shardKeyDelimiter: string;
      throttle: number;
      transcodes: Record<string, { decode: unknown; encode: unknown }>;
  }
  Config object.
Returns void
- Defined in src/EntityManager/EntityManager.ts:82

Methods

addKeys

addKeys<ET extends string>(
    entityToken: ET,
    item: EntityItemByToken<CC, ET>,
    overwrite?: boolean,
): EntityRecordByToken<CC, ET>
Update generated properties, hash key, and range key on an EntityItem object.
Type Parameters
- ET extends string
Parameters
- entityToken: ET
  Config entities key.
- item: EntityItemByToken<CC, ET>
  EntityItem object.
- Optionaloverwrite: boolean
  Overwrite existing properties (default false).
Returns EntityRecordByToken<CC, ET>
EntityRecord object with updated properties.

Throws
Error if entityToken is invalid.
- Defined in src/EntityManager/EntityManager.ts:116
addKeys<ET extends string>(
    entityToken: ET,
    item: EntityItemByToken<CC, ET>[],
    overwrite?: boolean,
): EntityRecordByToken<CC, ET>[]
Type Parameters
- ET extends string
Parameters
- entityToken: ET
- item: EntityItemByToken<CC, ET>[]
- Optionaloverwrite: boolean
Returns EntityRecordByToken<CC, ET>[]
- Defined in src/EntityManager/EntityManager.ts:124

encodeGeneratedProperty

encodeGeneratedProperty(
property: CC["ShardedKeys"] | CC["UnshardedKeys"],
item: EntityItem<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: EntityItem<CC>
  EntityItem object.
Returns string | undefined
Encoded generated property value.

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

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 src/EntityManager/EntityManager.ts:256
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 src/EntityManager/EntityManager.ts:264

getPrimaryKey

getPrimaryKey<ET extends string>(
    entityToken: ET,
    item: EntityItemByToken<CC, ET>,
    overwrite?: boolean,
): EntityKey<CC>[]
Convert one or more EntityItem objects into an array of EntityKey values.
Type Parameters
- ET extends string
Parameters
- entityToken: ET
  Config entities key.
- item: EntityItemByToken<CC, ET>
  EntityItem object, or array of them.
- Optionaloverwrite: boolean
  Overwrite existing properties (default false).
Returns EntityKey<CC>[]
An array of EntityKey values. For a single input item, returns 0..N keys (usually 1). For an array input, returns a single flattened array of keys across all inputs.

Throws
Error if entityToken is invalid.
- Defined in src/EntityManager/EntityManager.ts:166
getPrimaryKey<ET extends string>(
    entityToken: ET,
    items: EntityItemByToken<CC, ET>[],
    overwrite?: boolean,
): EntityKey<CC>[]
Type Parameters
- ET extends string
Parameters
- entityToken: ET
- items: EntityItemByToken<CC, ET>[]
- Optionaloverwrite: boolean
Returns EntityKey<CC>[]
- Defined in src/EntityManager/EntityManager.ts:174

`Protected`query

query<ET extends string, 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
- 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 src/EntityManager/EntityManager.ts:308

removeKeys

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

Throws
Error if entityToken is invalid.
- Defined in src/EntityManager/EntityManager.ts:216
removeKeys<ET extends string>(
entityToken: ET,
items: EntityRecordByToken<CC, ET>[],
): EntityItemByToken<CC, ET>[]
Type Parameters
- ET extends string
Parameters
- entityToken: ET
- items: EntityRecordByToken<CC, ET>[]
Returns EntityItemByToken<CC, ET>[]
- Defined in src/EntityManager/EntityManager.ts:223

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

Parameters

Returns void

Methods

addKeys

Type Parameters

Parameters

Returns EntityRecordByToken<CC, ET>

Throws

Type Parameters

Parameters

Returns EntityRecordByToken<CC, ET>[]

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>[]

Protectedquery

Type Parameters

Parameters

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

Remarks

Throws

removeKeys

Type Parameters

Parameters

Returns EntityItemByToken<CC, ET>

Throws

Type Parameters

Parameters

Returns EntityItemByToken<CC, ET>[]

Settings

On This Page

`Readonly`logger

`Protected`query