@ftschopp/dynatable-core 1.0.0

package/dist/core/types.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Type definitions for DynamoDB schema and model inference
+ *
+ * Provides comprehensive type utilities for:
+ * - Defining DynamoDB table schemas with primary and secondary indexes
+ * - Inferring strongly-typed input and output models from schema definitions
+ * - Automatic key generation and template variable extraction
+ * - Type-safe attribute handling with support for defaults and auto-generation
+ *
+ * @example
+ * ```typescript
+ * const schema: SchemaDefinition = {
+ *   format: 'dynatable:1.0.0',
+ *   version: '1.0.0',
+ *   indexes: { primary: { hash: "PK", sort: "SK" } },
+ *   models: {
+ *     User: {
+ *       key: { PK: { type: String, value: "USER#${id}" }, SK: { type: String, value: "PROFILE" } },
+ *       attributes: { id: { type: String, required: true }, name: { type: String } }
+ *     }
+ *   }
+ * };
+ * ```
+ */
+/**
+ * Attribute definition for model attributes
+ *
+ * @property type - The JavaScript constructor for the attribute type
+ * @property [required] - Whether the attribute is required
+ * @property [generate] - Auto-generation strategy ('ulid', 'uuid')
+ * @property [default] - Default value or generator function
+ */
+export type AttributeDefinition = {
+    type: StringConstructor | NumberConstructor | BooleanConstructor | DateConstructor;
+    required?: boolean;
+    generate?: 'ulid' | 'uuid';
+    default?: any;
+};
+/**
+ * Key definition for primary and secondary indexes
+ *
+ * @property type - Always String for DynamoDB keys
+ * @property value - Template string for key generation
+ */
+export type KeyDefinition = {
+    type: StringConstructor;
+    value: string;
+};
+/**
+ * Primary key definition - requires both PK and SK (uppercase)
+ */
+export type PrimaryKeyDefinition = {
+    PK: KeyDefinition;
+    SK: KeyDefinition;
+};
+/**
+ * Index definition with hash and optional sort key
+ */
+export type IndexDefinition = {
+    hash: string;
+    sort?: string;
+};
+/**
+ * Indexes configuration - requires at least a primary index
+ */
+export type IndexesDefinition = {
+    primary: IndexDefinition;
+    [indexName: string]: IndexDefinition;
+};
+/**
+ * Model definition containing keys, indexes, and attributes
+ * - key: REQUIRED, must have pk and sk
+ * - attributes: REQUIRED, model attributes
+ * - index: OPTIONAL, secondary index keys
+ */
+export type ModelDefinition = {
+    key: PrimaryKeyDefinition;
+    index?: Record<string, KeyDefinition>;
+    attributes: Record<string, AttributeDefinition>;
+};
+/**
+ * Schema parameters configuration
+ */
+export type SchemaParams = {
+    isoDates?: boolean;
+    timestamps?: boolean;
+};
+/**
+ * Complete schema definition for a DynamoDB table
+ * - format: Table schema format version (e.g., "dynatable:1.0.0")
+ * - version: Schema version (e.g., "1.0.0")
+ * - indexes: Index definitions (requires at least 'primary')
+ * - models: Model definitions (each requires 'key' and 'attributes')
+ * - params: Optional schema parameters
+ */
+export type SchemaDefinition = {
+    format: string;
+    version: string;
+    indexes: IndexesDefinition;
+    models: Record<string, ModelDefinition>;
+    params?: SchemaParams;
+};
+type InferAttr<T> = T extends StringConstructor ? string : T extends NumberConstructor ? number : T extends BooleanConstructor ? boolean : T extends DateConstructor ? Date : unknown;
+/**
+ * Non-generated attributes for input
+ * Splits into required and optional based on the 'required' field
+ */
+type NonGeneratedAttributes<M extends ModelDefinition> = {
+    [K in keyof M['attributes'] as M['attributes'][K] extends {
+        generate: string;
+    } ? never : M['attributes'][K] extends {
+        required: true;
+    } ? K : never]: InferAttr<M['attributes'][K]['type']>;
+} & {
+    [K in keyof M['attributes'] as M['attributes'][K] extends {
+        generate: string;
+    } ? never : M['attributes'][K] extends {
+        required: false;
+    } ? K : M['attributes'][K] extends {
+        required: true;
+    } ? never : K]?: InferAttr<M['attributes'][K]['type']>;
+};
+/**
+ * Generated-only attributes for internal use
+ */
+type GeneratedAttributes<M extends ModelDefinition> = {
+    [K in keyof M['attributes'] as M['attributes'][K] extends {
+        generate: string;
+    } ? K : never]: InferAttr<M['attributes'][K]['type']>;
+};
+/**
+ * Template string variable extraction
+ */
+type ExtractTemplateVars<S extends string> = S extends `${string}\${${infer Var}}${infer Rest}` ? Var | ExtractTemplateVars<Rest> : never;
+/**
+ * Extract template variables from primary keys (PK and SK)
+ */
+type PrimaryKeyVars<M extends ModelDefinition> = ExtractTemplateVars<M['key']['PK']['value']> | ExtractTemplateVars<M['key']['SK']['value']>;
+/**
+ * Extract template variables from index keys (if they exist)
+ */
+type IndexKeyVars<M extends ModelDefinition> = M['index'] extends Record<string, KeyDefinition> ? {
+    [K in keyof M['index']]: ExtractTemplateVars<M['index'][K]['value']>;
+}[keyof M['index']] : never;
+/**
+ * Extract all template variables from primary and index keys
+ */
+type KeyVars<M extends ModelDefinition> = PrimaryKeyVars<M> | IndexKeyVars<M>;
+type IsGenerated<M extends ModelDefinition, K extends string> = K extends keyof M['attributes'] ? M['attributes'][K] extends {
+    generate: string;
+} ? true : false : false;
+type FilterNonGeneratedKeyVars<M extends ModelDefinition, K extends string = KeyVars<M>> = K extends string ? (IsGenerated<M, K> extends true ? never : K) : never;
+/**
+ * Keys required in input
+ */
+type RequiredKeys<M extends ModelDefinition> = {
+    [K in keyof NonGeneratedAttributes<M>]: M['attributes'][K] extends {
+        required: true;
+    } ? K : never;
+}[keyof NonGeneratedAttributes<M>];
+/**
+ * Input type used for put/update
+ *
+ * @deprecated Use InferInputFromSchema when possible to get timestamp inference
+ */
+export type InferInput<M extends ModelDefinition> = {
+    [K in keyof NonGeneratedAttributes<M> as K extends RequiredKeys<M> ? K : never]: NonGeneratedAttributes<M>[K];
+} & {
+    [K in keyof NonGeneratedAttributes<M> as K extends RequiredKeys<M> ? never : K]?: NonGeneratedAttributes<M>[K];
+} & {
+    [K in FilterNonGeneratedKeyVars<M>]: string;
+};
+/**
+ * Infers the input type from a complete schema definition
+ * When timestamps are enabled, createdAt and updatedAt are NOT included (auto-generated)
+ */
+export type InferInputFromSchema<S extends SchemaDefinition, ModelName extends keyof S['models']> = InferInput<S['models'][ModelName]>;
+/**
+ * Full model type after applying defaults and keys
+ */
+type ModelAttributes<M extends ModelDefinition> = NonGeneratedAttributes<M> & GeneratedAttributes<M>;
+/**
+ * Timestamp fields that are automatically added when timestamps are enabled
+ */
+export type TimestampFields = {
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * Infers the model type without exposing internal DynamoDB keys (PK, SK, GSI1PK, etc.)
+ * Only includes business attributes and generated fields
+ *
+ * @deprecated Use InferModelFromSchema when possible to get timestamp inference
+ */
+export type InferModel<M extends ModelDefinition> = ModelAttributes<M>;
+/**
+ * Infers the model type from a complete schema definition
+ * Automatically includes timestamp fields (createdAt, updatedAt) when params.timestamps is true
+ */
+export type InferModelFromSchema<S extends SchemaDefinition, ModelName extends keyof S['models']> = S['params'] extends {
+    timestamps: true;
+} ? ModelAttributes<S['models'][ModelName]> & TimestampFields : ModelAttributes<S['models'][ModelName]>;
+/**
+ * Internal type that includes DynamoDB keys - used internally by builders
+ * Includes pk, sk, and any index keys
+ * @internal
+ */
+export type InferModelWithKeys<M extends ModelDefinition> = ModelAttributes<M> & {
+    [K in keyof M['key']]: string;
+} & (M['index'] extends Record<string, KeyDefinition> ? {
+    [K in keyof M['index']]: string;
+} : Record<string, never>);
+/**
+ * Extract template variables from primary keys only
+ */
+type KeyTemplateVars<M extends ModelDefinition> = PrimaryKeyVars<M>;
+/**
+ * Input for get/delete operations (only key template vars)
+ */
+export type InferKeyInput<M extends ModelDefinition> = {
+    [K in KeyTemplateVars<M>]: string;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/core/types.js

@@ -0,0 +1,3 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/entity.d.ts

@@ -0,0 +1,73 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { InferInput, InferKeyInput, InferModel, ModelDefinition } from './core/types';
+import { GetBuilder, PutBuilder, QueryBuilder, UpdateBuilder, DeleteBuilder, ScanBuilder, BatchGetBuilder, BatchWriteBuilder } from './builders';
+import { DynamoDBLogger } from './utils/dynamodb-logger';
+/**
+ * Options for creating the Entity API
+ */
+export type EntityAPIOptions = {
+    logger?: DynamoDBLogger;
+    timestamps?: boolean;
+};
+/**
+ * Entity API interface for a model
+ */
+export type EntityAPI<Model, Input, KeyInput, ModelDef extends ModelDefinition = any> = {
+    /**
+     * Retrieves an item by its key.
+     * @param key - Partial or full key object to identify the item
+     * @returns GetBuilder configured for the item
+     */
+    get: (key: KeyInput) => GetBuilder<KeyInput, Model>;
+    /**
+     * Puts an item into the table after validation and applying defaults.
+     * @param item - The input data to put
+     * @returns PutBuilder configured for the item
+     */
+    put: (item: Input) => PutBuilder<Model>;
+    /**
+     * Queries items using key conditions.
+     * @returns QueryBuilder for building and executing the query
+     */
+    query: () => QueryBuilder<Model, ModelDef>;
+    /**
+     * Scans the entire table or index without key conditions.
+     * @returns ScanBuilder for building and executing the scan
+     */
+    scan: () => ScanBuilder<Model>;
+    /**
+     * Updates an item by its key.
+     * @param key - Partial or full key object to identify the item
+     * @returns UpdateBuilder configured for the item
+     */
+    update: (key: KeyInput) => UpdateBuilder<Model>;
+    /**
+     * Deletes an item by its key.
+     * @param key - Partial or full key object to identify the item
+     * @returns DeleteBuilder configured for the item
+     */
+    delete: (key: KeyInput) => DeleteBuilder<Model>;
+    /**
+     * Retrieves multiple items by their keys in a single batch operation.
+     * @param keys - Array of key objects to retrieve
+     * @returns BatchGetBuilder configured for the items
+     */
+    batchGet: (keys: KeyInput[]) => BatchGetBuilder<Model>;
+    /**
+     * Writes multiple items in a single batch operation (puts or deletes).
+     * @param items - Array of items to put
+     * @returns BatchWriteBuilder configured for the items
+     */
+    batchWrite: (items: Input[]) => BatchWriteBuilder;
+};
+/**
+ * Creates an entity API instance with validation, key resolution, and builder creation.
+ *
+ * @param modelName - The name of the model/entity
+ * @param model - The model definition
+ * @param client - DynamoDB client instance
+ * @param options - Optional configuration (logger, timestamps)
+ * @returns EntityAPI with get and put methods
+ */
+export declare const createEntityAPI: <Model extends ModelDefinition>(tableName: string, modelName: string, model: Model, client: DynamoDBClient, options?: EntityAPIOptions) => EntityAPI<InferModel<Model>, InferInput<Model>, InferKeyInput<Model>, Model>;
+//# sourceMappingURL=entity.d.ts.map

package/dist/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGtF,OAAO,EASL,UAAU,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EACb,aAAa,EACb,WAAW,EACX,eAAe,EACf,iBAAiB,EAElB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,SAAS,eAAe,GAAG,GAAG,IAAI;IACtF;;;;OAIG;IACH,GAAG,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAEpD;;;;OAIG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,UAAU,CAAC,KAAK,CAAC,CAAC;IAExC;;;OAGG;IACH,KAAK,EAAE,MAAM,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAE3C;;;OAGG;IACH,IAAI,EAAE,MAAM,WAAW,CAAC,KAAK,CAAC,CAAC;IAE/B;;;;OAIG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,aAAa,CAAC,KAAK,CAAC,CAAC;IAEhD;;;;OAIG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,aAAa,CAAC,KAAK,CAAC,CAAC;IAEhD;;;;OAIG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,eAAe,CAAC,KAAK,CAAC,CAAC;IAEvD;;;;OAIG;IACH,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,iBAAiB,CAAC;CACnD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,SAAS,eAAe,EAC3D,WAAW,MAAM,EACjB,WAAW,MAAM,EACjB,OAAO,KAAK,EACZ,QAAQ,cAAc,EACtB,UAAS,gBAAqB,KAC7B,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,KAAK,CAqO7E,CAAC"}

package/dist/entity.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEntityAPI = void 0;
+const model_utils_1 = require("./utils/model-utils");
+const zod_utils_1 = require("./utils/zod-utils");
+const builders_1 = require("./builders");
+/**
+ * Creates an entity API instance with validation, key resolution, and builder creation.
+ *
+ * @param modelName - The name of the model/entity
+ * @param model - The model definition
+ * @param client - DynamoDB client instance
+ * @param options - Optional configuration (logger, timestamps)
+ * @returns EntityAPI with get and put methods
+ */
+const createEntityAPI = (tableName, modelName, model, client, options = {}) => {
+    const { logger, timestamps = false } = options;
+    // Build a Zod schema from the model
+    const zodSchema = (0, zod_utils_1.modelToZod)(model);
+    return {
+        get(key) {
+            // Extract required fields from key templates
+            const requiredFields = new Set();
+            if (model.key) {
+                for (const keyDef of Object.values(model.key)) {
+                    (0, model_utils_1.extractTemplateVars)(keyDef.value).forEach((field) => requiredFields.add(field));
+                }
+            }
+            // Check if all required fields are present
+            const keyRecord = key;
+            const missingFields = Array.from(requiredFields).filter((field) => keyRecord[field] === undefined);
+            if (missingFields.length > 0) {
+                throw new Error(`[${modelName}] Missing required key field(s) for get(): ${missingFields.join(', ')}. ` +
+                    `Required fields: ${Array.from(requiredFields).join(', ')}`);
+            }
+            // Resolve any key defaults or computed keys
+            const fullKey = (0, model_utils_1.resolveKeys)(model, key);
+            return (0, builders_1.createGetBuilder)(tableName, fullKey, client, undefined, logger);
+        },
+        put(item) {
+            // Validate full input data
+            const parsed = zodSchema.parse(item);
+            // Apply post-processing defaults from the model (including timestamps for new items)
+            const withDefaults = (0, model_utils_1.applyPostDefaults)(model, parsed, {
+                isUpdate: false,
+                timestamps,
+            });
+            // Resolve keys again with defaults
+            const fullKey = (0, model_utils_1.resolveKeys)(model, withDefaults);
+            // Combine keys and data into full item, adding _type field
+            const fullItem = {
+                ...withDefaults,
+                ...fullKey,
+                _type: modelName, // Add entity type identifier
+            };
+            return (0, builders_1.createPutBuilder)(tableName, fullItem, client, [], false, 'NONE', false, logger);
+        },
+        query() {
+            return (0, builders_1.createQueryBuilder)(tableName, client, model, logger);
+        },
+        scan() {
+            return (0, builders_1.createScanBuilder)(tableName, client, [], [], undefined, false, undefined, undefined, undefined, logger);
+        },
+        update(key) {
+            // Extract required fields from key templates
+            const requiredFields = new Set();
+            if (model.key) {
+                for (const keyDef of Object.values(model.key)) {
+                    (0, model_utils_1.extractTemplateVars)(keyDef.value).forEach((field) => requiredFields.add(field));
+                }
+            }
+            // Check if all required fields are present
+            const keyRecord = key;
+            const missingFields = Array.from(requiredFields).filter((field) => keyRecord[field] === undefined);
+            if (missingFields.length > 0) {
+                throw new Error(`[${modelName}] Missing required key field(s) for update(): ${missingFields.join(', ')}. ` +
+                    `Required fields: ${Array.from(requiredFields).join(', ')}`);
+            }
+            // Resolve any key defaults or computed keys
+            const fullKey = (0, model_utils_1.resolveKeys)(model, key);
+            return (0, builders_1.createUpdateBuilder)(tableName, fullKey, client, [], { set: [], remove: [], add: [], delete: [] }, 'NONE', 0, timestamps, logger);
+        },
+        delete(key) {
+            // Extract required fields from key templates
+            const requiredFields = new Set();
+            if (model.key) {
+                for (const keyDef of Object.values(model.key)) {
+                    (0, model_utils_1.extractTemplateVars)(keyDef.value).forEach((field) => requiredFields.add(field));
+                }
+            }
+            // Check if all required fields are present
+            const keyRecord = key;
+            const missingFields = Array.from(requiredFields).filter((field) => keyRecord[field] === undefined);
+            if (missingFields.length > 0) {
+                throw new Error(`[${modelName}] Missing required key field(s) for delete(): ${missingFields.join(', ')}. ` +
+                    `Required fields: ${Array.from(requiredFields).join(', ')}`);
+            }
+            // Resolve any key defaults or computed keys
+            const fullKey = (0, model_utils_1.resolveKeys)(model, key);
+            return (0, builders_1.createDeleteBuilder)(tableName, fullKey, client, [], 'NONE', logger);
+        },
+        batchGet(keys) {
+            // Extract required fields from key templates
+            const requiredFields = new Set();
+            if (model.key) {
+                for (const keyDef of Object.values(model.key)) {
+                    (0, model_utils_1.extractTemplateVars)(keyDef.value).forEach((field) => requiredFields.add(field));
+                }
+            }
+            // Process all keys and validate them
+            const resolvedKeys = keys.map((key) => {
+                // Check if all required fields are present
+                const keyRecord = key;
+                const missingFields = Array.from(requiredFields).filter((field) => keyRecord[field] === undefined);
+                if (missingFields.length > 0) {
+                    throw new Error(`[${modelName}] Missing required key field(s) for batchGet(): ${missingFields.join(', ')}. ` +
+                        `Required fields: ${Array.from(requiredFields).join(', ')}`);
+                }
+                // Resolve any key defaults or computed keys
+                return (0, model_utils_1.resolveKeys)(model, key);
+            });
+            // Create the request items in the format expected by BatchGetItem
+            const requestItems = {
+                [tableName]: {
+                    Keys: resolvedKeys,
+                },
+            };
+            return (0, builders_1.createBatchGetBuilder)(requestItems, client, undefined, logger);
+        },
+        batchWrite(items) {
+            // Validate and process all items
+            const processedItems = items.map((item) => {
+                // Validate full input data
+                const parsed = zodSchema.parse(item);
+                // Apply post-processing defaults from the model (including timestamps for new items)
+                const withDefaults = (0, model_utils_1.applyPostDefaults)(model, parsed, {
+                    isUpdate: false,
+                    timestamps,
+                });
+                // Resolve keys again with defaults
+                const fullKey = (0, model_utils_1.resolveKeys)(model, withDefaults);
+                // Combine keys and data into full item, adding _type field
+                return {
+                    ...withDefaults,
+                    ...fullKey,
+                    _type: modelName, // Add entity type identifier
+                };
+            });
+            // Create the request items in the format expected by BatchWriteItem
+            const requestItems = {
+                [tableName]: processedItems.map((item) => ({
+                    PutRequest: {
+                        Item: item,
+                    },
+                })),
+            };
+            return (0, builders_1.createBatchWriteBuilder)(requestItems, client, logger);
+        },
+    };
+};
+exports.createEntityAPI = createEntityAPI;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './table';
+export { type SchemaDefinition, type ModelDefinition, type PrimaryKeyDefinition, type KeyDefinition, type AttributeDefinition, type IndexDefinition, type IndexesDefinition, type SchemaParams, type InferInput, type InferModel, type InferKeyInput, type InferModelFromSchema, type InferInputFromSchema, type TimestampFields, } from './core/types';
+export { createDynamoDBLogger, type DynamoDBLogger, type DynamoDBLoggerConfig, } from './utils/dynamodb-logger';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,oBAAoB,GAC1B,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDynamoDBLogger = void 0;
+__exportStar(require("./table"), exports);
+var dynamodb_logger_1 = require("./utils/dynamodb-logger");
+Object.defineProperty(exports, "createDynamoDBLogger", { enumerable: true, get: function () { return dynamodb_logger_1.createDynamoDBLogger; } });

package/dist/table.d.ts

@@ -0,0 +1,70 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { InferKeyInput, InferModelFromSchema, InferInputFromSchema, SchemaDefinition } from './core/types';
+import { EntityAPI } from './entity';
+import { TransactWriteBuilder } from './builders/transact-write';
+import { TransactGetBuilder } from './builders/transact-get';
+import { DynamoDBLogger } from './utils/dynamodb-logger';
+/**
+ * Configuration options for the Table instance
+ */
+export type TableConfig<S extends SchemaDefinition> = {
+    /** The DynamoDB table name */
+    name: string;
+    /** AWS DynamoDB client instance */
+    client: DynamoDBClient;
+    /** Optional logger instance for DynamoDB operations */
+    logger?: DynamoDBLogger;
+    /** The schema definition for all models in the table */
+    schema: S;
+};
+/**
+ * Internal helper type to infer all entity APIs from schema definition
+ */
+type EntityMap<S extends SchemaDefinition> = {
+    [K in keyof S['models']]: EntityAPI<InferModelFromSchema<S, K>, InferInputFromSchema<S, K>, InferKeyInput<S['models'][K]>>;
+};
+/**
+ * Represents a typed DynamoDB Table with entity APIs
+ *
+ * Provides access to all entity operations (get, put, delete, etc.)
+ * via `table.entities.<EntityName>`.
+ */
+export declare class Table<S extends SchemaDefinition> {
+    /** Generated entity APIs */
+    readonly entities: EntityMap<S>;
+    /** DynamoDB client */
+    private readonly client;
+    constructor(config: TableConfig<S>);
+    /**
+     * Creates a new TransactWrite builder for atomic multi-item write operations
+     *
+     * @returns A TransactWriteBuilder instance
+     *
+     * @example
+     * ```typescript
+     * // Like a photo atomically
+     * await table.transactWrite()
+     *   .addPut(table.entities.Like.put({ photoId: "123", likingUsername: "alice" }).dbParams())
+     *   .addUpdate(table.entities.Photo.update({ username: "bob", photoId: "123" }).add("likesCount", 1).dbParams())
+     *   .execute();
+     * ```
+     */
+    transactWrite(): TransactWriteBuilder;
+    /**
+     * Creates a new TransactGet builder for atomic multi-item read operations
+     *
+     * @returns A TransactGetBuilder instance
+     *
+     * @example
+     * ```typescript
+     * // Get user and photo atomically
+     * const [user, photo] = await table.transactGet()
+     *   .addGet(table.entities.User.get({ username: "alice" }).dbParams())
+     *   .addGet(table.entities.Photo.get({ username: "alice", photoId: "123" }).dbParams())
+     *   .execute();
+     * ```
+     */
+    transactGet(): TransactGetBuilder;
+}
+export {};
+//# sourceMappingURL=table.d.ts.map

package/dist/table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../src/table.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAmB,SAAS,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAA8B,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAC7F,OAAO,EAA4B,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,gBAAgB,IAAI;IACpD,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,MAAM,EAAE,cAAc,CAAC;IACvB,uDAAuD;IACvD,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,wDAAwD;IACxD,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AAEF;;GAEG;AACH,KAAK,SAAS,CAAC,CAAC,SAAS,gBAAgB,IAAI;KAC1C,CAAC,IAAI,MAAM,CAAC,CAAC,QAAQ,CAAC,GAAG,SAAS,CACjC,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAC9B;CACF,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,KAAK,CAAC,CAAC,SAAS,gBAAgB;IAC3C,4BAA4B;IAC5B,SAAgB,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IAEvC,sBAAsB;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;gBAE5B,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAsBlC;;;;;;;;;;;;;OAaG;IACH,aAAa,IAAI,oBAAoB;IAIrC;;;;;;;;;;;;;OAaG;IACH,WAAW,IAAI,kBAAkB;CAGlC"}

package/dist/table.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Table = void 0;
+const entity_1 = require("./entity");
+const transact_write_1 = require("./builders/transact-write");
+const transact_get_1 = require("./builders/transact-get");
+/**
+ * Represents a typed DynamoDB Table with entity APIs
+ *
+ * Provides access to all entity operations (get, put, delete, etc.)
+ * via `table.entities.<EntityName>`.
+ */
+class Table {
+    /** Generated entity APIs */
+    entities;
+    /** DynamoDB client */
+    client;
+    constructor(config) {
+        const { client, schema, logger, name: tableName } = config;
+        this.client = client;
+        const rawEntities = {};
+        for (const modelName in schema.models) {
+            const model = schema.models[modelName];
+            if (!model) {
+                throw new Error(`Model '${modelName}' is missing in schema`);
+            }
+            rawEntities[modelName] = (0, entity_1.createEntityAPI)(tableName, modelName, model, client, {
+                logger,
+                timestamps: schema.params?.timestamps ?? false,
+            });
+        }
+        this.entities = rawEntities;
+    }
+    /**
+     * Creates a new TransactWrite builder for atomic multi-item write operations
+     *
+     * @returns A TransactWriteBuilder instance
+     *
+     * @example
+     * ```typescript
+     * // Like a photo atomically
+     * await table.transactWrite()
+     *   .addPut(table.entities.Like.put({ photoId: "123", likingUsername: "alice" }).dbParams())
+     *   .addUpdate(table.entities.Photo.update({ username: "bob", photoId: "123" }).add("likesCount", 1).dbParams())
+     *   .execute();
+     * ```
+     */
+    transactWrite() {
+        return (0, transact_write_1.createTransactWriteBuilder)(this.client);
+    }
+    /**
+     * Creates a new TransactGet builder for atomic multi-item read operations
+     *
+     * @returns A TransactGetBuilder instance
+     *
+     * @example
+     * ```typescript
+     * // Get user and photo atomically
+     * const [user, photo] = await table.transactGet()
+     *   .addGet(table.entities.User.get({ username: "alice" }).dbParams())
+     *   .addGet(table.entities.Photo.get({ username: "alice", photoId: "123" }).dbParams())
+     *   .execute();
+     * ```
+     */
+    transactGet() {
+        return (0, transact_get_1.createTransactGetBuilder)(this.client);
+    }
+}
+exports.Table = Table;