@karmaniverous/entity-manager 5.0.8 → 6.0.0

package/dist/index.d.cts

@@ -0,0 +1,826 @@
+import { Entity, Exactify, TranscodeMap, PropertiesOfType, TranscodableProperties, Transcodes, DefaultTranscodeMap, SortOrder } from '@karmaniverous/entity-tools';
+export { DefaultTranscodeMap, Entity, PropertiesOfType, SortOrder, TranscodableProperties, TranscodeMap, Transcodes, defaultTranscodes } from '@karmaniverous/entity-tools';
+import { z } from 'zod';
+
+/**
+ * The base EntityMap type. All EntityMaps should extend this type.
+ *
+ * @category Entities
+ */
+type EntityMap = Record<string, Entity>;
+/**
+ * Tests a string literal type to determine whether it is a key of any {@link Entity | `Entity`} in an {@link EntityMap | `EntityMap`} or is a member of a union of reserved keys.
+ *
+ * @typeParam K - The string literal type to test.
+ * @typeParam M - The {@link EntityMap | `EntityMap`}.
+ * @typeParam R - The reserved set of string literal types.
+ *
+ * @returns `K` if `K` is exclusive or `never` otherwise.
+ *
+ * @category Config
+ * @protected
+ */
+type ExclusiveKey<K extends string, M extends EntityMap, R extends string = never> = keyof {
+    [E in keyof Exactify<M> as K extends keyof Exactify<M[E]> | R ? K : never]: never;
+} extends never ? K : never;
+/**
+ * Returns the `generated` property of a Config entity.
+ *
+ * @typeParam EntityToken - The {@link Entity | `Entity`} token.
+ * @typeParam M - The {@link EntityMap | `EntityMap`}.
+ * @typeParam T - The {@link TranscodeMap | `TranscodeMap`} identifying transcodable property types.
+ *
+ * @remarks
+ * All Entity properties of type `never` must be represented, and no extra properties are allowed.
+ *
+ * @category Config
+ * @protected
+ */
+type ConfigEntityGenerated<EntityToken extends keyof Exactify<M>, M extends EntityMap, T extends TranscodeMap> = ([PropertiesOfType<M[EntityToken], never>] extends [never] ? never : Record<PropertiesOfType<M[EntityToken], never>, {
+    atomic?: boolean;
+    elements: TranscodableProperties<M[EntityToken], T>[];
+    sharded?: boolean;
+}>) | ([PropertiesOfType<M[EntityToken], never>] extends [never] ? Record<string, never> : never);
+/**
+ * Defines a single time period in an {@link Entity | `Entity`} sharding strategy.
+ *
+ * @category Config
+ * @protected
+ */
+interface ShardBump {
+    /**
+     * The timestamp marking the beginning of the time period. Must be a non-negative integer.
+     *
+     * This value must be unique across all {@link ShardBump | `ShardBumps`} for the {@link Entity | `Entity`}.
+     */
+    timestamp: number;
+    /**
+     * The number of bits per character in the bump's shard space. For example, `0` yields a single shard per character, and a value of `2` would yield 4 shards per character.
+     *
+     * This value must be an integer between `1` and `5` inclusive.
+     */
+    charBits: number;
+    /**
+     * The number of characters used to represent the bump's shard key.
+     *
+     * This value must be an integer between `0` and `40` inclusive. Note that more than a few characters will result in an impossibly large shard space!   *
+     * A ShardBump with `chars` of `2` and `charBits` of `3` would yield a two-character shard key with a space of 16 shards.
+     */
+    chars: number;
+}
+/**
+ * Returns a Config entity type.
+ *
+ * @typeParam EntityToken - The {@link Entity | `Entity`} token.
+ * @typeParam M - The {@link EntityMap | `EntityMap`}.
+ * @typeParam HashKey - The property used across the configuration to store an {@link Entity | `Entity`}'s sharded hash key. Should be configured as the table hash key. Must not conflict with any {@link Entity | `Entity`} property.
+ * @typeParam RangeKey - The property used across the configuration to store an {@link Entity | `Entity`}'s range key. Should be configured as the table range key. Must not conflict with any {@link Entity | `Entity`} property.
+ * @typeParam T - The {@link TranscodeMap | `TranscodeMap`} identifying transcodable property types. Only {@link Entity | `Entity`} properties of these types can be components of an {@link ConfigEntity.indexes | index} or a {@link ConfigEntityGenerated | generated property}.
+
+ * @remarks
+ * `generated` is optional if `E` has no properties of type `never`.
+ *
+ * @category Config
+ * @protected
+ */
+type ConfigEntity<EntityToken extends keyof Exactify<M>, M extends EntityMap, HashKey extends string, RangeKey extends string, T extends TranscodeMap> = {
+    /**
+     * The default maximum number of records to return from a query.
+     *
+     * @defaultValue `10`
+     *
+     * @remarks
+     * Can be overridden at {@link QueryOptions.limit | `QueryOptions.limit`}.
+     *
+     * In cross-shard queries, the actual number of records returned is heavily influenced by {@link QueryOptions.pageSize | query pageSize} and the number of shards queried. Actual results may significantly exceed this limit.
+     */
+    defaultLimit?: number;
+    /**
+     * The default maximum number of records to return per data page on an individual shard query.
+     *
+     * @defaultValue `10`
+     *
+     * @remarks
+     * Shard queries will be repeated internally until either the shard is exhausted or the number of records returned exceeds the {@link QueryOptions.limit | query limit}.
+     *
+     * Can be overridden at {@link QueryOptions.pageSize | `QueryOptions.pageSize`}.
+     */
+    defaultPageSize?: number;
+    /**
+     * This object assigns transcodes to {@link Entity | `Entity`} generated property & ungenerated index elements.
+     *
+     * These transcodes are used to encode and decode generated property values & pageKeys.
+     *
+     * The keys of this object must be transcodable properties of the {@link Entity | `Entity`}.
+     *
+     * The values of this object must be one of the keys of the {@link Config | `Config`} `T` type parameter (the config's {@link TranscodeMap | `TranscodeMap`}).
+     *
+     * The types of the related {@link Entity | `Entity`} and {@link TranscodeMap | `TranscodeMap`} properties should match.
+     *
+     * If any entity generated property element or ungenerated index element is not included here, the {@link Config | `Config`} object will fail to parse.
+     *
+     * @example
+     * ```
+     * // Default transcodable types.
+     * interface DefaultTranscodeMap extends TranscodeMap {
+     *   string: string;
+     *   number: number;
+     *   boolean: boolean;
+     *   bigint: bigint;
+     * }
+     *
+     * interface MyEntityMap extends EntityMap {
+     *   user: {
+     *    created: number;
+     *    data?: Json; // Not a Stringifiable type
+     *    userId: string;
+     *   };
+     * }
+     *
+     * // T type param defaults to DefaultTranscodeMap.
+     * const config: Config<MyEntityMap> = {
+     *   entities: {
+     *     user: {
+     *       ...,
+     *       types: { // All Stringafiable properties required!
+     *         created: 'number',
+     *         userId: 'string',
+     *         // 'data' not allowed: not a Stringifiable type
+     *       }
+     *     }
+     *   },
+     *   ...
+     * };
+     * ```
+     */
+    elementTypes?: ([TranscodableProperties<M[EntityToken], T>] extends [never] ? never : {
+        [P in TranscodableProperties<M[EntityToken], T>]?: PropertiesOfType<T, M[EntityToken][P]>;
+    }) | ([TranscodableProperties<M[EntityToken], T>] extends [never] ? Record<string, never> : never);
+    /**
+     * Indexes defined for the {@link Entity | `Entity`}. Should reflect the underlying database table indexes.
+     *
+     * Each key is the name of an index, and each value is a non-empty array of {@link Entity | `Entity`} property names that define the index.
+     *
+     * Related property types must be align with the {@link Config | `Config`} `T` type parameter. Note tha all {@link ConfigEntityGenerated | generated property} types are transcodable by definition.
+     */
+    indexes?: Record<string, (TranscodableProperties<M[EntityToken], T> | PropertiesOfType<M[EntityToken], never> | HashKey | RangeKey)[]>;
+    /**
+     * An array of {@link ShardBump | `ShardBump`} objects representing the {@link Entity | `Entity`}'s sharding strategy.
+     *
+     * If omitted, or if configured without a zero-{@link ShardBump.timestamp | `timestamp`} {@link ShardBump | `ShardBump`}, this array will be initialized with the following {@link ShardBump | `ShardBump`} as its first member:
+     *
+     * ```
+     * { timestamp: 0, charBits: 0, chars: 1 }
+     * ```
+     *
+     * Members must be unique by {@link ShardBump.timestamp | `timestamp`}.
+     *
+     * {@link ShardBump.chars | `chars`} must increase monotonically with {@link ShardBump.timestamp | `timestamp`}
+     *
+     * Array will be sorted in ascending order by {@link ShardBump.timestamp | `timestamp`} on initialization.
+     *
+     * Future {@link ShardBump | `ShardBumps`} can be changed as required, but past {@link ShardBump | `ShardBumps`} should not be modified or data integrity will be compromised!
+     */
+    shardBumps?: ShardBump[];
+    /**
+     * Identifies the {@link Entity | `Entity`} property used as the timestamp for shard key calculations.
+     *
+     * This property must be of type `number`. Its value should not change over the life of the record. A `created` timestamp is ideal.
+     *
+     * Once in production, this configuration property should not be changed or data integrity will be compromised!
+     */
+    timestampProperty: PropertiesOfType<M[EntityToken], number>;
+    /**
+     * Identifies the {@link Entity | `Entity`} used as the basis for both shard key calculations and the table's {@link ConfigKeys.rangeKey | range key}.
+     *
+     * This property must be of type `string` or `number`. Its value should be a unique record identifier and should not change over the life of the record.
+     *
+     * Once in production, this configuration property should not be changed or data integrity will be compromised!
+     */
+    uniqueProperty: PropertiesOfType<M[EntityToken], number | string>;
+} & ([PropertiesOfType<M[EntityToken], never>] extends [never] ? {
+    generated?: ConfigEntityGenerated<EntityToken, M, T>;
+} : {
+    /**
+     * {@link Entity | `Entity`} properties whose values will be generated by EntityManager.
+     *
+     * These properties should be indicated by a `never` type in the {@link Config | `Config`} `EntityMap` type parameter.
+     *
+     * All such properties must be accounted for in the `generated` object, and no additional properties are permitted..
+     */
+    generated: ConfigEntityGenerated<EntityToken, M, T>;
+});
+/**
+ * Returns the `entities` property of the {@link Config | `Config`} tyoe.
+ *
+ * @typeParam M - The {@link EntityMap | `EntityMap`} type that identitfies the {@link Entity | `Entity`} & related property types to be managed by EntityManager.
+ * @typeParam HashKey - The property used across the configuration to store an {@link Entity | `Entity`}'s sharded hash key. Should be configured as the table hash key. Must not conflict with any {@link Entity | `Entity`} property.
+ * @typeParam RangeKey - The property used across the configuration to store an {@link Entity | `Entity`}'s range key. Should be configured as the table range key. Must not conflict with any {@link Entity | `Entity`} property.
+ * @typeParam T - The {@link TranscodeMap | `TranscodeMap`} identifying transcodable property types. Only {@link Entity | `Entity`} properties of these types can be components of an {@link ConfigEntity.indexes | index} or a {@link ConfigEntityGenerated | generated property}.
+ *
+ * @remarks
+ * All properties of `M` must be represented, and no extra properties are allowed.
+ *
+ * @category Config
+ * @protected
+ */
+type ConfigEntities<M extends EntityMap, HashKey extends string, RangeKey extends string, T extends TranscodeMap> = ([keyof Exactify<M>] extends [never] ? never : {
+    [E in keyof Exactify<M>]: ConfigEntity<E, M, HashKey, RangeKey, T>;
+}) | Record<string, never>;
+/**
+ * Returns variably-optional properties of the {@link Config | `Config`} type as optional.
+
+ * @typeParam M - The {@link EntityMap | `EntityMap`} type that identitfies the {@link Entity | `Entity`} & related property types to be managed by EntityManager.
+ * @typeParam HashKey - The property used across the configuration to store an {@link Entity | `Entity`}'s sharded hash key. Should be configured as the table hash key. Must not conflict with any {@link Entity | `Entity`} property.
+ * @typeParam RangeKey - The property used across the configuration to store an {@link Entity | `Entity`}'s range key. Should be configured as the table range key. Must not conflict with any {@link Entity | `Entity`} property.
+ * @typeParam T - The {@link TranscodeMap | `TranscodeMap`} identifying transcodable property types. Only {@link Entity | `Entity`} properties of these types can be components of an {@link ConfigEntity.indexes | index} or a {@link ConfigEntityGenerated | generated property}.
+ *
+ * @category Config
+ * @protected
+ */
+interface ConfigKeys<M extends EntityMap, HashKey extends string, RangeKey extends string, T extends TranscodeMap> {
+    /**
+     * Defines options for each {@link Entity | `Entity`} in the {@link Config | `Config`} `EntityMap` type parameter.
+     *
+     * The properties of this object must exactly match the keys of the {@link Config | `Config`} `EntityMap` type parameter.
+     */
+    entities?: ConfigEntities<M, HashKey, RangeKey, T>;
+    /**
+     * The property used across the configuration to store an {@link Entity | `Entity`}'s sharded hash key. Should be configured as the table hash key.
+     *
+     * This value must exactly match the {@link Config | `Config`} `HashKey` type parameter, and must not conflict with any {@link Entity | `Entity`} property.
+     *
+     * @defaultValue `'hashKey'`
+     *
+     * @category Config
+     * @protected
+     */
+    hashKey?: ExclusiveKey<HashKey, M, RangeKey>;
+    /**
+     * The property used across the configuration to store an {@link Entity | `Entity`}'s range key. Should be configured as the table range key.
+     *
+     * This value must exactly match the {@link Config | `Config`} `RangeKey` type parameter, and must not conflict with any {@link Entity | `Entity`} property.
+     *
+     * @defaultValue `'rangeKey'`
+     */
+    rangeKey?: ExclusiveKey<RangeKey, M, HashKey>;
+}
+/**
+ * @category Config
+ * @protected
+ */
+type ConfigTranscodes<T extends TranscodeMap> = ([keyof Exactify<T>] extends [never] ? never : Transcodes<T>) | ([keyof Exactify<T>] extends [never] ? Record<string, never> : never);
+/**
+ * EntityManager Config type.
+ *
+ * @typeParam M - The {@link EntityMap | `EntityMap`} type that identitfies the {@link Entity | `Entity`} & related property types to be managed by EntityManager.
+ * @typeParam HashKey - The property used across the configuration to store an {@link Entity | `Entity`}'s sharded hash key. Should be configured as the table hash key. Must not conflict with any {@link Entity | `Entity`} property. Defaults to `'hashKey'`.
+ * @typeParam RangeKey - The property used across the configuration to store an {@link Entity | `Entity`}'s range key. Should be configured as the table range key. Must not conflict with any {@link Entity | `Entity`} property. Defaults to `'rangeKey'`.
+ * @typeParam T - The {@link TranscodeMap | `TranscodeMap`} identifying transcodable property types. Only {@link Entity | `Entity`} properties of these types can be components of an {@link ConfigEntity.indexes | index} or a {@link ConfigEntityGenerated | generated property}. Defaults to {@link DefaultTranscodeMap | `DefaultTranscodeMap`}.
+ *
+ * @remarks
+ * `entities` is optional if `M` is empty.
+ *
+ * @category Config
+ */
+type Config<M extends EntityMap = Record<string, never>, HashKey extends string = 'hashKey', RangeKey extends string = 'rangeKey', T extends TranscodeMap = DefaultTranscodeMap> = ([keyof Exactify<M>] extends [never] ? ConfigKeys<M, HashKey, RangeKey, T> : Required<ConfigKeys<M, HashKey, RangeKey, T>>) & {
+    /**
+     * Defines the delimiter used to separate key-value pairs in a generated property value.
+     *
+     * Must consist of one or more non-word characters, and must not intersect with {@link Config.generatedValueDelimiter | `generatedValueDelimiter`} or {@link Config.shardKeyDelimiter | `shardKeyDelimiter`}.
+     *
+     * @defaultValue `'|'`
+     */
+    generatedKeyDelimiter?: string;
+    /**
+     * Defines the delimiter used to separate keys & values in a generated property value.
+     *
+     * Must consist of one or more non-word characters, and must not intersect with {@link Config.generatedKeyDelimiter | `generatedKeyDelimiter`} or {@link Config.shardKeyDelimiter | `shardKeyDelimiter`}.
+     *
+     * @defaultValue `'#'`
+     */
+    generatedValueDelimiter?: string;
+    /**
+     * Defines the delimiter used to construct an Entity's hashKey value from its Entity key and shard key.
+     *
+     * Must consist of one or more non-word characters, and must not intersect with {@link Config.generatedKeyDelimiter | `generatedKeyDelimiter`} or {@link Config.generatedValueDelimiter | `generatedValueDelimiter`}.
+     *
+     * @defaultValue `'!'`
+     */
+    shardKeyDelimiter?: string;
+    /**
+     * The default maximum number of shards to query in parallel. Can be overridden at {@link QueryOptions.throttle | `QueryOptions.throttle`}.
+     *
+     * @defaultValue `10`
+     */
+    throttle?: number;
+} & ([keyof Exactify<T>] extends [never] ? {
+    transcodes?: ConfigTranscodes<T>;
+} : DefaultTranscodeMap extends T ? {
+    transcodes?: ConfigTranscodes<T>;
+} : {
+    transcodes: ConfigTranscodes<T>;
+});
+/**
+ * Flattens the top layer of logic in a type.
+ *
+ * @category Utility
+ * @protected
+ */
+type Unwrap<T> = {
+    [P in keyof T]: T[P];
+};
+/**
+ * Extracts a map of {@link Entity | `Entity`} item types decorated with {@link ConfigKeys.hashKey | hashKey}, {@link ConfigKeys.rangeKey | rangeKey}, and {@link ConfigEntityGenerated | generated properties}.
+ *
+ * @typeParam M - The {@link EntityMap | `EntityMap`} type that identitfies the {@link Entity | `Entity`} & related property types to be managed by EntityManager.
+ * @typeParam HashKey - The property used across the configuration to store an {@link Entity | `Entity`}'s sharded hash key. Should be configured as the table hash key. Must not conflict with any {@link Entity | `Entity`} property. Defaults to `'hashKey'`.
+ * @typeParam RangeKey - The property used across the configuration to store an {@link Entity | `Entity`}'s range key. Should be configured as the table range key. Must not conflict with any {@link Entity | `Entity`} property. Defaults to `'rangeKey'`.
+ *
+ * @category Entities
+ */
+type ItemMap<M extends EntityMap, HashKey extends string = 'hashKey', RangeKey extends string = 'rangeKey'> = {
+    [EntityToken in keyof Exactify<M>]: Unwrap<{
+        [P in keyof Exactify<M[EntityToken]>]: [
+            NonNullable<M[EntityToken][P]>
+        ] extends [never] ? string : M[EntityToken][P];
+    } & {
+        [P in HashKey | RangeKey]?: string;
+    }>;
+};
+
+declare const configSchema: z.ZodEffects<z.ZodObject<{
+    entities: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+        defaultLimit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        defaultPageSize: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        generated: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodObject<{
+            atomic: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+            elements: z.ZodEffects<z.ZodArray<z.ZodString, "atleastone">, [string, ...string[]], [string, ...string[]]>;
+            sharded: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        }, "strip", z.ZodTypeAny, {
+            atomic: boolean;
+            elements: [string, ...string[]];
+            sharded: boolean;
+        }, {
+            elements: [string, ...string[]];
+            atomic?: boolean | undefined;
+            sharded?: boolean | undefined;
+        }>>>>>;
+        elementTypes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+        indexes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodArray<z.ZodString, "atleastone">, [string, ...string[]], [string, ...string[]]>>>>;
+        shardBumps: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+            timestamp: z.ZodNumber;
+            charBits: z.ZodNumber;
+            chars: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }, {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }>, "many">>>, {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[], {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[] | undefined>, {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[], {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[] | undefined>, {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[], {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[] | undefined>;
+        timestampProperty: z.ZodString;
+        uniqueProperty: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        defaultLimit: number;
+        defaultPageSize: number;
+        elementTypes: Record<string, string>;
+        indexes: Record<string, [string, ...string[]]>;
+        shardBumps: {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[];
+        timestampProperty: string;
+        uniqueProperty: string;
+        generated: Record<string, {
+            atomic: boolean;
+            elements: [string, ...string[]];
+            sharded: boolean;
+        } | undefined>;
+    }, {
+        timestampProperty: string;
+        uniqueProperty: string;
+        defaultLimit?: number | undefined;
+        defaultPageSize?: number | undefined;
+        elementTypes?: Record<string, string> | undefined;
+        indexes?: Record<string, [string, ...string[]]> | undefined;
+        shardBumps?: {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[] | undefined;
+        generated?: Record<string, {
+            elements: [string, ...string[]];
+            atomic?: boolean | undefined;
+            sharded?: boolean | undefined;
+        } | undefined> | undefined;
+    }>, {
+        defaultLimit: number;
+        defaultPageSize: number;
+        elementTypes: Record<string, string>;
+        indexes: Record<string, [string, ...string[]]>;
+        shardBumps: {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[];
+        timestampProperty: string;
+        uniqueProperty: string;
+        generated: Record<string, {
+            atomic: boolean;
+            elements: [string, ...string[]];
+            sharded: boolean;
+        } | undefined>;
+    }, {
+        timestampProperty: string;
+        uniqueProperty: string;
+        defaultLimit?: number | undefined;
+        defaultPageSize?: number | undefined;
+        elementTypes?: Record<string, string> | undefined;
+        indexes?: Record<string, [string, ...string[]]> | undefined;
+        shardBumps?: {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[] | undefined;
+        generated?: Record<string, {
+            elements: [string, ...string[]];
+            atomic?: boolean | undefined;
+            sharded?: boolean | undefined;
+        } | undefined> | undefined;
+    }>>>>;
+    generatedKeyDelimiter: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    generatedValueDelimiter: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    shardKeyDelimiter: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    hashKey: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    rangeKey: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    throttle: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    transcodes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        encode: z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodString>;
+        decode: z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodAny>;
+    }, "strict", z.ZodTypeAny, {
+        encode: (args_0: any, ...args: unknown[]) => string;
+        decode: (args_0: string, ...args: unknown[]) => any;
+    }, {
+        encode: (args_0: any, ...args: unknown[]) => string;
+        decode: (args_0: string, ...args: unknown[]) => any;
+    }>>>>;
+}, "strict", z.ZodTypeAny, {
+    hashKey: string;
+    rangeKey: string;
+    entities: Record<string, {
+        defaultLimit: number;
+        defaultPageSize: number;
+        elementTypes: Record<string, string>;
+        indexes: Record<string, [string, ...string[]]>;
+        shardBumps: {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[];
+        timestampProperty: string;
+        uniqueProperty: string;
+        generated: Record<string, {
+            atomic: boolean;
+            elements: [string, ...string[]];
+            sharded: boolean;
+        } | undefined>;
+    }>;
+    generatedKeyDelimiter: string;
+    generatedValueDelimiter: string;
+    shardKeyDelimiter: string;
+    throttle: number;
+    transcodes: Record<string, {
+        encode: (args_0: any, ...args: unknown[]) => string;
+        decode: (args_0: string, ...args: unknown[]) => any;
+    }>;
+}, {
+    hashKey?: string | undefined;
+    rangeKey?: string | undefined;
+    entities?: Record<string, {
+        timestampProperty: string;
+        uniqueProperty: string;
+        defaultLimit?: number | undefined;
+        defaultPageSize?: number | undefined;
+        elementTypes?: Record<string, string> | undefined;
+        indexes?: Record<string, [string, ...string[]]> | undefined;
+        shardBumps?: {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[] | undefined;
+        generated?: Record<string, {
+            elements: [string, ...string[]];
+            atomic?: boolean | undefined;
+            sharded?: boolean | undefined;
+        } | undefined> | undefined;
+    }> | undefined;
+    generatedKeyDelimiter?: string | undefined;
+    generatedValueDelimiter?: string | undefined;
+    shardKeyDelimiter?: string | undefined;
+    throttle?: number | undefined;
+    transcodes?: Record<string, {
+        encode: (args_0: any, ...args: unknown[]) => string;
+        decode: (args_0: string, ...args: unknown[]) => any;
+    }> | undefined;
+}>, {
+    hashKey: string;
+    rangeKey: string;
+    entities: Record<string, {
+        defaultLimit: number;
+        defaultPageSize: number;
+        elementTypes: Record<string, string>;
+        indexes: Record<string, [string, ...string[]]>;
+        shardBumps: {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[];
+        timestampProperty: string;
+        uniqueProperty: string;
+        generated: Record<string, {
+            atomic: boolean;
+            elements: [string, ...string[]];
+            sharded: boolean;
+        } | undefined>;
+    }>;
+    generatedKeyDelimiter: string;
+    generatedValueDelimiter: string;
+    shardKeyDelimiter: string;
+    throttle: number;
+    transcodes: Record<string, {
+        encode: (args_0: any, ...args: unknown[]) => string;
+        decode: (args_0: string, ...args: unknown[]) => any;
+    }>;
+}, {
+    hashKey?: string | undefined;
+    rangeKey?: string | undefined;
+    entities?: Record<string, {
+        timestampProperty: string;
+        uniqueProperty: string;
+        defaultLimit?: number | undefined;
+        defaultPageSize?: number | undefined;
+        elementTypes?: Record<string, string> | undefined;
+        indexes?: Record<string, [string, ...string[]]> | undefined;
+        shardBumps?: {
+            timestamp: number;
+            charBits: number;
+            chars: number;
+        }[] | undefined;
+        generated?: Record<string, {
+            elements: [string, ...string[]];
+            atomic?: boolean | undefined;
+            sharded?: boolean | undefined;
+        } | undefined> | undefined;
+    }> | undefined;
+    generatedKeyDelimiter?: string | undefined;
+    generatedValueDelimiter?: string | undefined;
+    shardKeyDelimiter?: string | undefined;
+    throttle?: number | undefined;
+    transcodes?: Record<string, {
+        encode: (args_0: any, ...args: unknown[]) => string;
+        decode: (args_0: string, ...args: unknown[]) => any;
+    }> | undefined;
+}>;
+/**
+ * Foo
+ *
+ * @category Config
+ */
+type ParsedConfig = z.infer<typeof configSchema>;
+
+/**
+ * A result returned by a {@link ShardQueryFunction | `ShardQueryFunction`} querying an individual shard.
+ *
+ * @typeParam Item - The {@link ItemMap | `ItemMap`} type being queried.
+ * @typeParam T - The {@link TranscodeMap | `TranscodeMap`} identifying property types that can be indexed.
+
+* @category Query
+ */
+interface ShardQueryResult<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string = 'hashKey', RangeKey extends string = 'rangeKey', T extends TranscodeMap = DefaultTranscodeMap> {
+    /** The number of records returned. */
+    count: number;
+    /** The returned records. */
+    items: Item[];
+    /** The page key for the next query on this shard. */
+    pageKey?: Partial<Pick<Item, PropertiesOfType<Item, T[keyof T]>>>;
+}
+
+/**
+ * A query function that returns a single page of results from an individual
+ * shard. This function will typically be composed dynamically to express a
+ * specific query index & logic. The arguments to this function will be
+ * provided by the {@link EntityManager.query | `EntityManager.query`} method, which assembles many returned
+ * pages queried across multiple shards into a single query result.
+ *
+ * @typeParam Item - The {@link ItemMap | `ItemMap`} type being queried.
+ * @typeParam T - The {@link TranscodeMap | `TranscodeMap`} identifying property types that can be indexed. Defaults to {@link DefaultTranscodeMap | `DefaultTranscodeMap`}.
+
+ * @param hashKey - The {@link ConfigKeys.hashKey | `this.config.hashKey`} property value of the shard being queried.
+ * @param pageKey - The page key returned by the previous query on this shard.
+ * @param pageSize - The maximum number of items to return from this query.
+ *
+ * @category Query
+ */
+type ShardQueryFunction<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string = 'hashKey', RangeKey extends string = 'rangeKey', T extends TranscodeMap = DefaultTranscodeMap> = (hashKey: string, pageKey?: Partial<Pick<Item, PropertiesOfType<Item, T[keyof T]>>>, pageSize?: number) => Promise<ShardQueryResult<Item, EntityToken, M, HashKey, RangeKey, T>>;
+
+/**
+ * Options passed to the {@link EntityManager.query | `EntityManager.query`} method.
+ *
+ * @category Query
+ */
+interface QueryOptions<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string, RangeKey extends string, T extends TranscodeMap> {
+    /** Identifies the entity to be queried. Key of {@link Config | `EntityManager.config.entities`}. */
+    entityToken: EntityToken;
+    /**
+     * Identifies the entity key across which the query will be sharded. Key of
+     * {@link Config | `EntityManager.config.entities.<entityToken>.keys`}.
+     */
+    hashKey: string;
+    /**
+     * A partial {@link ItemMap | `ItemMap`} object containing at least the properties specified in
+     * {@link Config | `EntityManager.config.entities.<entityToken>.keys.<keyToken>.elements`}, except for the properties specified in {@link Config | `EntityManager.config.tokens`}.
+     *
+     * This data will be used to generate query keys across all shards.
+     */
+    item?: Item;
+    /**
+     * The target maximum number of records to be returned by the query across
+     * all shards.
+     *
+     * The actual number of records returned will be a product of {@link QueryOptions.pageSize | `pageSize`} and the
+     * number of shards queried, unless limited by available records in a given
+     * shard.
+     */
+    limit?: number;
+    /**
+     * {@link QueryResult.pageKeyMap | `pageKeyMap`} returned by the previous iteration of this query.
+     */
+    pageKeyMap?: string;
+    /**
+     * The maximum number of records to be returned by each individual query to a
+     * single shard (i.e. {@link ShardQueryFunction | `ShardQueryFunction`} execution).
+     *
+     * Note that, within a given {@link EntityManager.query | `query`} method execution, these queries will be
+     * repeated until either available data is exhausted or the {@link QueryOptions.limit | `limit`} value is
+     * reached.
+     */
+    pageSize?: number;
+    /**
+     * Each key in this object is a valid entity index token. Each value is a valid
+     * {@link ShardQueryFunction | 'ShardQueryFunction'} that specifies the query of a single page of data on a
+     * single shard for the mapped index.
+     *
+     * This allows simultaneous queries on multiple sort keys to share a single
+     * page key, e.g. to match the same string against `firstName` and `lastName`
+     * properties without performing a table scan for either.
+     */
+    queryMap: Record<string, ShardQueryFunction<Item, EntityToken, M, HashKey, RangeKey, T>>;
+    /**
+     * A {@link SortOrder | `SortOrder`} object specifying the sort order of the result set. Defaults to `[]`.
+     */
+    sortOrder?: SortOrder<Item>;
+    /**
+     * Lower limit to query shard space.
+     *
+     * Only valid if the query is constrained along the dimension used by the
+     * {@link Config | `EntityManager.config.entities.<entityToken>.sharding.timestamptokens.timestamp`}
+     * function to generate `shardKey`.
+     *
+     * @defaultValue `0`
+     */
+    timestampFrom?: number;
+    /**
+     * Upper limit to query shard space.
+     *
+     * Only valid if the query is constrained along the dimension used by the
+     * {@link Config | `EntityManager.config.entities.<entityToken>.sharding.timestamptokens.timestamp`}
+     * function to generate `shardKey`.
+     *
+     * @defaultValue `Date.now()`
+     */
+    timestampTo?: number;
+    /**
+     * The maximum number of shards to query in parallel. Overrides options `throttle`.
+     *
+     * @defaultValue `options.throttle`
+     */
+    throttle?: number;
+}
+
+/**
+ * A result returned by a query across multiple shards, where each shard may
+ * receive multiple page queries via a dynamically-generated {@link ShardQueryFunction | `ShardQueryFunction`}.
+ *
+ * @category Query
+ */
+interface QueryResult<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string, M extends EntityMap, HashKey extends string, RangeKey extends string> {
+    /** Total number of records returned across all shards. */
+    count: number;
+    /** The returned records. */
+    items: Item[];
+    /**
+     * A compressed, two-layer map of page keys, used to query the next page of
+     * data for a given sort key on each shard of a given hash key.
+     */
+    pageKeyMap: string;
+}
+
+/**
+ * The EntityManager class applies a configuration-driven sharded data model &
+ * query strategy to NoSql data.
+ *
+ * @category Entity Manager
+ */
+declare class EntityManager<M extends EntityMap, HashKey extends string, RangeKey extends string, T extends TranscodeMap> {
+    #private;
+    /**
+     * Create an EntityManager instance.
+     *
+     * @param config - EntityManager {@link Config | `Config`} object.
+     */
+    constructor(config: Config<M, HashKey, RangeKey, T>);
+    /**
+     * Get the current EntityManager {@link Config | `Config`} object.
+     *
+     * @returns Current {@link Config | `Config`} object.
+     */
+    get config(): ParsedConfig;
+    /**
+     * Set the current EntityManager {@link Config | `Config`} object.
+     *
+     * @param value - {@link Config | `Config`} object.
+     */
+    set config(value: ParsedConfig);
+    /**
+     * Update generated properties, hash key, and range key on an {@link ItemMap | `ItemMap`} object. Mutates `item`.
+     *
+     * @param item - {@link ItemMap | `ItemMap`} object.
+     * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
+     * @param overwrite - Overwrite existing properties (default `false`).
+     *
+     * @returns Mutated `item` with updated properties.
+     *
+     * @throws `Error` if `entityToken` is invalid.
+     */
+    addKeys<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string>(item: Item, entityToken: EntityToken, overwrite?: boolean): Item;
+    /**
+     * Strips generated properties, hash key, and range key from an {@link ItemMap | `ItemMap`} object. Mutates `item`.
+     *
+     * @param item - {@link ItemMap | `ItemMap`} object.
+     * @param entityToken - {@link ConfigKeys.entities | `this.config.entities`} key.
+     *
+     * @returns Mutated `item` without generated properties, hash key or range key.
+     *
+     * @throws `Error` if `entityToken` is invalid.
+     */
+    removeKeys<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string>(item: Item, entityToken: EntityToken): Item;
+    /**
+     * Query a database entity across shards in a provider-generic fashion.
+     *
+     * @remarks
+     * The provided {@link ShardQueryFunction | `ShardQueryFunction`} performs the actual query of individual data pages on individual shards. This function is presumed to express provider-specific query logic, including any necessary indexing or search constraints.
+     *
+     * Individual shard query results will be combined, deduped by {@link ConfigEntity.uniqueProperty} property value, and sorted by {@link QueryOptions.sortOrder | `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.
+     *
+     * @param options - {@link QueryOptions | `QueryOptions`} object.
+     *
+     * @returns {@link QueryResult} object.
+     *
+     * @throws Error if {@link QueryOptions.pageKeyMap | `pageKeyMap`} keys do not match {@link QueryOptions.queryMap | `queryMap`} keys.
+     */
+    query<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string>(options: QueryOptions<Item, EntityToken, M, HashKey, RangeKey, T>): Promise<QueryResult<Item, EntityToken, M, HashKey, RangeKey>>;
+}
+
+export { type Config, type ConfigEntities, type ConfigEntity, type ConfigEntityGenerated, type ConfigKeys, type ConfigTranscodes, EntityManager, type EntityMap, type ExclusiveKey, type ItemMap, type ParsedConfig, type QueryOptions, type QueryResult, type ShardBump, type ShardQueryFunction, type ShardQueryResult, type Unwrap };