@karmaniverous/entity-manager 6.14.3 → 7.0.0

package/dist/mjs/BaseEntityClient/BaseEntityClient.js

@@ -1,7 +1,7 @@
 /**
  * Base EntityClient class. Integrates {@link EntityManager | `EntityManager`} with injected logging & enhanced batch processing.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
  * @category EntityClient
  */

package/dist/mjs/BaseQueryBuilder/BaseQueryBuilder.js

@@ -3,9 +3,10 @@ import { mapValues } from 'radash';
 /**
  * Abstract base class supporting a fluent API for building a {@link ShardQueryMap | `ShardQueryMap`} using a database client.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines an {@link Config | `EntityManager configuration`}'s {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  * @typeParam EntityClient - {@link BaseEntityClient | `BaseEntityClient`} derived class instance.
  * @typeParam IndexParams - Database platform-specific, index-specific query parameters.
+ * @typeParam CF - Optional values-first config literal type for page key narrowing.
  *
  * @category QueryBuilder
  */
@@ -30,7 +31,7 @@ class BaseQueryBuilder {
      * @returns - The {@link ShardQueryMap | `ShardQueryMap`} object.
      */
     build() {
-        return mapValues(this.indexParamsMap, (indexConfig, indexToken) => this.getShardQueryFunction(indexToken));
+        return mapValues(this.indexParamsMap, (_indexConfig, indexToken) => this.getShardQueryFunction(indexToken));
     }
     async query(options) {
         const { entityClient: { entityManager }, entityToken, pageKeyMap, } = this;

package/dist/mjs/EntityManager/EntityManager.js

@@ -12,7 +12,7 @@ var _EntityManager_config;
  * The EntityManager class applies a configuration-driven sharded data model &
  * query strategy to NoSql data.
  *
- * @typeParam C - {@link ConfigMap | `ConfigMap`} that defines the configuration's {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeMap | `TranscodeMap`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
+ * @typeParam CC - {@link ConfigMap | `ConfigMap`} that defines the configuration's {@link EntityMap | `EntityMap`}, key properties, and {@link TranscodeRegistry | `TranscodeRegistry`}. If omitted, defaults to {@link BaseConfigMap | `BaseConfigMap`}.
  *
  * @remarks
  * While the {@link EntityManager.query | `query`} method is `public`, normally it should not be called directly. The `query` method is used by a platform-specific {@link BaseQueryBuilder.query | `QueryBuilder.query`} method to provide a fluent query API.

package/dist/mjs/EntityManager/createEntityManager.js

@@ -0,0 +1,40 @@
+import { EntityManager } from './EntityManager.js';
+
+/**
+ * Values-first factory that captures literal tokens and index names directly
+ * from the provided config value. Runtime config parsing/validation is
+ * unchanged (performed in the EntityManager constructor).
+ *
+ * @typeParam CC - Captured config input (values-first). Prefer `as const` and
+ *                 `satisfies` at call sites to preserve literal keys.
+ * @typeParam EM - EntityMap for the manager. Defaults to a minimal derived map
+ *                 from `CC.entitiesSchema` when present; otherwise falls back to EntityMap.
+ */
+function createEntityManager(config, logger = console) {
+    // Cast to the existing Config<C> shape for runtime parsing; Zod validation
+    // remains authoritative at construction time.
+    // Optional dev guardrail: cross-check entitiesSchema keys vs config.entities keys.
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (config && 'entitiesSchema' in config && config.entitiesSchema) {
+            const schemaKeys = Object.keys(config
+                .entitiesSchema ?? {});
+            const entitiesKeys = Object.keys(config
+                .entities ?? {});
+            const missingInEntities = schemaKeys.filter((k) => !entitiesKeys.includes(k));
+            const missingInSchema = entitiesKeys.filter((k) => !schemaKeys.includes(k));
+            if (missingInEntities.length || missingInSchema.length) {
+                logger.debug('entitiesSchema keys mismatch with config.entities', {
+                    missingInEntities,
+                    missingInSchema,
+                });
+            }
+        }
+    }
+    catch {
+        // Best-effort warning only; never block construction.
+    }
+    return new EntityManager(config, logger);
+}
+
+export { createEntityManager };

package/dist/mjs/EntityManager/decodeGeneratedProperty.js

@@ -5,14 +5,14 @@ import { decodeElement } from './decodeElement.js';
  * Decode a generated property value. Returns an {@link EntityItem | `EntityItem`}.
  *
  * @param entityManager - {@link EntityManager | `EntityManager`} instance.
- * @param entityToken - `entityManager.config.entities` key.
+ * @param entityToken - {@link Config.entities | `entityManager.config.entities`} key.
  * @param encoded - Encoded generated property value.
  *
  * @returns {@link EntityItem | `EntityItem`} object with updated properties decoded from `encoded`.
  *
  * @throws `Error` if `entityToken` is invalid.
  */
-function decodeGeneratedProperty(entityManager, encoded) {
+function decodeGeneratedProperty(entityManager, entityToken, encoded) {
     try {
         const { generatedKeyDelimiter, generatedValueDelimiter, hashKey, shardKeyDelimiter, } = entityManager.config;
         // Handle degenerate case.
@@ -37,6 +37,8 @@ function decodeGeneratedProperty(entityManager, encoded) {
             encoded,
             decoded,
         });
+        // entityToken used for typing only (ET-narrowed result).
+        void entityToken;
         return decoded;
     }
     catch (error) {

package/dist/mjs/EntityManager/dehydratePageKeyMap.js

@@ -38,8 +38,8 @@ function dehydratePageKeyMap(entityManager, entityToken, pageKeyMap) {
         }
         // Extract, sort & validate indexs.
         const indexes = Object.keys(pageKeyMap).sort();
-        indexes.map((index) => {
-            validateIndexToken(entityManager, index);
+        indexes.map((indexToken) => {
+            validateIndexToken(entityManager, indexToken);
         });
         // Extract & sort hash keys.
         const hashKeys = Object.keys(pageKeyMap[indexes[0]]);
@@ -53,11 +53,12 @@ function dehydratePageKeyMap(entityManager, entityToken, pageKeyMap) {
                     continue;
                 }
                 // Compose item from page key
-                const item = Object.entries(pageKeyMap[index][hashKey]).reduce((item, [property, value]) => {
+                const pk = pageKeyMap[index][hashKey];
+                const item = Object.entries(pk).reduce((item, [property, value]) => {
                     if (property === entityManager.config.rangeKey ||
                         property in entityManager.config.generatedProperties.sharded ||
                         property in entityManager.config.generatedProperties.unsharded)
-                        Object.assign(item, decodeGeneratedProperty(entityManager, value));
+                        Object.assign(item, decodeGeneratedProperty(entityManager, entityToken, value));
                     else
                         Object.assign(item, { [property]: value });
                     return item;

package/dist/mjs/EntityManager/getIndexComponents.js

@@ -15,7 +15,12 @@ function getIndexComponents(entityManager, indexToken) {
     validateIndexToken(entityManager, indexToken);
     const { hashKey, rangeKey, indexes } = entityManager.config;
     const { hashKey: indexHashKey, rangeKey: indexRangeKey } = indexes[indexToken];
-    return unique([hashKey, rangeKey, indexHashKey, indexRangeKey]);
+    return unique([
+        hashKey,
+        rangeKey,
+        indexHashKey,
+        indexRangeKey,
+    ]);
 }
 
 export { getIndexComponents };

package/dist/mjs/EntityManager/query.js

@@ -56,17 +56,20 @@ async function query(entityManager, options) {
             // items, which may be >> limit. Probably the way to fix entityManager is to limit the number of shards queried per
             // iteration in order to keep shardsQueried * pageSize > (limit - items.length) but only just.
             // TODO: Test for invalid characters (path delimiters) in index keys & shard key values.
+            // Build typed tasks (indexToken, hashKey, pageKey).
+            const tasks = [];
+            for (const [indexToken, indexPageKeys] of Object.entries(rehydratedPageKeyMap)) {
+                for (const [hashKey, pk] of Object.entries(indexPageKeys)) {
+                    tasks.push([indexToken, hashKey, pk]);
+                }
+            }
             // Query every shard on every index in pageKeyMap.
-            const shardQueryResults = await parallel(throttle, Object.entries(rehydratedPageKeyMap).flatMap(([indexToken, indexPageKeys]) => Object.entries(indexPageKeys).map(([hashKey, pageKey]) => [
-                indexToken,
-                hashKey,
-                pageKey,
-            ])), async ([indexToken, hashKey, pageKey]) => ({
+            const shardQueryResults = await parallel(throttle, tasks, async ([indexToken, hashKey, pageKey]) => ({
                 indexToken,
                 queryResult: await shardQueryMap[indexToken](hashKey, pageKey, pageSize),
                 hashKey,
             }));
-            // Reduce shardQueryResults & updateworkingRresult.
+            // Reduce shardQueryResults & update working result.
             workingResult = shardQueryResults.reduce(({ items, pageKeyMap }, { indexToken, queryResult, hashKey }) => {
                 Object.assign(rehydratedPageKeyMap[indexToken], {
                     [hashKey]: queryResult.pageKey,
@@ -76,12 +79,24 @@ async function query(entityManager, options) {
                     pageKeyMap,
                 };
             }, workingResult);
-        } while (
-        // Repeat while pages remain & limit is not reached.
-        Object.values(workingResult.pageKeyMap).some((indexPageKeys) => Object.values(indexPageKeys).some((pageKey) => pageKey !== undefined)) &&
-            workingResult.items.length < limit);
+            // Repeat while pages remain & limit is not reached.
+            let pagesRemain = false;
+            for (const idx of Object.keys(workingResult.pageKeyMap)) {
+                const inner = workingResult.pageKeyMap[idx];
+                for (const h of Object.keys(inner)) {
+                    if (inner[h] !== undefined) {
+                        pagesRemain = true;
+                        break;
+                    }
+                }
+                if (pagesRemain)
+                    break;
+            }
+            if (!pagesRemain)
+                break;
+        } while (workingResult.items.length < limit);
         // Dedupe & sort working result.
-        workingResult.items = sort(unique(workingResult.items, (item) => item[entityManager.config.entities[entityToken]
+        workingResult.items = sort(unique(workingResult.items, (i) => i[entityManager.config.entities[entityToken]
             .uniqueProperty].toString()), sortOrder);
         const result = {
             count: workingResult.items.length,

package/dist/mjs/EntityManager/rehydratePageKeyMap.js

@@ -36,7 +36,7 @@ function rehydratePageKeyMap(entityManager, entityToken, indexTokens, item, dehy
         // Validate indexTokens populated.
         if (!indexTokens.length)
             throw new Error('indexTokens empty');
-        // Validate indexTokens exist.
+        // Validate indexTokens exist and capture hashKeys.
         const hashKeys = unique(indexTokens.map((indexToken) => {
             validateIndexToken(entityManager, indexToken);
             return entityManager.config.indexes[indexToken].hashKey;
@@ -50,7 +50,10 @@ function rehydratePageKeyMap(entityManager, entityToken, indexTokens, item, dehy
         });
         // Shortcut empty dehydrated.
         if (dehydrated && !dehydrated.length)
-            return [hashKeyToken, {}];
+            return [
+                hashKeyToken,
+                {},
+            ];
         // Get hash key space.
         const hashKeySpace = getHashKeySpace(entityManager, entityToken, hashKeyToken, item, timestampFrom, timestampTo);
         // Default dehydrated.
@@ -66,7 +69,7 @@ function rehydratePageKeyMap(entityManager, entityToken, indexTokens, item, dehy
             if (!dehydratedIndexPageKeyMaps[i])
                 return;
             let pageKeyItem = {
-                ...decodeGeneratedProperty(entityManager, hashKey),
+                ...decodeGeneratedProperty(entityManager, entityToken, hashKey),
                 ...rehydrateIndexItem(entityManager, entityToken, index, dehydratedIndexPageKeyMaps[i]),
             };
             pageKeyItem = updateItemRangeKey(entityManager, entityToken, pageKeyItem);

package/dist/mjs/index.js

@@ -1,4 +1,5 @@
 export { BaseEntityClient } from './BaseEntityClient/BaseEntityClient.js';
 export { BaseQueryBuilder } from './BaseQueryBuilder/BaseQueryBuilder.js';
+export { createEntityManager } from './EntityManager/createEntityManager.js';
 export { EntityManager } from './EntityManager/EntityManager.js';
 export { configSchema } from './EntityManager/ParsedConfig.js';

package/package.json

@@ -1,135 +1,132 @@
-{
-  "author": "Jason Williscroft",
-  "bugs": {
-    "url": "https://github.com/karmaniverous/entity-manager/issues"
-  },
-  "dependencies": {
-    "@karmaniverous/batch-process": "^0.1.0",
-    "@karmaniverous/entity-tools": "^0.6.9",
-    "@karmaniverous/string-utilities": "^0.2.1",
-    "lz-string": "^1.5.0",
-    "radash": "^12.1.1",
-    "string-hash": "^1.1.3",
-    "zod": "^4.1.12"
-  },
-  "description": "Rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.",
-  "devDependencies": {
-    "@dotenvx/dotenvx": "^1.51.1",
-    "@eslint/js": "^9.39.1",
-    "@faker-js/faker": "^10.1.0",
-    "@karmaniverous/mock-db": "^0.3.5",
-    "@rollup/plugin-alias": "^6.0.0",
-    "@rollup/plugin-commonjs": "^29.0.0",
-    "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^16.0.3",
-    "@rollup/plugin-strip": "^3.0.4",
-    "@rollup/plugin-typescript": "^12.3.0",
-    "@types/node": "^24.10.0",
-    "@types/string-hash": "^1.1.3",
-    "auto-changelog": "^2.5.0",
-    "cross-env": "^10.1.0",
-    "eslint": "^9.39.1",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.4",
-    "eslint-plugin-simple-import-sort": "^12.1.1",
-    "eslint-plugin-tsdoc": "^0.4.0",
-    "knip": "^5.67.1",
-    "lefthook": "^2.0.2",
-    "prettier": "^3.6.2",
-    "release-it": "^19.0.5",
-    "rimraf": "^6.1.0",
-    "rollup": "^4.52.5",
-    "rollup-plugin-dts": "^6.2.3",
-    "tsd": "^0.33.0",
-    "tslib": "^2.8.1",
-    "typedoc": "^0.28.14",
-    "typedoc-plugin-mdn-links": "^5.0.10",
-    "typedoc-plugin-replace-text": "^4.2.0",
-    "typedoc-plugin-zod": "^1.4.3",
-    "@vitest/coverage-v8": "^4.0.6",
-    "@vitest/eslint-plugin": "^1.4.0",
-    "vitest": "^4.0.6",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.46.3"
-  },
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/mjs/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/cjs/index.js"
-      }
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "homepage": "https://github.com/karmaniverous/entity-manager#readme",
-  "keywords": [
-    "dynamo-db",
-    "sharding"
-  ],
-  "license": "BSD-3-Clause",
-  "main": "dist/cjs/index.js",
-  "module": "dist/mjs/index.js",
-  "name": "@karmaniverous/entity-manager",
-  "publishConfig": {
-    "access": "public"
-  },
-  "release-it": {
-    "git": {
-      "changelog": "npx auto-changelog --stdout --commit-limit false --unreleased --template https://raw.githubusercontent.com/release-it/release-it/main/templates/changelog-compact.hbs",
-      "commitMessage": "chore: release v${version}",
-      "requireBranch": "main"
-    },
-    "github": {
-      "release": true
-    },
-    "hooks": {
-      "after:init": [
-        "npm run lint",
-        "npm run test",
-        "npm run knip",
-        "npm run build"
-      ],
-      "before:npm:release": [
-        "npx auto-changelog -p",
-        "npm run docs",
-        "git add -A"
-      ],
-      "after:release": [
-        "git switch -c release/${version}",
-        "git push -u origin release/${version}",
-        "git switch ${branchName}"
-      ]
-    },
-    "npm": {
-      "publish": true
-    }
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/karmaniverous/entity-manager.git"
-  },
-  "scripts": {
-    "build": "rimraf dist && rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",
-    "changelog": "auto-changelog",
-    "docs": "typedoc",
-    "knip": "knip",
-    "lint": "eslint .",
-    "lint:fix": "npm run lint -- --fix .",
-    "release": "dotenvx run -f .env.local -- release-it",
-    "release:pre": "npm run release -- --no-git.requireBranch --github.prerelease --preRelease",
-    "test": "vitest --run --silent",
-    "typecheck": "tsc && tsd"
-  },
-  "tsd": {
-    "directory": "test/types"
-  },
-  "type": "module",
-  "types": "dist/index.d.ts",
-  "version": "6.14.3"
-}
+{
+  "author": "Jason Williscroft",
+  "bugs": {
+    "url": "https://github.com/karmaniverous/entity-manager/issues"
+  },
+  "dependencies": {
+    "@karmaniverous/batch-process": "^0.1.0",
+    "@karmaniverous/entity-tools": "^0.7.1",
+    "@karmaniverous/string-utilities": "^0.2.1",
+    "lz-string": "^1.5.0",
+    "radash": "^12.1.1",
+    "string-hash": "^1.1.3",
+    "zod": "^4.1.12"
+  },
+  "description": "Rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.",
+  "devDependencies": {
+    "@dotenvx/dotenvx": "^1.51.1",
+    "@eslint/js": "^9.39.1",
+    "@faker-js/faker": "^10.1.0",
+    "@karmaniverous/mock-db": "^0.4.0",
+    "@rollup/plugin-alias": "^6.0.0",
+    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-strip": "^3.0.4",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^24.10.1",
+    "@types/string-hash": "^1.1.3",
+    "auto-changelog": "^2.5.0",
+    "cross-env": "^10.1.0",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "eslint-plugin-tsdoc": "^0.5.0",
+    "knip": "^5.69.1",
+    "lefthook": "^2.0.4",
+    "prettier": "^3.6.2",
+    "release-it": "^19.0.6",
+    "rimraf": "^6.1.0",
+    "rollup": "^4.53.2",
+    "rollup-plugin-dts": "^6.2.3",
+    "tsd": "^0.33.0",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.28.14",
+    "typedoc-plugin-mdn-links": "^5.0.10",
+    "typedoc-plugin-replace-text": "^4.2.0",
+    "typedoc-plugin-zod": "^1.4.3",
+    "@vitest/coverage-v8": "^4.0.9",
+    "@vitest/eslint-plugin": "^1.4.3",
+    "vitest": "^4.0.9",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.4"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/mjs/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "homepage": "https://github.com/karmaniverous/entity-manager#readme",
+  "keywords": [
+    "dynamo-db",
+    "sharding"
+  ],
+  "license": "BSD-3-Clause",
+  "main": "dist/cjs/index.js",
+  "module": "dist/mjs/index.js",
+  "name": "@karmaniverous/entity-manager",
+  "publishConfig": {
+    "access": "public"
+  },
+  "release-it": {
+    "git": {
+      "changelog": "npx auto-changelog --stdout --commit-limit false --unreleased --template https://raw.githubusercontent.com/release-it/release-it/main/templates/changelog-compact.hbs",
+      "commitMessage": "chore: release v${version}",
+      "requireBranch": "main"
+    },
+    "github": {
+      "release": true
+    },
+    "hooks": {
+      "after:init": [
+        "npm run lint",
+        "npm run test",
+        "npm run knip",
+        "npm run build"
+      ],
+      "before:npm:release": [
+        "npx auto-changelog -p",
+        "npm run docs",
+        "git add -A"
+      ],
+      "after:release": [
+        "git switch -c release/${version}",
+        "git push -u origin release/${version}",
+        "git switch ${branchName}"
+      ]
+    },
+    "npm": {
+      "publish": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/karmaniverous/entity-manager.git"
+  },
+  "scripts": {
+    "build": "rimraf dist && rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",
+    "changelog": "auto-changelog",
+    "docs": "typedoc",
+    "knip": "knip",
+    "lint": "eslint .",
+    "lint:fix": "npm run lint -- --fix .",
+    "release": "dotenvx run -f .env.local -- release-it",
+    "release:pre": "npm run release -- --no-git.requireBranch --github.prerelease --preRelease",
+    "test": "vitest --run --silent",
+    "typecheck": "tsc && tsd"
+  },
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "version": "7.0.0"
+}