@karmaniverous/entity-manager 6.14.0 → 6.14.1

package/README.md

@@ -1,34 +1,348 @@
-<!-- TYPEDOC_EXCLUDE -->
+# entity-manager
 
-> [API Documentation](https://docs.karmanivero.us/entity-manager/) • [CHANGELOG](https://github.com/karmaniverous/entity-manager/tree/main/CHANGELOG.md)
+[![npm version](https://img.shields.io/npm/v/@karmaniverous/entity-manager.svg)](https://www.npmjs.com/package/@karmaniverous/entity-manager) ![Node Current](https://img.shields.io/node/v/@karmaniverous/entity-manager) <!-- TYPEDOC_EXCLUDE --> [![docs](https://img.shields.io/badge/docs-website-blue)](https://docs.karmanivero.us/entity-manager) [![changelog](https://img.shields.io/badge/changelog-latest-blue.svg)](https://github.com/karmaniverous/entity-manager/tree/main/CHANGELOG.md)<!-- /TYPEDOC_EXCLUDE --> [![license](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/karmaniverous/entity-manager/tree/main/LICENSE.md)
 
-<!-- /TYPEDOC_EXCLUDE -->
+EntityManager implements rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.
 
-# entity-manager
+If you have any questions, please [start a discussion](https://github.com/karmaniverous/entity-manager/discussions). Otherwise stay tuned!
 
-**EntityManager implements rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.**
+## What is this?
 
-> The Typescript refactor is still in flux, but stabilizing! Still fleshing out the [demo](https://github.com/karmaniverous/entity-manager-demo) & [documentation](https://karmanivero.us/projects/entity-manager/intro/).
+Entity Manager is a TypeScript-first library that applies a provider‑agnostic, highly opinionated single‑table design to your NoSQL data. It lets you:
 
-If you have any questions, please [start a discussion](https://github.com/karmaniverous/entity-manager/discussions). Otherwise stay tuned!
+- Define a global hash key and range key, plus additional generated properties used by your indexes.
+- Encode/decode indexable elements via transcodes so strings sort like their original types.
+- Configure a time‑based sharding strategy (shard bumps) that grows as you scale.
+- Query across many shards and indexes in parallel through injected “shard query” functions — results are combined, de‑duplicated, sorted, and returned with a compact, dehydrated page key for the next request.
+
+It is designed to work with stores like DynamoDB but keeps the orchestration provider‑neutral.
+
+Key links:
+
+- API: https://docs.karmanivero.us/entity-manager
+- Requirements: see .stan/system/stan.requirements.md (authoritative for v6.14.0)
+- Example test configuration: see test/config.ts
+
+## Features
+
+- Global model for generated properties, indexes, and property transcodes
+  - generatedProperties.sharded and generatedProperties.unsharded
+  - Global indexes: indexToken → { hashKey, rangeKey, projections? }
+  - Global propertyTranscodes: property → transcodeName
+- Deterministic sharding
+  - Time‑windowed shard bumps: { timestamp, charBits, chars }
+  - Full shard space assignment per bump (uses radix\*\*chars placeholders)
+  - Cross‑bump query enumeration over all applicable shards
+- Page key dehydration/rehydration
+  - Compact string arrays and lz‑string compression for transport
+  - Rehydrate back to pageKey objects for each index+shard
+- Provider‑agnostic parallel query orchestration
+  - Inject shard query functions for each index
+  - Parallel fan‑out with configurable throttle
+  - Combine, dedupe by unique property, and sort results
+- Strong typing + runtime validation
+  - Zod‑validated config parsing
+  - Robust TypeScript surface for config, items, keys, queries
+
+## Install
+
+```bash
+npm install @karmaniverous/entity-manager
+# optional: testing support used in the repo
+npm install --save-dev @karmaniverous/mock-db
+```
+
+TypeScript is strongly recommended. The library will validate configuration at runtime for JavaScript users, but you lose compile‑time guarantees.
+
+## Usage overview
+
+The pattern has three parts:
+
+1. Define your entity types and a config map
+
+- Each entity type lists all properties that exist on your records.
+- Entity‑level behaviors live in the config’s entities block (timestamp property, unique property, shard bumps).
+- Generated properties, indexes, and transcodes are defined globally.
+
+2. Create an EntityManager instance
+
+- Pass your config (validated with Zod).
+- Optionally inject a logger with debug/error methods (defaults to console).
+
+3. Use EntityManager helpers
+
+- addKeys / getPrimaryKey / removeKeys
+- encodeGeneratedProperty / decodeGeneratedProperty
+- getIndexComponents / unwrapIndex / dehydrateIndexItem / rehydrateIndexItem
+- dehydratePageKeyMap / rehydratePageKeyMap
+- query(options) to orchestrate cross‑shard multi‑index queries
+
+## Quick start (TypeScript)
+
+Below is a minimal end‑to‑end example showing shape and intent. It mirrors the current implementation’s global config model.
+
+```ts
+import {
+  defaultTranscodes,
+  type ConfigMap,
+} from '@karmaniverous/entity-manager';
+import { EntityManager } from '@karmaniverous/entity-manager';
+
+// 1) Entity definitions (Typescript types)
+interface User {
+  userId: string; // unique property
+  created: number; // timestamp property
+  updated: number;
+  firstNameCanonical: string;
+  lastNameCanonical: string;
+  // Generated properties exist on stored items but are configured globally:
+  // e.g., firstNameRK (unsharded), lastNameRK (unsharded), userPK (sharded)
+}
+
+type MyConfigMap = ConfigMap<{
+  EntityMap: { user: User };
+  HashKey: 'hashKey'; // defaults are 'hashKey' / 'rangeKey' if omitted
+  RangeKey: 'rangeKey';
+  ShardedKeys: 'userPK'; // token(s) for sharded generated properties
+  UnshardedKeys: 'firstNameRK' | 'lastNameRK';
+  TranscodedProperties:
+    | 'userId'
+    | 'created'
+    | 'updated'
+    | 'firstNameCanonical'
+    | 'lastNameCanonical';
+}>;
+
+// 2) Build a config with the global model
+const now = Date.now();
+const manager = new EntityManager<MyConfigMap>({
+  // Per-entity: unique + timestamp + shard schedule (+ optional defaults)
+  entities: {
+    user: {
+      uniqueProperty: 'userId',
+      timestampProperty: 'created',
+      shardBumps: [
+        // records with timestamp < now → effectively unsharded
+        { timestamp: now, charBits: 1, chars: 0 },
+        // records with timestamp ≥ now → 1 char at radix 4 (2^2) gives 4 shards
+        { timestamp: now, charBits: 2, chars: 1 },
+      ],
+      // optional defaults (used by query if omitted in options)
+      defaultLimit: 10,
+      defaultPageSize: 10,
+    },
+  },
+
+  // Global generated properties (tokens → element lists)
+  generatedProperties: {
+    sharded: {
+      userPK: ['userId'], // atomic (all required)
+    },
+    unsharded: {
+      firstNameRK: ['firstNameCanonical', 'lastNameCanonical', 'created'],
+      lastNameRK: ['lastNameCanonical', 'firstNameCanonical', 'created'],
+    },
+  },
+
+  // Global key tokens
+  hashKey: 'hashKey',
+  rangeKey: 'rangeKey',
+
+  // Global indexes (hashKey, rangeKey must match allowed token sets)
+  indexes: {
+    created: { hashKey: 'hashKey', rangeKey: 'created' },
+    updated: { hashKey: 'hashKey', rangeKey: 'updated' },
+    firstName: { hashKey: 'hashKey', rangeKey: 'firstNameRK' },
+    lastName: { hashKey: 'hashKey', rangeKey: 'lastNameRK' },
+    userCreated: { hashKey: 'userPK', rangeKey: 'created' }, // sharded alt hash
+  },
+
+  // Transcode mapping for scalar/unsharded elements and properties
+  propertyTranscodes: {
+    userId: 'string',
+    created: 'timestamp',
+    updated: 'timestamp',
+    firstNameCanonical: 'string',
+    lastNameCanonical: 'string',
+  },
+
+  // Transcodes (can override/extend defaultTranscodes)
+  transcodes: defaultTranscodes,
+
+  // Delimiters and query throttle (defaults shown)
+  generatedKeyDelimiter: '|',
+  generatedValueDelimiter: '#',
+  shardKeyDelimiter: '!',
+  throttle: 10,
+});
+```
+
+### Generate keys on items
+
+```ts
+// A partial item (no keys yet)
+const user = {
+  userId: 'u123',
+  created: Date.now(),
+  updated: Date.now(),
+  firstNameCanonical: 'lee',
+  lastNameCanonical: 'zhang',
+};
+
+// Add hashKey, rangeKey, and generated properties
+const record = manager.addKeys('user', user); // returns EntityRecord<...>
+
+// Get just the primary key
+const keyOnly = manager.getPrimaryKey('user', user); // { hashKey, rangeKey }
+
+// Remove generated keys from a stored record
+const pruned = manager.removeKeys('user', record);
+```
+
+### Encode/decode generated property strings
+
+```ts
+// Encode an unsharded generated property (always returns a string)
+const fn = manager.encodeGeneratedProperty('firstNameRK', record);
+// e.g. "firstNameCanonical#lee|lastNameCanonical#zhang|created#000001711234567"
+
+// Decode back into an object fragment
+import { decodeGeneratedProperty } from '@karmaniverous/entity-manager';
+const decoded = decodeGeneratedProperty(manager, fn); // { firstNameCanonical: 'lee', ... }
+```
+
+### Query across shards and indexes
+
+Entity Manager relies on injected shard query functions to perform provider‑specific queries on each shard/index page. The library orchestrates:
+
+- page‑key rehydration → parallel shard queries → de‑duplication and sorting → page‑key dehydration.
+
+```ts
+import type {
+  QueryOptions,
+  ShardQueryFunction,
+} from '@karmaniverous/entity-manager';
+
+// Example shard query using a made-up client (see @karmaniverous/mock-db in repo tests)
+const firstNameQuery: ShardQueryFunction<MyConfigMap> = async (
+  hashKey,
+  pageKey,
+  pageSize,
+) => {
+  // Return { count, items, pageKey? } for this shard+index page
+  // pageKey is a partial item object with necessary index components
+  // ... perform provider-specific work here ...
+  return { count: 0, items: [], pageKey };
+};
+
+// Invoke query with shardQueryMap
+const result = await manager.query({
+  entityToken: 'user',
+  item: {}, // often used to supply elements for alternate hash keys
+  shardQueryMap: { firstName: firstNameQuery },
+  limit: 50,
+  pageSize: 10,
+  // optional: pageKeyMap: previousResult.pageKeyMap,
+  // optional: timestampFrom / timestampTo for shard-space windowing
+});
+```
+
+Notes:
+
+- The result includes a compressed pageKeyMap string for the next call.
+- Entity Manager enumerates the hash key space for the time window, rehydrates the prior page keys (if any), and fans out queries across all shard+index pairs in `shardQueryMap` (up to `throttle`).
+- Items are deduplicated by the entity’s unique property and sorted by `sortOrder` (if provided).
+
+## Configuration reference (current model, v6.14.0)
+
+- entities: Record<entityToken, { timestampProperty, uniqueProperty, shardBumps?, defaultLimit?, defaultPageSize? }>
+- generatedProperties:
+  - sharded: Record<ShardedKey, TranscodedProperties[]>
+  - unsharded: Record<UnshardedKey, TranscodedProperties[]>
+- indexes: Record<indexToken, {
+  - hashKey: HashKey | ShardedKey
+  - rangeKey: RangeKey | UnshardedKey | TranscodedProperties
+  - projections?: string[]
+    }>
+- propertyTranscodes: Record<TranscodedProperties, keyof TranscodeMap>
+- transcodes: Record<transcodeName, { encode, decode }> (defaults to defaultTranscodes)
+- hashKey: HashKey (e.g., 'hashKey')
+- rangeKey: RangeKey (e.g., 'rangeKey')
+- generatedKeyDelimiter: string (default '|', must match /\W+/)
+- generatedValueDelimiter: string (default '#', must match /\W+/)
+- shardKeyDelimiter: string (default '!', must match /\W+/)
+- throttle: number (default 10)
+
+Validation highlights:
+
+- Delimiters must not contain each other.
+- Keys and tokens must be mutually exclusive as required.
+- Generated property element lists are non‑empty and have no duplicates.
+- propertyTranscodes values must exist in transcodes.
+- Index hashKey/rangeKey must use valid token sets.
+- shardBumps are sorted, include a zero‑timestamp bump if missing, and chars must increase monotonically with timestamp.
+
+Sharding:
+
+- For assignment: a record always uses all placeholders for its applicable bump; suffix space is (2**charBits) ** chars.
+- For queries: hash key space spans all bumps overlapping [timestampFrom, timestampTo].
+
+## ESM / CJS
+
+```ts
+// ESM
+import {
+  EntityManager,
+  defaultTranscodes,
+} from '@karmaniverous/entity-manager';
+
+// CJS
+const {
+  EntityManager,
+  defaultTranscodes,
+} = require('@karmaniverous/entity-manager');
+```
+
+## Logging
+
+All helpers log debug context and error detail via the injected logger (defaults to `console`). In tests, you may supply a quiet logger:
+
+```ts
+const logger = { debug: () => undefined, error: console.error };
+const manager = new EntityManager(config, logger);
+```
+
+## Delimiter safety
+
+Generated key/value delimiters and the shard key delimiter are used when composing strings:
 
-## Why?
+- generatedKeyDelimiter: '|' (between pairs)
+- generatedValueDelimiter: '#' (between key and value)
+- shardKeyDelimiter: '!' (between entity token and shard suffix)
 
-Traditional relational database systems like MySQL or SQL Server implement indexing & scaling strategies at a platform level based on schemas defined at design time.
+Your scalar property values used in generated properties should not include these delimiters. If they must, set custom delimiters (must match /\W+/ and not contain each other).
 
-NoSQL platforms like DynamoDB offer far better performance at scale, but structured index & shard keys must be defined as data elements and exploited by application logic in data retrieval & cross-shard queries. **They shift the burden of complexity from the database platform to the developer!**
+## Types you’ll use most
 
-EntityManager encapsulates a provider-agnostic, highly opinionated approach to the [single-table design pattern](https://aws.amazon.com/blogs/compute/creating-a-single-table-design-with-amazon-dynamodb/).
+- ConfigMap<M>
+- EntityItem<C>, EntityRecord<C>, EntityKey<C>, EntityToken<C>
+- QueryOptions<C>, QueryResult<C>
+- PageKey<C>, PageKeyMap<C>
+- ShardQueryFunction<C>, ShardQueryMap<C>, ShardBump
 
-With EntityManager, you can:
+See the full API: https://docs.karmanivero.us/entity-manager
 
-- Define related data entities & structured keys wth a simple, declarative configuration format.
+## Scripts (repo)
 
-- Specify a partition sharding strategy that maximizes query performance while permitting planned, staged scaling over time.
+- build: rollup outputs ESM/CJS + .d.ts
+- test: vitest with coverage
+- lint: ESLint (type‑aware) + Prettier integration
+- docs: TypeDoc (links to external type docs for shared utility packages)
+- typecheck: tsc + tsd (type‑level tests)
 
-- Add or remove structured index keys from entity data objects with a single method call.
+## License
 
-- Perform paged, cross-shard, multi-index queries with a single method call.
+BSD‑3‑Clause (see package.json).
 
 ---
 

package/dist/cjs/EntityManager/ParsedConfig.js

@@ -10,7 +10,7 @@ const validateArrayUnique = (arr, ctx, identity = (item) => item, path = []) =>
     for (const [element, count] of Object.entries(counts)) {
         if (count > 1)
             ctx.addIssue({
-                code: zod.z.ZodIssueCode.custom,
+                code: 'custom',
                 message: `duplicate array element`,
                 params: { element },
                 path,
@@ -21,7 +21,7 @@ const validateKeysExclusive = (keys, label, ref, ctx) => {
     const intersection = keys.filter((key) => ref.includes(key));
     if (intersection.length)
         ctx.addIssue({
-            code: zod.z.ZodIssueCode.custom,
+            code: 'custom',
             message: `${label} key collision: ${intersection.toString()}`,
         });
 };
@@ -32,26 +32,14 @@ const componentArray = zod.z
 const configSchema = zod.z
     .object({
     entities: zod.z
-        .record(zod.z
+        .record(zod.z.string(), zod.z
         .object({
-        defaultLimit: zod.z
-            .number()
-            .int()
-            .positive()
-            .safe()
-            .optional()
-            .default(10),
-        defaultPageSize: zod.z
-            .number()
-            .int()
-            .positive()
-            .safe()
-            .optional()
-            .default(10),
+        defaultLimit: zod.z.number().int().positive().optional().default(10),
+        defaultPageSize: zod.z.number().int().positive().optional().default(10),
         shardBumps: zod.z
             .array(zod.z
             .object({
-            timestamp: zod.z.number().nonnegative().safe(),
+            timestamp: zod.z.number().int().nonnegative(),
             charBits: zod.z.number().int().min(1).max(5),
             chars: zod.z.number().int().min(0).max(40),
         })
@@ -79,7 +67,7 @@ const configSchema = zod.z
                 for (let i = 1; i < val.length; i++)
                     if (val[i].chars <= val[i - 1].chars)
                         ctx.addIssue({
-                            code: zod.z.ZodIssueCode.custom,
+                            code: 'custom',
                             message: `shardBump chars do not monotonically increase at timestamp ${val[i].timestamp.toString()}`,
                             path: [i],
                         });
@@ -93,14 +81,14 @@ const configSchema = zod.z
         .default({}),
     generatedProperties: zod.z
         .object({
-        sharded: zod.z.record(componentArray).optional().default({}),
-        unsharded: zod.z.record(componentArray).optional().default({}),
+        sharded: zod.z.record(zod.z.string(), componentArray).optional().default({}),
+        unsharded: zod.z.record(zod.z.string(), componentArray).optional().default({}),
     })
         .optional()
         .default({ sharded: {}, unsharded: {} }),
     hashKey: zod.z.string(),
     indexes: zod.z
-        .record(zod.z.object({
+        .record(zod.z.string(), zod.z.object({
         hashKey: zod.z.string().min(1),
         rangeKey: zod.z.string().min(1),
         projections: zod.z
@@ -112,15 +100,18 @@ const configSchema = zod.z
         .default({}),
     generatedKeyDelimiter: zod.z.string().regex(/\W+/).optional().default('|'),
     generatedValueDelimiter: zod.z.string().regex(/\W+/).optional().default('#'),
-    propertyTranscodes: zod.z.record(zod.z.string()).optional().default({}),
+    propertyTranscodes: zod.z.record(zod.z.string(), zod.z.string()).optional().default({}),
     rangeKey: zod.z.string(),
     shardKeyDelimiter: zod.z.string().regex(/\W+/).optional().default('!'),
-    throttle: zod.z.number().int().positive().safe().optional().default(10),
+    throttle: zod.z.number().int().positive().optional().default(10),
     transcodes: zod.z
-        .record(zod.z
+        .record(zod.z.string(), zod.z
         .object({
-        encode: zod.z.function().args(zod.z.any()).returns(zod.z.string()),
-        decode: zod.z.function().args(zod.z.string()).returns(zod.z.any()),
+        // Accept function shapes without relying on z.function()
+        // to avoid TS inference conflicts across Zod versions and
+        // to remain compatible with narrower parameter types.
+        encode: zod.z.custom((fn) => typeof fn === 'function'),
+        decode: zod.z.custom((fn) => typeof fn === 'function'),
     })
         .strict())
         .optional()
@@ -131,7 +122,7 @@ const configSchema = zod.z
     // validate no generated key delimiter collision
     if (data.generatedKeyDelimiter.includes(data.generatedValueDelimiter))
         ctx.addIssue({
-            code: zod.z.ZodIssueCode.custom,
+            code: 'custom',
             message: 'generatedKeyDelimiter contains generatedValueDelimiter',
             params: {
                 generatedKeyDelimiter: data.generatedKeyDelimiter,
@@ -141,7 +132,7 @@ const configSchema = zod.z
         });
     if (data.generatedKeyDelimiter.includes(data.shardKeyDelimiter))
         ctx.addIssue({
-            code: zod.z.ZodIssueCode.custom,
+            code: 'custom',
             message: 'generatedKeyDelimiter contains shardKeyDelimiter',
             params: {
                 generatedKeyDelimiter: data.generatedKeyDelimiter,
@@ -152,7 +143,7 @@ const configSchema = zod.z
     // validate no generated value delimiter collision
     if (data.generatedValueDelimiter.includes(data.generatedKeyDelimiter))
         ctx.addIssue({
-            code: zod.z.ZodIssueCode.custom,
+            code: 'custom',
             message: 'generatedValueDelimiter contains generatedKeyDelimiter',
             params: {
                 generatedValueDelimiter: data.generatedValueDelimiter,
@@ -162,7 +153,7 @@ const configSchema = zod.z
         });
     if (data.generatedValueDelimiter.includes(data.shardKeyDelimiter))
         ctx.addIssue({
-            code: zod.z.ZodIssueCode.custom,
+            code: 'custom',
             message: 'generatedValueDelimiter contains shardKeyDelimiter',
             params: {
                 generatedValueDelimiter: data.generatedValueDelimiter,
@@ -173,7 +164,7 @@ const configSchema = zod.z
     // validate no shard key delimiter collision
     if (data.shardKeyDelimiter.includes(data.generatedKeyDelimiter))
         ctx.addIssue({
-            code: zod.z.ZodIssueCode.custom,
+            code: 'custom',
             message: 'shardKeyDelimiter contains generatedKeyDelimiter',
             params: {
                 generatedKeyDelimiter: data.generatedKeyDelimiter,
@@ -183,7 +174,7 @@ const configSchema = zod.z
         });
     if (data.shardKeyDelimiter.includes(data.generatedValueDelimiter))
         ctx.addIssue({
-            code: zod.z.ZodIssueCode.custom,
+            code: 'custom',
             message: 'shardKeyDelimiter contains generatedValueDelimiter',
             params: {
                 generatedValueDelimiter: data.generatedValueDelimiter,
@@ -213,19 +204,17 @@ const configSchema = zod.z
     for (const [property, transcode] of Object.entries(data.propertyTranscodes))
         if (!transcodes.includes(transcode))
             ctx.addIssue({
-                code: zod.z.ZodIssueCode.invalid_enum_value,
-                options: transcodes,
+                code: 'custom',
+                message: `propertyTranscodes['${property}'] references unknown transcode '${transcode}'`,
                 path: ['propertyTranscodes', property],
-                received: transcode,
             });
     // Validate all sharded property elements are transcoded properties.
     for (const [property, elements] of Object.entries(data.generatedProperties.sharded))
         for (const element of elements)
             if (!transcodedProperties.includes(element))
                 ctx.addIssue({
-                    code: zod.z.ZodIssueCode.invalid_enum_value,
-                    options: transcodedProperties,
-                    received: element,
+                    code: 'custom',
+                    message: `generatedProperties.sharded['${property}'] contains non-transcoded element '${element}'`,
                     path: ['generatedProperties', 'sharded', property],
                 });
     // Validate all unsharded property elements are transcoded properties.
@@ -233,9 +222,8 @@ const configSchema = zod.z
         for (const element of elements)
             if (!transcodedProperties.includes(element))
                 ctx.addIssue({
-                    code: zod.z.ZodIssueCode.invalid_enum_value,
-                    options: transcodedProperties,
-                    received: element,
+                    code: 'custom',
+                    message: `generatedProperties.unsharded['${property}'] contains non-transcoded element '${element}'`,
                     path: ['generatedProperties', 'unsharded', property],
                 });
     // Validate indexes.
@@ -244,19 +232,24 @@ const configSchema = zod.z
         // Validate hash key is sharded.
         if (![data.hashKey, ...shardedKeys].includes(hashKey)) {
             ctx.addIssue({
-                code: zod.z.ZodIssueCode.invalid_enum_value,
-                options: [data.hashKey, ...shardedKeys],
+                code: 'custom',
+                message: `index '${indexKey}' hashKey '${hashKey}' must be one of [${[
+                    data.hashKey,
+                    ...shardedKeys,
+                ].join(', ')}]`,
                 path: ['indexes', indexKey, 'hashKey'],
-                received: hashKey,
             });
         }
         // Validate range key is unsharded or transcodable.
         if (![data.rangeKey, ...unshardedKeys, ...transcodedProperties].includes(rangeKey)) {
             ctx.addIssue({
-                code: zod.z.ZodIssueCode.invalid_enum_value,
-                options: [data.rangeKey, ...unshardedKeys],
+                code: 'custom',
+                message: `index '${indexKey}' rangeKey '${rangeKey}' must be one of [${[
+                    data.rangeKey,
+                    ...unshardedKeys,
+                    ...transcodedProperties,
+                ].join(', ')}]`,
                 path: ['indexes', indexKey, 'rangeKey'],
-                received: rangeKey,
             });
         }
         // Validate no index projections are keys.
@@ -271,7 +264,7 @@ const configSchema = zod.z
                     ...unshardedKeys,
                 ].includes(projection))
                     ctx.addIssue({
-                        code: zod.z.ZodIssueCode.custom,
+                        code: 'custom',
                         message: 'index projection is a key',
                         params: { projection },
                         path: ['indexes', indexKey, 'projections'],
@@ -282,18 +275,16 @@ const configSchema = zod.z
         // validate timestampProperty is a transcoded property.
         if (!transcodedProperties.includes(timestampProperty))
             ctx.addIssue({
-                code: zod.z.ZodIssueCode.invalid_enum_value,
-                options: transcodedProperties,
+                code: 'custom',
+                message: `entities['${entityToken}'].timestampProperty '${timestampProperty}' must be one of [${transcodedProperties.join(', ')}]`,
                 path: ['entities', entityToken, 'timestampProperty'],
-                received: timestampProperty,
             });
         // validate uniqueProperty is a transcoded property.
         if (!transcodedProperties.includes(uniqueProperty))
             ctx.addIssue({
-                code: zod.z.ZodIssueCode.invalid_enum_value,
-                options: transcodedProperties,
+                code: 'custom',
+                message: `entities['${entityToken}'].uniqueProperty '${uniqueProperty}' must be one of [${transcodedProperties.join(', ')}]`,
                 path: ['entities', entityToken, 'uniqueProperty'],
-                received: uniqueProperty,
             });
     }
 });

package/dist/cjs/EntityManager/addKeys.js

@@ -34,6 +34,7 @@ function addKeys(entityManager, entityToken, item, overwrite = false) {
                 if (encoded)
                     Object.assign(newItem, { [property]: encoded });
                 else
+                    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
                     delete newItem[property];
             }
         }

package/dist/cjs/EntityManager/decodeElement.js

@@ -24,7 +24,8 @@ function decodeElement(entityManager, element, value) {
         if (!value)
             return;
         const { propertyTranscodes, transcodes } = entityManager.config;
-        const decoded = transcodes[propertyTranscodes[element]].decode(value);
+        const decodeFn = transcodes[propertyTranscodes[element]].decode;
+        const decoded = decodeFn(value);
         entityManager.logger.debug('decoded entity element', {
             element,
             value,

package/dist/cjs/EntityManager/dehydratePageKeyMap.js

@@ -40,7 +40,9 @@ function dehydratePageKeyMap(entityManager, entityToken, pageKeyMap) {
         }
         // Extract, sort & validate indexs.
         const indexes = Object.keys(pageKeyMap).sort();
-        indexes.map((index) => validateIndexToken.validateIndexToken(entityManager, index));
+        indexes.map((index) => {
+            validateIndexToken.validateIndexToken(entityManager, index);
+        });
         // Extract & sort hash keys.
         const hashKeys = Object.keys(pageKeyMap[indexes[0]]);
         // Dehydrate page keys.

package/dist/cjs/EntityManager/encodeElement.js

@@ -21,8 +21,8 @@ function encodeElement(entityManager, element, item) {
         const value = item[element];
         if (value === undefined || [hashKey, rangeKey].includes(element))
             return value;
-        const encoded = transcodes[propertyTranscodes[element]].encode(item[element]) ||
-            undefined;
+        const encodeFn = transcodes[propertyTranscodes[element]].encode;
+        const encoded = encodeFn(item[element]) || undefined;
         entityManager.logger.debug('encoded entity element', {
             element,
             item,

package/dist/cjs/EntityManager/encodeGeneratedProperty.js

@@ -30,7 +30,7 @@ function encodeGeneratedProperty(entityManager, property, item) {
             ...(sharded
                 ? [item[entityManager.config.hashKey]]
                 : []),
-            ...elementMap.map(([element, value]) => [element, (value ?? '').toString()].join(entityManager.config.generatedValueDelimiter)),
+            ...elementMap.map(([element, value]) => [element, `${value ?? ''}`].join(entityManager.config.generatedValueDelimiter)),
         ].join(entityManager.config.generatedKeyDelimiter);
         entityManager.logger.debug('encoded generated property', {
             property,