@karmaniverous/entity-manager 6.4.9 → 6.5.0

package/dist/cjs/ParsedConfig.js

@@ -23,6 +23,10 @@ const validateKeyExclusive = (key, label, ref, ctx) => {
             message: `${label} '${key}' is not exclusive`,
         });
 };
+const componentArray = zod.z
+    .array(zod.z.string().min(1))
+    .nonempty()
+    .superRefine(validateArrayUnique);
 const configSchema = zod.z
     .object({
     entities: zod.z
@@ -46,10 +50,7 @@ const configSchema = zod.z
             .record(zod.z
             .object({
             atomic: zod.z.boolean().optional().default(false),
-            elements: zod.z
-                .array(zod.z.string().min(1))
-                .nonempty()
-                .superRefine(validateArrayUnique),
+            elements: componentArray,
             sharded: zod.z.boolean().optional().default(false),
         })
             .optional())
@@ -57,10 +58,10 @@ const configSchema = zod.z
             .default({}),
         elementTranscodes: zod.z.record(zod.z.string()).optional().default({}),
         indexes: zod.z
-            .record(zod.z
-            .array(zod.z.string().min(1))
-            .nonempty()
-            .superRefine(validateArrayUnique))
+            .record(zod.z.object({
+            components: componentArray,
+            projections: componentArray.optional(),
+        }))
             .optional()
             .default({}),
         shardBumps: zod.z
@@ -209,18 +210,42 @@ const configSchema = zod.z
                         ],
                         received: element,
                     });
-        // validate all ungenerated entity index components have a corresponding entity element type.
+        // validate indexes.
         const generatedProperties = Object.keys(entity.generated);
-        for (const [indexKey, index] of Object.entries(entity.indexes))
-            for (const component of index)
+        for (const [indexKey, index] of Object.entries(entity.indexes)) {
+            // validate all ungenerated entity index components have a corresponding entity element type
+            for (const component of index.components)
                 if (![data.hashKey, data.rangeKey, ...generatedProperties].includes(component) &&
                     !typedElements.includes(component))
                     ctx.addIssue({
                         code: zod.z.ZodIssueCode.invalid_enum_value,
                         options: typedElements,
-                        path: ['entities', entityToken, 'indexes', indexKey],
+                        path: [
+                            'entities',
+                            entityToken,
+                            'indexes',
+                            indexKey,
+                            'components',
+                        ],
                         received: component,
                     });
+            // validate no index projections are index components, hashKey, or rangeKey
+            if (index.projections)
+                for (const projection of index.projections) {
+                    if ([data.hashKey, data.rangeKey, ...index.components].includes(projection))
+                        ctx.addIssue({
+                            code: zod.z.ZodIssueCode.custom,
+                            message: 'index projection is an index component, hash key, or range key',
+                            path: [
+                                'entities',
+                                entityToken,
+                                'indexes',
+                                indexKey,
+                                'projections',
+                            ],
+                        });
+                }
+        }
     }
 });
 

package/dist/cjs/index.js

@@ -2,17 +2,8 @@
 
 var conditionalize = require('./conditionalize.js');
 var EntityManager = require('./EntityManager.js');
-var entityTools = require('@karmaniverous/entity-tools');
 
 
 
 exports.conditionalize = conditionalize.conditionalize;
 exports.EntityManager = EntityManager.EntityManager;
-Object.defineProperty(exports, "defaultTranscodes", {
-	enumerable: true,
-	get: function () { return entityTools.defaultTranscodes; }
-});
-Object.defineProperty(exports, "isNil", {
-	enumerable: true,
-	get: function () { return entityTools.isNil; }
-});

package/dist/cjs/rehydratePageKeyMap.js

@@ -51,7 +51,8 @@ function rehydratePageKeyMap(entityManager, dehydrated, entityToken, indexTokens
                 ...rehydrateIndexItem.rehydrateIndexItem(entityManager, dehydratedIndexPageKeyMaps[i], entityToken, index, [entityManager.config.hashKey]),
             };
             item = updateItemRangeKey.updateItemRangeKey(entityManager, item, entityToken);
-            return radash.zipToObject(entityManager.config.entities[entityToken].indexes[index], (component) => entityManager.config.entities[entityToken].generated[component]
+            return radash.zipToObject(entityManager.config.entities[entityToken].indexes[index]
+                .components, (component) => entityManager.config.entities[entityToken].generated[component]
                 ? encodeGeneratedProperty.encodeGeneratedProperty(entityManager, item, entityToken, component)
                 : item[component]);
         }));

package/dist/cjs/unwrapIndex.js

@@ -21,7 +21,7 @@ function unwrapIndex(entityManager, entityToken, indexToken) {
         validateEntityIndexToken.validateEntityIndexToken(entityManager, entityToken, indexToken);
         const generated = entityManager.config.entities[entityToken].generated;
         const generatedKeys = Object.keys(radash.shake(generated));
-        return entityManager.config.entities[entityToken].indexes[indexToken]
+        return entityManager.config.entities[entityToken].indexes[indexToken].components
             .map((component) => component === entityManager.config.hashKey
             ? entityManager.config.hashKey
             : component === entityManager.config.rangeKey

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import { Entity, Exactify, TranscodeMap, PropertiesOfType, TranscodableProperties, Transcodes, DefaultTranscodeMap, SortOrder } from '@karmaniverous/entity-tools';
-export { DefaultTranscodeMap, Entity, Exactify, Nil, PartialTranscodable, PropertiesNotOfType, PropertiesOfType, SortOrder, TranscodableProperties, TranscodeMap, Transcodes, defaultTranscodes, isNil } from '@karmaniverous/entity-tools';
 import { z } from 'zod';
 
 /**
@@ -81,6 +80,19 @@ interface ShardBump {
      */
     chars: number;
 }
+/**
+ * Returns a Config entity index components 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}.
+
+ * @category Config
+ * @protected
+ */
+type ConfigEntityIndexComponents<EntityToken extends keyof Exactify<M>, M extends EntityMap, HashKey extends string, RangeKey extends string, T extends TranscodeMap> = (TranscodableProperties<M[EntityToken], T> | PropertiesOfType<M[EntityToken], never> | HashKey | RangeKey)[];
 /**
  * Returns a Config entity type.
  *
@@ -176,7 +188,10 @@ type ConfigEntity<EntityToken extends keyof Exactify<M>, M extends EntityMap, Ha
      *
      * 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)[]>;
+    indexes?: Record<string, {
+        components: ConfigEntityIndexComponents<EntityToken, M, HashKey, RangeKey, T>;
+        projections?: (keyof M[EntityToken])[];
+    }>;
     /**
      * An array of {@link ShardBump | `ShardBump`} objects representing the {@link Entity | `Entity`}'s sharding strategy.
      *
@@ -357,9 +372,7 @@ type ItemMap<M extends EntityMap, HashKey extends string = 'hashKey', RangeKey e
         [P in keyof Exactify<M[EntityToken]>]: [
             NonNullable<M[EntityToken][P]>
         ] extends [never] ? string : M[EntityToken][P];
-    } & {
-        [P in HashKey | RangeKey]?: string;
-    }>;
+    } & Partial<Record<HashKey | RangeKey, string>>>;
 };
 
 declare const configSchema: z.ZodEffects<z.ZodObject<{
@@ -380,7 +393,16 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
             sharded?: boolean | undefined;
         }>>>>>;
         elementTranscodes: 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[]]>>>>;
+        indexes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            components: z.ZodEffects<z.ZodArray<z.ZodString, "atleastone">, [string, ...string[]], [string, ...string[]]>;
+            projections: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodString, "atleastone">, [string, ...string[]], [string, ...string[]]>>;
+        }, "strip", z.ZodTypeAny, {
+            components: [string, ...string[]];
+            projections?: [string, ...string[]] | undefined;
+        }, {
+            components: [string, ...string[]];
+            projections?: [string, ...string[]] | undefined;
+        }>>>>;
         shardBumps: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
             timestamp: z.ZodNumber;
             charBits: z.ZodNumber;
@@ -424,7 +446,10 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         defaultLimit: number;
         defaultPageSize: number;
         elementTranscodes: Record<string, string>;
-        indexes: Record<string, [string, ...string[]]>;
+        indexes: Record<string, {
+            components: [string, ...string[]];
+            projections?: [string, ...string[]] | undefined;
+        }>;
         shardBumps: {
             timestamp: number;
             charBits: number;
@@ -443,7 +468,10 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
         elementTranscodes?: Record<string, string> | undefined;
-        indexes?: Record<string, [string, ...string[]]> | undefined;
+        indexes?: Record<string, {
+            components: [string, ...string[]];
+            projections?: [string, ...string[]] | undefined;
+        }> | undefined;
         shardBumps?: {
             timestamp: number;
             charBits: number;
@@ -458,7 +486,10 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         defaultLimit: number;
         defaultPageSize: number;
         elementTranscodes: Record<string, string>;
-        indexes: Record<string, [string, ...string[]]>;
+        indexes: Record<string, {
+            components: [string, ...string[]];
+            projections?: [string, ...string[]] | undefined;
+        }>;
         shardBumps: {
             timestamp: number;
             charBits: number;
@@ -477,7 +508,10 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
         elementTranscodes?: Record<string, string> | undefined;
-        indexes?: Record<string, [string, ...string[]]> | undefined;
+        indexes?: Record<string, {
+            components: [string, ...string[]];
+            projections?: [string, ...string[]] | undefined;
+        }> | undefined;
         shardBumps?: {
             timestamp: number;
             charBits: number;
@@ -512,7 +546,10 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         defaultLimit: number;
         defaultPageSize: number;
         elementTranscodes: Record<string, string>;
-        indexes: Record<string, [string, ...string[]]>;
+        indexes: Record<string, {
+            components: [string, ...string[]];
+            projections?: [string, ...string[]] | undefined;
+        }>;
         shardBumps: {
             timestamp: number;
             charBits: number;
@@ -543,7 +580,10 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
         elementTranscodes?: Record<string, string> | undefined;
-        indexes?: Record<string, [string, ...string[]]> | undefined;
+        indexes?: Record<string, {
+            components: [string, ...string[]];
+            projections?: [string, ...string[]] | undefined;
+        }> | undefined;
         shardBumps?: {
             timestamp: number;
             charBits: number;
@@ -570,7 +610,10 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         defaultLimit: number;
         defaultPageSize: number;
         elementTranscodes: Record<string, string>;
-        indexes: Record<string, [string, ...string[]]>;
+        indexes: Record<string, {
+            components: [string, ...string[]];
+            projections?: [string, ...string[]] | undefined;
+        }>;
         shardBumps: {
             timestamp: number;
             charBits: number;
@@ -601,7 +644,10 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         defaultLimit?: number | undefined;
         defaultPageSize?: number | undefined;
         elementTranscodes?: Record<string, string> | undefined;
-        indexes?: Record<string, [string, ...string[]]> | undefined;
+        indexes?: Record<string, {
+            components: [string, ...string[]];
+            projections?: [string, ...string[]] | undefined;
+        }> | undefined;
         shardBumps?: {
             timestamp: number;
             charBits: number;
@@ -623,7 +669,7 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
     }> | undefined;
 }>;
 /**
- * Foo
+ * Simplified type taken on by a {@link Config | `Config`} object after parsing in the {@link EntityManager | `EntityManager`} constructor.
  *
  * @category Config
  */
@@ -831,41 +877,4 @@ declare class EntityManager<M extends EntityMap, HashKey extends string, RangeKe
     query<Item extends ItemMap<M, HashKey, RangeKey>[EntityToken], EntityToken extends keyof Exactify<M> & string>(options: QueryOptions<Item, EntityToken, M, HashKey, RangeKey>): Promise<QueryResult<Item, EntityToken, M, HashKey, RangeKey>>;
 }
 
-/**
- * Generic logger endpoint type.
- *
- * @category Logger
- */
-type LoggerEndpoint = (...args: unknown[]) => void;
-/**
- * Logger interface.
- *
- * @category Logger
- */
-interface Logger {
-    debug: LoggerEndpoint;
-    error: LoggerEndpoint;
-}
-/**
- * Logger options.
- *
- * @category Logger
- */
-interface LoggerOptions {
-    /** Logger to use for internal logging. Must support the `debug` & `error` methods. Defaults to `console`. */
-    logger?: Logger;
-    /** Enables internal logging when `true`. */
-    logInternals?: boolean;
-}
-
-/**
- * Returns an object type with specific properties rendered required and non-nullable.
- *
- * @typeParam T - The object type to modify.
- * @typeParam K - Union of keys of `T` to render required and non-nullable.
- */
-type WithRequiredAndNonNullable<T, K extends keyof T> = T & {
-    [P in K]-?: NonNullable<T[P]>;
-};
-
-export { type Config, type ConfigEntities, type ConfigEntity, type ConfigEntityGenerated, type ConfigKeys, type ConfigTranscodes, EntityManager, type EntityMap, type ExclusiveKey, type ItemMap, type Logger, type LoggerEndpoint, type LoggerOptions, type ParsedConfig, type QueryOptions, type QueryResult, type ShardBump, type ShardQueryFunction, type ShardQueryMap, type ShardQueryResult, type Unwrap, type WithRequiredAndNonNullable, conditionalize };
+export { type Config, type ConfigEntities, type ConfigEntity, type ConfigEntityGenerated, type ConfigEntityIndexComponents, type ConfigKeys, type ConfigTranscodes, EntityManager, type EntityMap, type ExclusiveKey, type ItemMap, type ParsedConfig, type QueryOptions, type QueryResult, type ShardBump, type ShardQueryFunction, type ShardQueryMap, type ShardQueryResult, type Unwrap, conditionalize };

package/dist/mjs/ParsedConfig.js

@@ -21,6 +21,10 @@ const validateKeyExclusive = (key, label, ref, ctx) => {
             message: `${label} '${key}' is not exclusive`,
         });
 };
+const componentArray = z
+    .array(z.string().min(1))
+    .nonempty()
+    .superRefine(validateArrayUnique);
 const configSchema = z
     .object({
     entities: z
@@ -44,10 +48,7 @@ const configSchema = z
             .record(z
             .object({
             atomic: z.boolean().optional().default(false),
-            elements: z
-                .array(z.string().min(1))
-                .nonempty()
-                .superRefine(validateArrayUnique),
+            elements: componentArray,
             sharded: z.boolean().optional().default(false),
         })
             .optional())
@@ -55,10 +56,10 @@ const configSchema = z
             .default({}),
         elementTranscodes: z.record(z.string()).optional().default({}),
         indexes: z
-            .record(z
-            .array(z.string().min(1))
-            .nonempty()
-            .superRefine(validateArrayUnique))
+            .record(z.object({
+            components: componentArray,
+            projections: componentArray.optional(),
+        }))
             .optional()
             .default({}),
         shardBumps: z
@@ -207,18 +208,42 @@ const configSchema = z
                         ],
                         received: element,
                     });
-        // validate all ungenerated entity index components have a corresponding entity element type.
+        // validate indexes.
         const generatedProperties = Object.keys(entity.generated);
-        for (const [indexKey, index] of Object.entries(entity.indexes))
-            for (const component of index)
+        for (const [indexKey, index] of Object.entries(entity.indexes)) {
+            // validate all ungenerated entity index components have a corresponding entity element type
+            for (const component of index.components)
                 if (![data.hashKey, data.rangeKey, ...generatedProperties].includes(component) &&
                     !typedElements.includes(component))
                     ctx.addIssue({
                         code: z.ZodIssueCode.invalid_enum_value,
                         options: typedElements,
-                        path: ['entities', entityToken, 'indexes', indexKey],
+                        path: [
+                            'entities',
+                            entityToken,
+                            'indexes',
+                            indexKey,
+                            'components',
+                        ],
                         received: component,
                     });
+            // validate no index projections are index components, hashKey, or rangeKey
+            if (index.projections)
+                for (const projection of index.projections) {
+                    if ([data.hashKey, data.rangeKey, ...index.components].includes(projection))
+                        ctx.addIssue({
+                            code: z.ZodIssueCode.custom,
+                            message: 'index projection is an index component, hash key, or range key',
+                            path: [
+                                'entities',
+                                entityToken,
+                                'indexes',
+                                indexKey,
+                                'projections',
+                            ],
+                        });
+                }
+        }
     }
 });
 

package/dist/mjs/index.js

@@ -1,3 +1,2 @@
 export { conditionalize } from './conditionalize.js';
 export { EntityManager } from './EntityManager.js';
-export { defaultTranscodes, isNil } from '@karmaniverous/entity-tools';

package/dist/mjs/rehydratePageKeyMap.js

@@ -49,7 +49,8 @@ function rehydratePageKeyMap(entityManager, dehydrated, entityToken, indexTokens
                 ...rehydrateIndexItem(entityManager, dehydratedIndexPageKeyMaps[i], entityToken, index, [entityManager.config.hashKey]),
             };
             item = updateItemRangeKey(entityManager, item, entityToken);
-            return zipToObject(entityManager.config.entities[entityToken].indexes[index], (component) => entityManager.config.entities[entityToken].generated[component]
+            return zipToObject(entityManager.config.entities[entityToken].indexes[index]
+                .components, (component) => entityManager.config.entities[entityToken].generated[component]
                 ? encodeGeneratedProperty(entityManager, item, entityToken, component)
                 : item[component]);
         }));

package/dist/mjs/unwrapIndex.js

@@ -19,7 +19,7 @@ function unwrapIndex(entityManager, entityToken, indexToken) {
         validateEntityIndexToken(entityManager, entityToken, indexToken);
         const generated = entityManager.config.entities[entityToken].generated;
         const generatedKeys = Object.keys(shake(generated));
-        return entityManager.config.entities[entityToken].indexes[indexToken]
+        return entityManager.config.entities[entityToken].indexes[indexToken].components
             .map((component) => component === entityManager.config.hashKey
             ? entityManager.config.hashKey
             : component === entityManager.config.rangeKey

package/package.json

@@ -4,7 +4,7 @@
     "url": "https://github.com/karmaniverous/entity-manager/issues"
   },
   "dependencies": {
-    "@karmaniverous/entity-tools": "^0.3.1",
+    "@karmaniverous/entity-tools": "^0.4.0",
     "@karmaniverous/string-utilities": "^0.2.1",
     "jsonschema": "^1.4.1",
     "lz-string": "^1.5.0",
@@ -14,9 +14,9 @@
   },
   "description": "Rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.",
   "devDependencies": {
-    "@dotenvx/dotenvx": "^1.20.0",
+    "@dotenvx/dotenvx": "^1.21.0",
     "@eslint/js": "^9.13.0",
-    "@faker-js/faker": "^9.0.3",
+    "@faker-js/faker": "^9.1.0",
     "@karmaniverous/mock-db": "^0.3.3",
     "@rollup/plugin-alias": "^5.1.1",
     "@rollup/plugin-commonjs": "^28.0.1",
@@ -24,15 +24,15 @@
     "@rollup/plugin-node-resolve": "^15.3.0",
     "@rollup/plugin-strip": "^3.0.4",
     "@rollup/plugin-typescript": "^12.1.1",
-    "@types/chai": "^5.0.0",
+    "@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.7.8",
+    "@types/node": "^22.8.2",
     "@types/string-hash": "^1.1.3",
     "auto-changelog": "^2.5.0",
-    "chai": "^5.1.1",
+    "chai": "^5.1.2",
     "cross-env": "^7.0.3",
     "eslint": "^9.13.0",
     "eslint-config-prettier": "^9.1.0",
@@ -40,24 +40,24 @@
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "eslint-plugin-tsdoc": "^0.3.0",
     "jsdom-global": "^3.0.2",
-    "knip": "^5.33.3",
-    "lefthook": "^1.7.22",
+    "knip": "^5.34.2",
+    "lefthook": "^1.8.2",
     "mocha": "^10.7.3",
     "nyc": "^17.1.0",
     "prettier": "^3.3.3",
     "release-it": "^17.10.0",
     "rimraf": "^6.0.1",
-    "rollup": "^4.24.0",
+    "rollup": "^4.24.2",
     "rollup-plugin-dts": "^6.1.1",
     "source-map-support": "^0.5.21",
     "ts-node": "^10.9.2",
     "tslib": "^2.8.0",
     "typedoc": "^0.26.10",
-    "typedoc-plugin-mdn-links": "^3.3.4",
+    "typedoc-plugin-mdn-links": "^3.3.5",
     "typedoc-plugin-replace-text": "^4.0.0",
     "typedoc-plugin-zod": "^1.2.1",
     "typescript": "^5.6.3",
-    "typescript-eslint": "^8.11.0"
+    "typescript-eslint": "^8.12.1"
   },
   "exports": {
     ".": {
@@ -132,5 +132,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "6.4.9"
+  "version": "6.5.0"
 }