@karmaniverous/entity-manager 6.4.10 → 6.5.1

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,11 @@ 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({
+            hashKey: zod.z.string().min(1),
+            rangeKey: zod.z.string().min(1),
+            projections: componentArray.optional(),
+        }))
             .optional()
             .default({}),
         shardBumps: zod.z
@@ -209,18 +211,56 @@ 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, { hashKey, rangeKey, projections },] of Object.entries(entity.indexes)) {
+            // validate index hash key is sharded
+            if (hashKey !== data.hashKey && !entity.generated[hashKey]?.sharded)
+                ctx.addIssue({
+                    code: zod.z.ZodIssueCode.custom,
+                    message: 'index hash key is not sharded',
+                    path: ['entities', entityToken, 'indexes', indexKey, 'hashKey'],
+                });
+            // validate index range key is unsharded
+            if (rangeKey !== data.rangeKey && entity.generated[rangeKey]?.sharded)
+                ctx.addIssue({
+                    code: zod.z.ZodIssueCode.custom,
+                    message: 'index range key is sharded',
+                    path: ['entities', entityToken, 'indexes', indexKey, 'rangeKey'],
+                });
+            // validate all ungenerated entity index components have a corresponding entity element type
+            for (const component of [hashKey, rangeKey])
                 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 (projections)
+                for (const projection of projections) {
+                    if ([data.hashKey, data.rangeKey, hashKey, rangeKey].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/getIndexComponents.js

@@ -0,0 +1,25 @@
+'use strict';
+
+var radash = require('radash');
+var validateEntityIndexToken = require('./validateEntityIndexToken.js');
+
+/**
+ * Get the index components of an entity index. Adds the hash and range keys to the index components.
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
+ * @param indexToken - {@link ConfigEntity.indexes | `entityManager.config.entities.<entityToken>.indexes`} key.
+ *
+ * @returns Array of index components.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ * @throws `Error` if `indexToken` is invalid.
+ */
+function getIndexComponents(entityManager, entityToken, indexToken) {
+    validateEntityIndexToken.validateEntityIndexToken(entityManager, entityToken, indexToken);
+    const { hashKey, rangeKey, entities } = entityManager.config;
+    const { hashKey: indexHashKey, rangeKey: indexRangeKey } = entities[entityToken].indexes[indexToken];
+    return radash.unique([hashKey, rangeKey, indexHashKey, indexRangeKey]);
+}
+
+exports.getIndexComponents = getIndexComponents;

package/dist/cjs/rehydratePageKeyMap.js

@@ -3,6 +3,7 @@
 var radash = require('radash');
 var encodeGeneratedProperty = require('./encodeGeneratedProperty.js');
 var getHashKeySpace = require('./getHashKeySpace.js');
+var getIndexComponents = require('./getIndexComponents.js');
 var rehydrateIndexItem = require('./rehydrateIndexItem.js');
 var updateItemRangeKey = require('./updateItemRangeKey.js');
 var validateEntityIndexToken = require('./validateEntityIndexToken.js');
@@ -51,7 +52,7 @@ 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(getIndexComponents.getIndexComponents(entityManager, entityToken, index), (component) => entityManager.config.entities[entityToken].generated[component]
                 ? encodeGeneratedProperty.encodeGeneratedProperty(entityManager, item, entityToken, component)
                 : item[component]);
         }));

package/dist/cjs/unwrapIndex.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var radash = require('radash');
+var getIndexComponents = require('./getIndexComponents.js');
 var validateEntityIndexToken = require('./validateEntityIndexToken.js');
 
 /**
@@ -21,7 +22,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 getIndexComponents.getIndexComponents(entityManager, entityToken, indexToken)
             .map((component) => component === entityManager.config.hashKey
             ? entityManager.config.hashKey
             : component === entityManager.config.rangeKey

package/dist/index.d.ts

@@ -80,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 ConfigEntityIndexComponent<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.
  *
@@ -171,11 +184,15 @@ type ConfigEntity<EntityToken extends keyof Exactify<M>, M extends EntityMap, Ha
     /**
      * Indexes defined for the {@link Entity | `Entity`}. Should reflect the underlying database table indexes.
      *
-     * Each key is the name of an index, and each value is a non-empty array of {@link Entity | `Entity`} property names that define the index.
+     * Each key is the name of an index, and each value defines the hash key, range key, and projected properties of the index.
      *
-     * Related property types must be align with the {@link Config | `Config`} `T` type parameter. Note tha all {@link ConfigEntityGenerated | generated property} types are transcodable by definition.
+     * hashKey and rangeKey types must align with the {@link Config | `Config`} `T` type parameter. Note that 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, {
+        hashKey: ConfigEntityIndexComponent<EntityToken, M, HashKey, RangeKey, T>;
+        rangeKey: ConfigEntityIndexComponent<EntityToken, M, HashKey, RangeKey, T>;
+        projections?: (keyof M[EntityToken])[];
+    }>;
     /**
      * An array of {@link ShardBump | `ShardBump`} objects representing the {@link Entity | `Entity`}'s sharding strategy.
      *
@@ -377,7 +394,19 @@ 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<{
+            hashKey: z.ZodString;
+            rangeKey: z.ZodString;
+            projections: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodString, "atleastone">, [string, ...string[]], [string, ...string[]]>>;
+        }, "strip", z.ZodTypeAny, {
+            hashKey: string;
+            rangeKey: string;
+            projections?: [string, ...string[]] | undefined;
+        }, {
+            hashKey: string;
+            rangeKey: 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;
@@ -421,7 +450,11 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         defaultLimit: number;
         defaultPageSize: number;
         elementTranscodes: Record<string, string>;
-        indexes: Record<string, [string, ...string[]]>;
+        indexes: Record<string, {
+            hashKey: string;
+            rangeKey: string;
+            projections?: [string, ...string[]] | undefined;
+        }>;
         shardBumps: {
             timestamp: number;
             charBits: number;
@@ -440,7 +473,11 @@ 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, {
+            hashKey: string;
+            rangeKey: string;
+            projections?: [string, ...string[]] | undefined;
+        }> | undefined;
         shardBumps?: {
             timestamp: number;
             charBits: number;
@@ -455,7 +492,11 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         defaultLimit: number;
         defaultPageSize: number;
         elementTranscodes: Record<string, string>;
-        indexes: Record<string, [string, ...string[]]>;
+        indexes: Record<string, {
+            hashKey: string;
+            rangeKey: string;
+            projections?: [string, ...string[]] | undefined;
+        }>;
         shardBumps: {
             timestamp: number;
             charBits: number;
@@ -474,7 +515,11 @@ 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, {
+            hashKey: string;
+            rangeKey: string;
+            projections?: [string, ...string[]] | undefined;
+        }> | undefined;
         shardBumps?: {
             timestamp: number;
             charBits: number;
@@ -509,7 +554,11 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         defaultLimit: number;
         defaultPageSize: number;
         elementTranscodes: Record<string, string>;
-        indexes: Record<string, [string, ...string[]]>;
+        indexes: Record<string, {
+            hashKey: string;
+            rangeKey: string;
+            projections?: [string, ...string[]] | undefined;
+        }>;
         shardBumps: {
             timestamp: number;
             charBits: number;
@@ -540,7 +589,11 @@ 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, {
+            hashKey: string;
+            rangeKey: string;
+            projections?: [string, ...string[]] | undefined;
+        }> | undefined;
         shardBumps?: {
             timestamp: number;
             charBits: number;
@@ -567,7 +620,11 @@ declare const configSchema: z.ZodEffects<z.ZodObject<{
         defaultLimit: number;
         defaultPageSize: number;
         elementTranscodes: Record<string, string>;
-        indexes: Record<string, [string, ...string[]]>;
+        indexes: Record<string, {
+            hashKey: string;
+            rangeKey: string;
+            projections?: [string, ...string[]] | undefined;
+        }>;
         shardBumps: {
             timestamp: number;
             charBits: number;
@@ -598,7 +655,11 @@ 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, {
+            hashKey: string;
+            rangeKey: string;
+            projections?: [string, ...string[]] | undefined;
+        }> | undefined;
         shardBumps?: {
             timestamp: number;
             charBits: number;
@@ -620,7 +681,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
  */
@@ -828,4 +889,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>>;
 }
 
-export { type Config, type ConfigEntities, type ConfigEntity, type ConfigEntityGenerated, type ConfigKeys, type ConfigTranscodes, EntityManager, type EntityMap, type ExclusiveKey, type ItemMap, type ParsedConfig, type QueryOptions, type QueryResult, type ShardBump, type ShardQueryFunction, type ShardQueryMap, type ShardQueryResult, type Unwrap, conditionalize };
+export { type Config, type ConfigEntities, type ConfigEntity, type ConfigEntityGenerated, type ConfigEntityIndexComponent, 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,11 @@ 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({
+            hashKey: z.string().min(1),
+            rangeKey: z.string().min(1),
+            projections: componentArray.optional(),
+        }))
             .optional()
             .default({}),
         shardBumps: z
@@ -207,18 +209,56 @@ 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, { hashKey, rangeKey, projections },] of Object.entries(entity.indexes)) {
+            // validate index hash key is sharded
+            if (hashKey !== data.hashKey && !entity.generated[hashKey]?.sharded)
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: 'index hash key is not sharded',
+                    path: ['entities', entityToken, 'indexes', indexKey, 'hashKey'],
+                });
+            // validate index range key is unsharded
+            if (rangeKey !== data.rangeKey && entity.generated[rangeKey]?.sharded)
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: 'index range key is sharded',
+                    path: ['entities', entityToken, 'indexes', indexKey, 'rangeKey'],
+                });
+            // validate all ungenerated entity index components have a corresponding entity element type
+            for (const component of [hashKey, rangeKey])
                 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 (projections)
+                for (const projection of projections) {
+                    if ([data.hashKey, data.rangeKey, hashKey, rangeKey].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/getIndexComponents.js

@@ -0,0 +1,23 @@
+import { unique } from 'radash';
+import { validateEntityIndexToken } from './validateEntityIndexToken.js';
+
+/**
+ * Get the index components of an entity index. Adds the hash and range keys to the index components.
+ *
+ * @param entityManager - {@link EntityManager | `EntityManager`} instance.
+ * @param entityToken - {@link ConfigKeys.entities | `entityManager.config.entities`} key.
+ * @param indexToken - {@link ConfigEntity.indexes | `entityManager.config.entities.<entityToken>.indexes`} key.
+ *
+ * @returns Array of index components.
+ *
+ * @throws `Error` if `entityToken` is invalid.
+ * @throws `Error` if `indexToken` is invalid.
+ */
+function getIndexComponents(entityManager, entityToken, indexToken) {
+    validateEntityIndexToken(entityManager, entityToken, indexToken);
+    const { hashKey, rangeKey, entities } = entityManager.config;
+    const { hashKey: indexHashKey, rangeKey: indexRangeKey } = entities[entityToken].indexes[indexToken];
+    return unique([hashKey, rangeKey, indexHashKey, indexRangeKey]);
+}
+
+export { getIndexComponents };

package/dist/mjs/rehydratePageKeyMap.js

@@ -1,6 +1,7 @@
 import { range, mapValues, zipToObject, cluster } from 'radash';
 import { encodeGeneratedProperty } from './encodeGeneratedProperty.js';
 import { getHashKeySpace } from './getHashKeySpace.js';
+import { getIndexComponents } from './getIndexComponents.js';
 import { rehydrateIndexItem } from './rehydrateIndexItem.js';
 import { updateItemRangeKey } from './updateItemRangeKey.js';
 import { validateEntityIndexToken } from './validateEntityIndexToken.js';
@@ -49,7 +50,7 @@ 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(getIndexComponents(entityManager, entityToken, index), (component) => entityManager.config.entities[entityToken].generated[component]
                 ? encodeGeneratedProperty(entityManager, item, entityToken, component)
                 : item[component]);
         }));

package/dist/mjs/unwrapIndex.js

@@ -1,4 +1,5 @@
 import { shake } from 'radash';
+import { getIndexComponents } from './getIndexComponents.js';
 import { validateEntityIndexToken } from './validateEntityIndexToken.js';
 
 /**
@@ -19,7 +20,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 getIndexComponents(entityManager, entityToken, indexToken)
             .map((component) => component === entityManager.config.hashKey
             ? entityManager.config.hashKey
             : component === entityManager.config.rangeKey

package/package.json

@@ -132,5 +132,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "6.4.10"
+  "version": "6.5.1"
 }