dyno-table 2.5.1 → 2.6.0

package/dist/entity/ddb-indexing.d.ts

@@ -0,0 +1,45 @@
+import type { Table } from "../table";
+import type { DynamoItem } from "../types";
+import type { IndexDefinition } from "./entity";
+/**
+ * Helper class for building indexes for DynamoDB operations
+ */
+export declare class IndexBuilder<T extends DynamoItem> {
+    private readonly table;
+    private readonly indexes;
+    /**
+     * Creates a new IndexBuilder instance
+     *
+     * @param table - The DynamoDB table instance
+     * @param indexes - The index definitions
+     */
+    constructor(table: Table, indexes?: Record<string, IndexDefinition<T>>);
+    /**
+     * Build index attributes for item creation
+     *
+     * @param item - The item to generate indexes for
+     * @param options - Options for building indexes
+     * @returns Record of GSI attribute names to their values
+     */
+    buildForCreate(item: T, options?: {
+        excludeReadOnly?: boolean;
+    }): Record<string, string>;
+    /**
+     * Build index attributes for item updates
+     *
+     * @param currentData - The current data before update
+     * @param updates - The update data
+     * @param options - Options for building indexes
+     * @returns Record of GSI attribute names to their updated values
+     */
+    buildForUpdate(currentData: T, updates: Partial<T>, options?: {
+        forceRebuildIndexes?: string[];
+    }): Record<string, string>;
+    /**
+     * Check if a key has undefined values
+     *
+     * @param key - The index key to check
+     * @returns True if the key contains undefined values, false otherwise
+     */
+    private hasUndefinedValues;
+}

package/dist/entity/entity.d.ts

@@ -0,0 +1,188 @@
+import type { DeleteBuilder, GetBuilder, Path, PathType, PutBuilder, QueryBuilder, ScanBuilder, TransactionBuilder, UpdateBuilder, UpdateCommandParams } from "../builders";
+import { type Condition, type ConditionOperator, type PrimaryKey, type PrimaryKeyWithoutExpression } from "../conditions";
+import type { StandardSchemaV1 } from "../standard-schema";
+import type { Table } from "../table";
+import type { DynamoItem, Index, TableConfig } from "../types";
+export type QueryFunction<_T extends DynamoItem, I, R> = (input: I) => R;
+export type QueryFunctionWithSchema<T extends DynamoItem, I, R> = QueryFunction<T, I, R> & {
+    schema?: StandardSchemaV1<I>;
+};
+export type QueryRecord<T extends DynamoItem> = {
+    [K: string]: QueryFunctionWithSchema<T, any, any>;
+};
+export type MappedQueries<T extends DynamoItem, Q extends QueryRecord<T>> = {
+    [K in keyof Q]: Q[K] extends QueryFunctionWithSchema<T, infer I, infer R> ? (input: I) => R : never;
+};
+export type QueryEntity<T extends DynamoItem> = {
+    scan: () => ScanBuilder<T>;
+    get: (key: PrimaryKeyWithoutExpression) => EntityGetBuilder<T>;
+    query: (keyCondition: PrimaryKey) => QueryBuilder<T, TableConfig>;
+};
+type SetElementType<T> = T extends Set<infer U> ? U : T extends Array<infer U> ? U : never;
+type PathSetElementType<T, K extends Path<T>> = SetElementType<PathType<T, K>>;
+export type EntityPutBuilder<T extends DynamoItem> = PutBuilder<T> & {
+    readonly entityName: string;
+};
+export type EntityGetBuilder<T extends DynamoItem> = GetBuilder<T> & {
+    readonly entityName: string;
+};
+export type EntityDeleteBuilder = DeleteBuilder & {
+    readonly entityName: string;
+};
+export type EntityUpdateBuilder<T extends DynamoItem> = {
+    readonly entityName: string;
+    set(values: Partial<T>): EntityUpdateBuilder<T>;
+    set<K extends Path<T>>(path: K, value: PathType<T, K>): EntityUpdateBuilder<T>;
+    remove<K extends Path<T>>(path: K): EntityUpdateBuilder<T>;
+    add<K extends Path<T>>(path: K, value: PathType<T, K>): EntityUpdateBuilder<T>;
+    deleteElementsFromSet<K extends Path<T>>(path: K, value: PathSetElementType<T, K>[] | Set<PathSetElementType<T, K>>): EntityUpdateBuilder<T>;
+    condition(condition: Condition | ((op: ConditionOperator<T>) => Condition)): EntityUpdateBuilder<T>;
+    returnValues(returnValues: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE"): EntityUpdateBuilder<T>;
+    toDynamoCommand(): UpdateCommandParams;
+    withTransaction(transaction: TransactionBuilder): void;
+    debug(): ReturnType<UpdateBuilder<T>["debug"]>;
+    execute(): Promise<{
+        item?: T;
+    }>;
+    forceIndexRebuild(indexes: string | string[]): EntityUpdateBuilder<T>;
+    getForceRebuildIndexes(): string[];
+};
+interface Settings {
+    /**
+     * Defaults to "entityType"
+     */
+    entityTypeAttributeName?: string;
+    timestamps?: {
+        createdAt?: {
+            /**
+             * ISO vs Unix trade-offs
+             *
+             * Both options support between, greater than and less than comparisons.
+             *
+             * ISO:
+             * - Human readable, but requires more storage space
+             * - Does not work with DynamoDBs TTL feature.
+             *
+             * UNIX:
+             * - Less readable, but requires less storage space.
+             * - Works with DynamoDBs TTL feature.
+             */
+            format: "ISO" | "UNIX";
+            /**
+             * Defaults to "createdAt"
+             */
+            attributeName?: string;
+        };
+        updatedAt?: {
+            /**
+             * ISO vs Unix trade-offs
+             *
+             * Both options support between, greater than and less than comparisons.
+             *
+             * ISO:
+             * - Human readable, but requires more storage space
+             * - Does not work with DynamoDBs TTL feature.
+             *
+             * UNIX:
+             * - Less readable, but requires less storage space.
+             * - Works with DynamoDBs TTL feature.
+             */
+            format: "ISO" | "UNIX";
+            /**
+             * Defaults to "updatedAt"
+             */
+            attributeName?: string;
+        };
+    };
+}
+export interface EntityConfig<T extends DynamoItem, TInput extends DynamoItem = T, I extends DynamoItem = T, Q extends QueryRecord<T> = QueryRecord<T>> {
+    name: string;
+    schema: StandardSchemaV1<TInput, T>;
+    primaryKey: IndexDefinition<I>;
+    indexes?: Record<string, IndexDefinition<T>>;
+    queries: Q;
+    settings?: Settings;
+}
+export interface EntityRepository<
+/**
+ * The Entity Type (output type)
+ */
+T extends DynamoItem, 
+/**
+ * The Input Type (for create operations)
+ */
+TInput extends DynamoItem = T, 
+/**
+ * The Primary Index (Partition index) Type
+ */
+I extends DynamoItem = T, 
+/**
+ * The Queries object
+ */
+Q extends QueryRecord<T> = QueryRecord<T>> {
+    create: (data: TInput) => EntityPutBuilder<T>;
+    upsert: (data: TInput & I) => EntityPutBuilder<T>;
+    get: (key: I) => EntityGetBuilder<T>;
+    update: (key: I, data: Partial<T>) => EntityUpdateBuilder<T>;
+    delete: (key: I) => EntityDeleteBuilder;
+    query: MappedQueries<T, Q>;
+    scan: () => ScanBuilder<T>;
+}
+export interface EntityDefinition<T extends DynamoItem, TInput extends DynamoItem = T, I extends DynamoItem = T, Q extends QueryRecord<T> = QueryRecord<T>> {
+    name: string;
+    createRepository: (table: Table) => EntityRepository<T, TInput, I, Q>;
+}
+/**
+ * Creates an entity definition with type-safe operations
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name: string;
+ * }
+ *
+ * const UserEntity = defineEntity<User>({
+ *   name: "User",
+ *   schema: userSchema,
+ *   primaryKey: primaryKey,
+ * });
+ * ```
+ */
+export declare function defineEntity<T extends DynamoItem, TInput extends DynamoItem = T, I extends DynamoItem = T, Q extends QueryRecord<T> = QueryRecord<T>>(config: EntityConfig<T, TInput, I, Q>): EntityDefinition<T, TInput, I, Q>;
+export declare function createQueries<T extends DynamoItem>(): {
+    input: <I>(schema: StandardSchemaV1<I>) => {
+        query: <R extends ScanBuilder<T> | QueryBuilder<T, TableConfig> | GetBuilder<T>>(handler: (params: {
+            input: I;
+            entity: QueryEntity<T>;
+        }) => R) => QueryFunctionWithSchema<T, I, R>;
+    };
+};
+/**
+ * Defines a DynamoDB index configuration
+ */
+export interface IndexDefinition<T extends DynamoItem> extends Index<T> {
+    /** The name of the index */
+    name: string;
+    /** Whether the index is read-only */
+    isReadOnly: boolean;
+    /** Function to generate the index key from an item */
+    generateKey: (item: T) => {
+        pk: string;
+        sk?: string;
+    };
+}
+export declare function createIndex(): {
+    input: <T extends DynamoItem>(schema: StandardSchemaV1<T>) => {
+        partitionKey: <P extends (item: T) => string>(pkFn: P) => {
+            sortKey: <S extends (item: T) => string>(skFn: S) => IndexDefinition<T> & {
+                readOnly: (value?: boolean) => IndexDefinition<T>;
+            };
+            withoutSortKey: () => IndexDefinition<T> & {
+                readOnly: (value?: boolean) => IndexDefinition<T>;
+            };
+        };
+        readOnly: (value?: boolean) => /*elided*/ any;
+    };
+};
+export {};

package/dist/entity/index-utils.d.ts

@@ -0,0 +1,24 @@
+import type { Table } from "../table";
+import type { DynamoItem } from "../types";
+import type { IndexDefinition } from "./entity";
+/**
+ * Builds secondary indexes for an item based on the configured indexes
+ *
+ * @param dataForKeyGeneration - The validated data to generate keys from
+ * @param table - The DynamoDB table instance containing GSI configurations
+ * @param indexes - The index definitions
+ * @param excludeReadOnly - Whether to exclude read-only indexes
+ * @returns Record of GSI attribute names to their values
+ */
+export declare function buildIndexes<T extends DynamoItem>(dataForKeyGeneration: T, table: Table, indexes: Record<string, IndexDefinition<T>> | undefined, excludeReadOnly?: boolean): Record<string, string>;
+/**
+ * Builds index updates for an item based on the configured indexes
+ *
+ * @param currentData - The current data before update
+ * @param updates - The update data
+ * @param table - The DynamoDB table instance containing GSI configurations
+ * @param indexes - The index definitions
+ * @param forceRebuildIndexes - Array of index names to force rebuild even if readonly
+ * @returns Record of GSI attribute names to their updated values
+ */
+export declare function buildIndexUpdates<T extends DynamoItem>(currentData: T, updates: Partial<T>, table: Table, indexes: Record<string, IndexDefinition<T>> | undefined, forceRebuildIndexes?: string[]): Record<string, string>;

package/dist/entity.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkZXM6LPRV_cjs = require('./chunk-ZXM6LPRV.cjs');
+var chunkZ334X72N_cjs = require('./chunk-Z334X72N.cjs');
 require('./chunk-ELULXDSB.cjs');
 require('./chunk-7UJJ7JXM.cjs');
 
@@ -8,13 +8,13 @@ require('./chunk-7UJJ7JXM.cjs');
 
 Object.defineProperty(exports, "createIndex", {
   enumerable: true,
-  get: function () { return chunkZXM6LPRV_cjs.createIndex; }
+  get: function () { return chunkZ334X72N_cjs.createIndex; }
 });
 Object.defineProperty(exports, "createQueries", {
   enumerable: true,
-  get: function () { return chunkZXM6LPRV_cjs.createQueries; }
+  get: function () { return chunkZ334X72N_cjs.createQueries; }
 });
 Object.defineProperty(exports, "defineEntity", {
   enumerable: true,
-  get: function () { return chunkZXM6LPRV_cjs.defineEntity; }
+  get: function () { return chunkZ334X72N_cjs.defineEntity; }
 });

package/dist/entity.d.ts

@@ -1,261 +1 @@
-import { s as Path, t as PathType, b as Condition, c as ConditionOperator, P as PrimaryKeyWithoutExpression, a as PrimaryKey } from './conditions-BSAcZswY.js';
-import { P as PutBuilder, G as GetBuilder, U as UpdateBuilder, p as UpdateCommandParams, T as TransactionBuilder, D as DeleteBuilder, S as ScanBuilder, Q as QueryBuilder } from './index-Bc-ra0im.js';
-import { StandardSchemaV1 } from './standard-schema.js';
-import { Table } from './table.js';
-import { DynamoItem, Index, TableConfig } from './types.js';
-import '@aws-sdk/lib-dynamodb';
-
-type SetElementType<T> = T extends Set<infer U> ? U : T extends Array<infer U> ? U : never;
-type PathSetElementType<T, K extends Path<T>> = SetElementType<PathType<T, K>>;
-/**
- * Entity-aware wrapper for PutBuilder that automatically provides entity name to batch operations
- */
-type EntityAwarePutBuilder<T extends DynamoItem> = PutBuilder<T> & {
-    readonly entityName: string;
-};
-/**
- * Entity-aware wrapper for GetBuilder that automatically provides entity name to batch operations
- */
-type EntityAwareGetBuilder<T extends DynamoItem> = GetBuilder<T> & {
-    readonly entityName: string;
-};
-/**
- * Entity-aware wrapper for DeleteBuilder that automatically provides entity name to batch operations
- */
-type EntityAwareDeleteBuilder = DeleteBuilder & {
-    readonly entityName: string;
-};
-/**
- * Entity-aware wrapper for UpdateBuilder that adds forceIndexRebuild functionality
- * and automatically provides entity name to batch operations
- */
-declare class EntityAwareUpdateBuilder<T extends DynamoItem> {
-    private forceRebuildIndexes;
-    readonly entityName: string;
-    private builder;
-    private entityConfig?;
-    private updateDataApplied;
-    constructor(builder: UpdateBuilder<T>, entityName: string);
-    /**
-     * Configure entity-specific logic for automatic timestamp generation and index updates
-     */
-    configureEntityLogic(config: {
-        data: Partial<T>;
-        key: T;
-        table: Table;
-        indexes: Record<string, IndexDefinition<T>> | undefined;
-        generateTimestamps: () => Record<string, string | number>;
-        buildIndexUpdates: (currentData: T, updates: Partial<T>, table: Table, indexes: Record<string, IndexDefinition<T>> | undefined, forceRebuildIndexes?: string[]) => Record<string, string>;
-    }): void;
-    /**
-     * Forces a rebuild of one or more readonly indexes during the update operation.
-     *
-     * By default, readonly indexes are not updated during entity updates to prevent
-     * errors when required index attributes are missing. This method allows you to
-     * override that behavior and force specific indexes to be rebuilt.
-     *
-     * @example
-     * ```typescript
-     * // Force rebuild a single readonly index
-     * const result = await repo.update({ id: 'TREX-001' }, { status: 'ACTIVE' })
-     *   .forceIndexRebuild('gsi1')
-     *   .execute();
-     *
-     * // Force rebuild multiple readonly indexes
-     * const result = await repo.update({ id: 'TREX-001' }, { status: 'ACTIVE' })
-     *   .forceIndexRebuild(['gsi1', 'gsi2'])
-     *   .execute();
-     *
-     * // Chain with other update operations
-     * const result = await repo.update({ id: 'TREX-001' }, { status: 'ACTIVE' })
-     *   .set('lastUpdated', new Date().toISOString())
-     *   .forceIndexRebuild('gsi1')
-     *   .condition(op => op.eq('status', 'INACTIVE'))
-     *   .execute();
-     * ```
-     *
-     * @param indexes - A single index name or array of index names to force rebuild
-     * @returns The builder instance for method chaining
-     */
-    forceIndexRebuild(indexes: string | string[]): this;
-    /**
-     * Gets the list of indexes that should be force rebuilt.
-     * This is used internally by entity update logic.
-     *
-     * @returns Array of index names to force rebuild
-     */
-    getForceRebuildIndexes(): string[];
-    /**
-     * Apply entity-specific update data (timestamps and index updates)
-     * This is called automatically when needed
-     */
-    private applyEntityUpdates;
-    set(values: Partial<T>): this;
-    set<K extends Path<T>>(path: K, value: PathType<T, K>): this;
-    remove<K extends Path<T>>(path: K): this;
-    add<K extends Path<T>>(path: K, value: PathType<T, K>): this;
-    deleteElementsFromSet<K extends Path<T>>(path: K, value: PathSetElementType<T, K>[] | Set<PathSetElementType<T, K>>): this;
-    condition(condition: Condition | ((op: ConditionOperator<T>) => Condition)): this;
-    returnValues(returnValues: "ALL_NEW" | "UPDATED_NEW" | "ALL_OLD" | "UPDATED_OLD" | "NONE"): this;
-    toDynamoCommand(): UpdateCommandParams;
-    withTransaction(transaction: TransactionBuilder): void;
-    debug(): ReturnType<UpdateBuilder<T>["debug"]>;
-    execute(): Promise<{
-        item?: T;
-    }>;
-}
-
-type QueryFunction<_T extends DynamoItem, I, R> = (input: I) => R;
-type QueryFunctionWithSchema<T extends DynamoItem, I, R> = QueryFunction<T, I, R> & {
-    schema?: StandardSchemaV1<I>;
-};
-type QueryRecord<T extends DynamoItem> = {
-    [K: string]: QueryFunctionWithSchema<T, any, any>;
-};
-type MappedQueries<T extends DynamoItem, Q extends QueryRecord<T>> = {
-    [K in keyof Q]: Q[K] extends QueryFunctionWithSchema<T, infer I, infer R> ? (input: I) => R : never;
-};
-type QueryEntity<T extends DynamoItem> = {
-    scan: () => ScanBuilder<T>;
-    get: (key: PrimaryKeyWithoutExpression) => EntityAwareGetBuilder<T>;
-    query: (keyCondition: PrimaryKey) => QueryBuilder<T, TableConfig>;
-};
-interface Settings {
-    /**
-     * Defaults to "entityType"
-     */
-    entityTypeAttributeName?: string;
-    timestamps?: {
-        createdAt?: {
-            /**
-             * ISO vs Unix trade-offs
-             *
-             * Both options support between, greater than and less than comparisons.
-             *
-             * ISO:
-             * - Human readable, but requires more storage space
-             * - Does not work with DynamoDBs TTL feature.
-             *
-             * UNIX:
-             * - Less readable, but requires less storage space.
-             * - Works with DynamoDBs TTL feature.
-             */
-            format: "ISO" | "UNIX";
-            /**
-             * Defaults to "createdAt"
-             */
-            attributeName?: string;
-        };
-        updatedAt?: {
-            /**
-             * ISO vs Unix trade-offs
-             *
-             * Both options support between, greater than and less than comparisons.
-             *
-             * ISO:
-             * - Human readable, but requires more storage space
-             * - Does not work with DynamoDBs TTL feature.
-             *
-             * UNIX:
-             * - Less readable, but requires less storage space.
-             * - Works with DynamoDBs TTL feature.
-             */
-            format: "ISO" | "UNIX";
-            /**
-             * Defaults to "updatedAt"
-             */
-            attributeName?: string;
-        };
-    };
-}
-interface EntityConfig<T extends DynamoItem, TInput extends DynamoItem = T, I extends DynamoItem = T, Q extends QueryRecord<T> = QueryRecord<T>> {
-    name: string;
-    schema: StandardSchemaV1<TInput, T>;
-    primaryKey: IndexDefinition<I>;
-    indexes?: Record<string, IndexDefinition<T>>;
-    queries: Q;
-    settings?: Settings;
-}
-interface EntityRepository<
-/**
- * The Entity Type (output type)
- */
-T extends DynamoItem, 
-/**
- * The Input Type (for create operations)
- */
-TInput extends DynamoItem = T, 
-/**
- * The Primary Index (Partition index) Type
- */
-I extends DynamoItem = T, 
-/**
- * The Queries object
- */
-Q extends QueryRecord<T> = QueryRecord<T>> {
-    create: (data: TInput) => EntityAwarePutBuilder<T>;
-    upsert: (data: TInput & I) => EntityAwarePutBuilder<T>;
-    get: (key: I) => EntityAwareGetBuilder<T>;
-    update: (key: I, data: Partial<T>) => EntityAwareUpdateBuilder<T>;
-    delete: (key: I) => EntityAwareDeleteBuilder;
-    query: MappedQueries<T, Q>;
-    scan: () => ScanBuilder<T>;
-}
-/**
- * Creates an entity definition with type-safe operations
- *
- * @example
- * ```typescript
- * interface User {
- *   id: string;
- *   name: string;
- * }
- *
- * const UserEntity = defineEntity<User>({
- *   name: "User",
- *   schema: userSchema,
- *   primaryKey: primaryKey,
- * });
- * ```
- */
-declare function defineEntity<T extends DynamoItem, TInput extends DynamoItem = T, I extends DynamoItem = T, Q extends QueryRecord<T> = QueryRecord<T>>(config: EntityConfig<T, TInput, I, Q>): {
-    name: string;
-    createRepository: (table: Table) => EntityRepository<T, TInput, I, Q>;
-};
-declare function createQueries<T extends DynamoItem>(): {
-    input: <I>(schema: StandardSchemaV1<I>) => {
-        query: <R extends ScanBuilder<T> | QueryBuilder<T, TableConfig> | GetBuilder<T>>(handler: (params: {
-            input: I;
-            entity: QueryEntity<T>;
-        }) => R) => QueryFunctionWithSchema<T, I, R>;
-    };
-};
-/**
- * Defines a DynamoDB index configuration
- */
-interface IndexDefinition<T extends DynamoItem> extends Index<T> {
-    /** The name of the index */
-    name: string;
-    /** Whether the index is read-only */
-    isReadOnly: boolean;
-    /** Function to generate the index key from an item */
-    generateKey: (item: T) => {
-        pk: string;
-        sk?: string;
-    };
-}
-declare function createIndex(): {
-    input: <T extends DynamoItem>(schema: StandardSchemaV1<T>) => {
-        partitionKey: <P extends (item: T) => string>(pkFn: P) => {
-            sortKey: <S extends (item: T) => string>(skFn: S) => IndexDefinition<T> & {
-                readOnly: (value?: boolean) => IndexDefinition<T>;
-            };
-            withoutSortKey: () => IndexDefinition<T> & {
-                readOnly: (value?: boolean) => IndexDefinition<T>;
-            };
-        };
-        readOnly: (value?: boolean) => /*elided*/ any;
-    };
-};
-
-export { type EntityConfig, type EntityRepository, type IndexDefinition, type MappedQueries, type QueryEntity, type QueryFunction, type QueryFunctionWithSchema, type QueryRecord, createIndex, createQueries, defineEntity };
+export * from "./entity/entity";

package/dist/entity.js

@@ -1,3 +1,3 @@
-export { createIndex, createQueries, defineEntity } from './chunk-U6MQGB6Y.js';
+export { createIndex, createQueries, defineEntity } from './chunk-JZB6TYST.js';
 import './chunk-FF7FYGDH.js';
 import './chunk-2WIBY7PZ.js';