@karmaniverous/entity-manager 6.13.3 → 6.14.1

package/dist/mjs/{ParsedConfig.js → EntityManager/ParsedConfig.js}

@@ -8,7 +8,7 @@ const validateArrayUnique = (arr, ctx, identity = (item) => item, path = []) =>
     for (const [element, count] of Object.entries(counts)) {
         if (count > 1)
             ctx.addIssue({
-                code: z.ZodIssueCode.custom,
+                code: 'custom',
                 message: `duplicate array element`,
                 params: { element },
                 path,
@@ -19,7 +19,7 @@ const validateKeysExclusive = (keys, label, ref, ctx) => {
     const intersection = keys.filter((key) => ref.includes(key));
     if (intersection.length)
         ctx.addIssue({
-            code: z.ZodIssueCode.custom,
+            code: 'custom',
             message: `${label} key collision: ${intersection.toString()}`,
         });
 };
@@ -30,26 +30,14 @@ const componentArray = z
 const configSchema = z
     .object({
     entities: z
-        .record(z
+        .record(z.string(), z
         .object({
-        defaultLimit: z
-            .number()
-            .int()
-            .positive()
-            .safe()
-            .optional()
-            .default(10),
-        defaultPageSize: z
-            .number()
-            .int()
-            .positive()
-            .safe()
-            .optional()
-            .default(10),
+        defaultLimit: z.number().int().positive().optional().default(10),
+        defaultPageSize: z.number().int().positive().optional().default(10),
         shardBumps: z
             .array(z
             .object({
-            timestamp: z.number().nonnegative().safe(),
+            timestamp: z.number().int().nonnegative(),
             charBits: z.number().int().min(1).max(5),
             chars: z.number().int().min(0).max(40),
         })
@@ -77,7 +65,7 @@ const configSchema = z
                 for (let i = 1; i < val.length; i++)
                     if (val[i].chars <= val[i - 1].chars)
                         ctx.addIssue({
-                            code: z.ZodIssueCode.custom,
+                            code: 'custom',
                             message: `shardBump chars do not monotonically increase at timestamp ${val[i].timestamp.toString()}`,
                             path: [i],
                         });
@@ -91,14 +79,14 @@ const configSchema = z
         .default({}),
     generatedProperties: z
         .object({
-        sharded: z.record(componentArray).optional().default({}),
-        unsharded: z.record(componentArray).optional().default({}),
+        sharded: z.record(z.string(), componentArray).optional().default({}),
+        unsharded: z.record(z.string(), componentArray).optional().default({}),
     })
         .optional()
         .default({ sharded: {}, unsharded: {} }),
     hashKey: z.string(),
     indexes: z
-        .record(z.object({
+        .record(z.string(), z.object({
         hashKey: z.string().min(1),
         rangeKey: z.string().min(1),
         projections: z
@@ -110,15 +98,18 @@ const configSchema = z
         .default({}),
     generatedKeyDelimiter: z.string().regex(/\W+/).optional().default('|'),
     generatedValueDelimiter: z.string().regex(/\W+/).optional().default('#'),
-    propertyTranscodes: z.record(z.string()).optional().default({}),
+    propertyTranscodes: z.record(z.string(), z.string()).optional().default({}),
     rangeKey: z.string(),
     shardKeyDelimiter: z.string().regex(/\W+/).optional().default('!'),
-    throttle: z.number().int().positive().safe().optional().default(10),
+    throttle: z.number().int().positive().optional().default(10),
     transcodes: z
-        .record(z
+        .record(z.string(), z
         .object({
-        encode: z.function().args(z.any()).returns(z.string()),
-        decode: z.function().args(z.string()).returns(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: z.custom((fn) => typeof fn === 'function'),
+        decode: z.custom((fn) => typeof fn === 'function'),
     })
         .strict())
         .optional()
@@ -129,7 +120,7 @@ const configSchema = z
     // validate no generated key delimiter collision
     if (data.generatedKeyDelimiter.includes(data.generatedValueDelimiter))
         ctx.addIssue({
-            code: z.ZodIssueCode.custom,
+            code: 'custom',
             message: 'generatedKeyDelimiter contains generatedValueDelimiter',
             params: {
                 generatedKeyDelimiter: data.generatedKeyDelimiter,
@@ -139,7 +130,7 @@ const configSchema = z
         });
     if (data.generatedKeyDelimiter.includes(data.shardKeyDelimiter))
         ctx.addIssue({
-            code: z.ZodIssueCode.custom,
+            code: 'custom',
             message: 'generatedKeyDelimiter contains shardKeyDelimiter',
             params: {
                 generatedKeyDelimiter: data.generatedKeyDelimiter,
@@ -150,7 +141,7 @@ const configSchema = z
     // validate no generated value delimiter collision
     if (data.generatedValueDelimiter.includes(data.generatedKeyDelimiter))
         ctx.addIssue({
-            code: z.ZodIssueCode.custom,
+            code: 'custom',
             message: 'generatedValueDelimiter contains generatedKeyDelimiter',
             params: {
                 generatedValueDelimiter: data.generatedValueDelimiter,
@@ -160,7 +151,7 @@ const configSchema = z
         });
     if (data.generatedValueDelimiter.includes(data.shardKeyDelimiter))
         ctx.addIssue({
-            code: z.ZodIssueCode.custom,
+            code: 'custom',
             message: 'generatedValueDelimiter contains shardKeyDelimiter',
             params: {
                 generatedValueDelimiter: data.generatedValueDelimiter,
@@ -171,7 +162,7 @@ const configSchema = z
     // validate no shard key delimiter collision
     if (data.shardKeyDelimiter.includes(data.generatedKeyDelimiter))
         ctx.addIssue({
-            code: z.ZodIssueCode.custom,
+            code: 'custom',
             message: 'shardKeyDelimiter contains generatedKeyDelimiter',
             params: {
                 generatedKeyDelimiter: data.generatedKeyDelimiter,
@@ -181,7 +172,7 @@ const configSchema = z
         });
     if (data.shardKeyDelimiter.includes(data.generatedValueDelimiter))
         ctx.addIssue({
-            code: z.ZodIssueCode.custom,
+            code: 'custom',
             message: 'shardKeyDelimiter contains generatedValueDelimiter',
             params: {
                 generatedValueDelimiter: data.generatedValueDelimiter,
@@ -211,19 +202,17 @@ const configSchema = z
     for (const [property, transcode] of Object.entries(data.propertyTranscodes))
         if (!transcodes.includes(transcode))
             ctx.addIssue({
-                code: 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: 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.
@@ -231,9 +220,8 @@ const configSchema = z
         for (const element of elements)
             if (!transcodedProperties.includes(element))
                 ctx.addIssue({
-                    code: 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.
@@ -242,19 +230,24 @@ const configSchema = z
         // Validate hash key is sharded.
         if (![data.hashKey, ...shardedKeys].includes(hashKey)) {
             ctx.addIssue({
-                code: 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: 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.
@@ -269,7 +262,7 @@ const configSchema = z
                     ...unshardedKeys,
                 ].includes(projection))
                     ctx.addIssue({
-                        code: z.ZodIssueCode.custom,
+                        code: 'custom',
                         message: 'index projection is a key',
                         params: { projection },
                         path: ['indexes', indexKey, 'projections'],
@@ -280,18 +273,16 @@ const configSchema = z
         // validate timestampProperty is a transcoded property.
         if (!transcodedProperties.includes(timestampProperty))
             ctx.addIssue({
-                code: 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: 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/mjs/{addKeys.js → EntityManager/addKeys.js}

@@ -32,6 +32,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/mjs/{decodeElement.js → EntityManager/decodeElement.js}

@@ -22,7 +22,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/mjs/{dehydratePageKeyMap.js → EntityManager/dehydratePageKeyMap.js}

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

package/dist/mjs/{encodeElement.js → EntityManager/encodeElement.js}

@@ -19,8 +19,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/mjs/{encodeGeneratedProperty.js → EntityManager/encodeGeneratedProperty.js}

@@ -28,7 +28,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,

package/dist/mjs/EntityManager/getPrimaryKey.js

@@ -0,0 +1,23 @@
+import { pick } from 'radash';
+import { addKeys } from './addKeys.js';
+
+/**
+ * Convert an {@link EntityItem | `EntityItem`} into an {@link EntityKey | `EntityKey`}.
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param entityToken - {@link Config | `Config`} `entities` key.
+ * @param item - {@link EntityItem | `EntityItem`} object.
+ * @param overwrite - Overwrite existing properties (default `false`).
+ *
+ * @returns {@link EntityKey | `EntityKey`} extracted from shallow clone of `item` with updated properties.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ */
+function getPrimaryKey(entityManager, entityToken, item, overwrite = false) {
+    const { hashKey, rangeKey } = entityManager.config;
+    return pick(!overwrite && item[hashKey] && item[rangeKey]
+        ? item
+        : addKeys(entityManager, entityToken, item, overwrite), [entityManager.config.hashKey, entityManager.config.rangeKey]);
+}
+
+export { getPrimaryKey };

package/dist/mjs/{rehydratePageKeyMap.js → EntityManager/rehydratePageKeyMap.js}

@@ -45,7 +45,9 @@ function rehydratePageKeyMap(entityManager, entityToken, indexTokens, item, dehy
         if (hashKeys.length > 1)
             throw new Error('inconsistent hashKeys');
         const [hashKeyToken] = hashKeys;
-        indexTokens.map((index) => validateIndexToken(entityManager, index));
+        indexTokens.map((index) => {
+            validateIndexToken(entityManager, index);
+        });
         // Shortcut empty dehydrated.
         if (dehydrated && !dehydrated.length)
             return [hashKeyToken, {}];

package/dist/mjs/{removeKeys.js → EntityManager/removeKeys.js}

@@ -15,14 +15,16 @@ function removeKeys(entityManager, entityToken, item) {
     try {
         // Validate params.
         validateEntityToken(entityManager, entityToken);
-        // Delete hash & range keys.
-        const newItem = { ...item };
-        delete newItem[entityManager.config.hashKey];
-        delete newItem[entityManager.config.rangeKey];
-        // Delete generated properties.
-        const { sharded, unsharded } = entityManager.config.generatedProperties;
-        for (const property in { ...sharded, ...unsharded })
-            delete newItem[property];
+        // Build a set of keys to strip (hash, range, and all generated properties).
+        const { hashKey, rangeKey, generatedProperties: { sharded, unsharded }, } = entityManager.config;
+        const keysToStrip = new Set([
+            hashKey,
+            rangeKey,
+            ...Object.keys(sharded),
+            ...Object.keys(unsharded),
+        ]);
+        // Create a shallow copy of item omitting the keys above (no delete operator).
+        const newItem = Object.fromEntries(Object.entries(item).filter(([key]) => !keysToStrip.has(key)));
         entityManager.logger.debug('stripped entity item generated properties', {
             entityToken,
             item,

package/dist/mjs/{updateItemHashKey.js → EntityManager/updateItemHashKey.js}

@@ -40,12 +40,15 @@ function updateItemHashKey(entityManager, entityToken, item, overwrite = false)
         if (chars) {
             // Radix is the numerical base of the shardKey.
             const radix = 2 ** charBits;
+            // Compute the full shard space for this bump. Use radix ** chars to ensure
+            // all placeholders are utilized (e.g., chars=2, charBits=2 => 16 combos).
+            const space = radix ** chars;
             // Get item unique property & validate.
             const uniqueId = item[entityManager.config.entities[entityToken]
                 .uniqueProperty];
             if (isNil(uniqueId))
                 throw new Error(`missing item unique property`);
-            hashKey += (stringHash(uniqueId.toString()) % (chars * radix))
+            hashKey += (stringHash(uniqueId) % space)
                 .toString(radix)
                 .padStart(chars, '0');
         }

package/dist/mjs/index.js

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

package/package.json

@@ -5,58 +5,52 @@
   },
   "dependencies": {
     "@karmaniverous/batch-process": "^0.1.0",
-    "@karmaniverous/entity-tools": "^0.6.6",
+    "@karmaniverous/entity-tools": "^0.6.9",
     "@karmaniverous/string-utilities": "^0.2.1",
     "lz-string": "^1.5.0",
-    "radash": "^12.1.0",
+    "radash": "^12.1.1",
     "string-hash": "^1.1.3",
-    "zod": "^3.23.8"
+    "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.23.0",
-    "@eslint/js": "^9.14.0",
-    "@faker-js/faker": "^9.2.0",
-    "@karmaniverous/mock-db": "^0.3.4",
-    "@rollup/plugin-alias": "^5.1.1",
-    "@rollup/plugin-commonjs": "^28.0.1",
+    "@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": "^15.3.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-strip": "^3.0.4",
-    "@rollup/plugin-typescript": "^12.1.1",
-    "@types/chai": "^5.0.1",
-    "@types/eslint__js": "^8.42.3",
-    "@types/eslint-config-prettier": "^6.11.3",
-    "@types/eslint-plugin-mocha": "^10.4.0",
-    "@types/mocha": "^10.0.9",
-    "@types/node": "^22.9.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^24.10.0",
     "@types/string-hash": "^1.1.3",
     "auto-changelog": "^2.5.0",
-    "chai": "^5.1.2",
-    "eslint": "^9.14.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-mocha": "^10.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.3.0",
-    "jsdom-global": "^3.0.2",
-    "knip": "^5.37.0",
-    "lefthook": "^1.8.2",
-    "mocha": "^10.8.2",
-    "nyc": "^17.1.0",
-    "prettier": "^3.3.3",
-    "release-it": "^17.10.0",
-    "rimraf": "^6.0.1",
-    "rollup": "^4.26.0",
-    "rollup-plugin-dts": "^6.1.1",
-    "source-map-support": "^0.5.21",
-    "ts-node": "^10.9.2",
+    "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.26.11",
-    "typedoc-plugin-mdn-links": "^3.3.7",
-    "typedoc-plugin-replace-text": "^4.0.0",
-    "typedoc-plugin-zod": "^1.2.1",
-    "typescript": "^5.6.3",
-    "typescript-eslint": "^8.14.0"
+    "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": {
     ".": {
@@ -122,15 +116,20 @@
   },
   "scripts": {
     "build": "rimraf dist && rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",
+    "changelog": "auto-changelog",
     "docs": "typedoc",
     "knip": "knip",
-    "lint": "eslint src/** && prettier -c src",
-    "lint:fix": "eslint --fix src/** && prettier --write src",
+    "lint": "eslint .",
+    "lint:fix": "npm run lint -- --fix .",
     "release": "dotenvx run -f .env.local -- release-it",
-    "release:pre": "dotenvx run -f .env.local -- release-it --no-git.requireBranch --github.prerelease --preRelease",
-    "test": "dotenvx run --quiet --log-level=LOG_LEVEL=debug -- nyc mocha"
+    "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.13.3"
+  "version": "6.14.1"
 }