dyno-table 2.5.2 → 2.6.1

package/dist/errors.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Base error class for all dyno-table errors
+ *
+ * All custom errors in the library extend this class, allowing consumers
+ * to catch all library errors with a single catch block if needed.
+ */
+export declare class DynoTableError extends Error {
+    /**
+     * Machine-readable error code for programmatic error handling
+     * @example "KEY_GENERATION_FAILED", "VALIDATION_ERROR", etc.
+     */
+    readonly code: string;
+    /**
+     * Additional context about the error
+     * Contains operation-specific details like entity names, table names,
+     * expressions, conditions, and other relevant debugging information
+     */
+    readonly context: Record<string, unknown>;
+    /**
+     * The original error that caused this error (if wrapping another error)
+     * Useful for preserving AWS SDK errors or other underlying errors
+     */
+    readonly cause?: Error;
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for schema validation and input validation failures
+ *
+ * Thrown when user-provided data doesn't match the expected schema
+ * or when required fields are missing.
+ */
+export declare class ValidationError extends DynoTableError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for DynamoDB operation failures
+ *
+ * Wraps AWS SDK errors and adds library-specific context like
+ * the operation type, table name, and generated expressions.
+ */
+export declare class OperationError extends DynoTableError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for transaction-specific failures
+ *
+ * Thrown when transaction operations fail, including duplicate item
+ * detection, transaction cancellation, and other transaction-related issues.
+ */
+export declare class TransactionError extends DynoTableError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for batch operation failures
+ *
+ * Thrown when batch operations fail or when batch limits are exceeded.
+ * Includes information about unprocessed items and operation details.
+ */
+export declare class BatchError extends DynoTableError {
+    /**
+     * The type of batch operation that failed
+     */
+    readonly operation: "write" | "read";
+    /**
+     * The items that were not processed during the batch operation
+     */
+    readonly unprocessedItems: unknown[];
+    constructor(message: string, code: string, operation: "write" | "read", unprocessedItems?: unknown[], context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for expression building failures
+ *
+ * Thrown when building DynamoDB expressions (condition, filter, update, etc.)
+ * fails due to invalid conditions or missing required fields.
+ */
+export declare class ExpressionError extends DynoTableError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for table/index configuration issues
+ *
+ * Thrown when there are problems with table configuration,
+ * such as missing GSIs or invalid index references.
+ */
+export declare class ConfigurationError extends DynoTableError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Base error for all entity-related errors
+ *
+ * Parent class for entity-specific errors like key generation
+ * and index generation failures.
+ */
+export declare class EntityError extends DynoTableError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for primary key generation failures
+ *
+ * Thrown when generating entity primary keys fails due to missing
+ * attributes or invalid key formats.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await userRepo.create({ name: "John" }).execute();
+ * } catch (error) {
+ *   if (error instanceof KeyGenerationError) {
+ *     console.error("Failed to generate key");
+ *     console.error("Entity:", error.context.entityName);
+ *     console.error("Required attributes:", error.context.requiredAttributes);
+ *   }
+ * }
+ * ```
+ */
+export declare class KeyGenerationError extends EntityError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for index key generation failures
+ *
+ * Thrown when generating secondary index keys fails due to missing
+ * attributes or when trying to update readonly indexes without forcing.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await orderRepo.update({ id: "123" }, { status: "shipped" }).execute();
+ * } catch (error) {
+ *   if (error instanceof IndexGenerationError) {
+ *     console.error("Index failed:", error.context.indexName);
+ *     console.error("Suggestion:", error.context.suggestion);
+ *   }
+ * }
+ * ```
+ */
+export declare class IndexGenerationError extends EntityError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error for entity schema validation failures
+ *
+ * Thrown when entity data doesn't pass schema validation.
+ * Includes validation issues and the entity context.
+ */
+export declare class EntityValidationError extends ValidationError {
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+}
+/**
+ * Error codes used throughout the library
+ *
+ * These codes allow for programmatic error handling and can be used
+ * to implement retry logic, user-friendly error messages, etc.
+ */
+export declare const ErrorCodes: {
+    readonly KEY_GENERATION_FAILED: "KEY_GENERATION_FAILED";
+    readonly KEY_MISSING_ATTRIBUTES: "KEY_MISSING_ATTRIBUTES";
+    readonly KEY_INVALID_FORMAT: "KEY_INVALID_FORMAT";
+    readonly INDEX_GENERATION_FAILED: "INDEX_GENERATION_FAILED";
+    readonly INDEX_MISSING_ATTRIBUTES: "INDEX_MISSING_ATTRIBUTES";
+    readonly INDEX_NOT_FOUND: "INDEX_NOT_FOUND";
+    readonly INDEX_READONLY_UPDATE_FAILED: "INDEX_READONLY_UPDATE_FAILED";
+    readonly INDEX_UNDEFINED_VALUES: "INDEX_UNDEFINED_VALUES";
+    readonly ENTITY_VALIDATION_FAILED: "ENTITY_VALIDATION_FAILED";
+    readonly ASYNC_VALIDATION_NOT_SUPPORTED: "ASYNC_VALIDATION_NOT_SUPPORTED";
+    readonly QUERY_INPUT_VALIDATION_FAILED: "QUERY_INPUT_VALIDATION_FAILED";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    readonly SCHEMA_VALIDATION_FAILED: "SCHEMA_VALIDATION_FAILED";
+    readonly INVALID_PARAMETER: "INVALID_PARAMETER";
+    readonly MISSING_REQUIRED_FIELD: "MISSING_REQUIRED_FIELD";
+    readonly UNDEFINED_VALUE: "UNDEFINED_VALUE";
+    readonly EXPRESSION_MISSING_ATTRIBUTE: "EXPRESSION_MISSING_ATTRIBUTE";
+    readonly EXPRESSION_MISSING_VALUE: "EXPRESSION_MISSING_VALUE";
+    readonly EXPRESSION_INVALID_CONDITION: "EXPRESSION_INVALID_CONDITION";
+    readonly EXPRESSION_EMPTY_ARRAY: "EXPRESSION_EMPTY_ARRAY";
+    readonly EXPRESSION_UNKNOWN_TYPE: "EXPRESSION_UNKNOWN_TYPE";
+    readonly EXPRESSION_INVALID: "EXPRESSION_INVALID";
+    readonly EXPRESSION_INVALID_OPERATOR: "EXPRESSION_INVALID_OPERATOR";
+    readonly QUERY_FAILED: "QUERY_FAILED";
+    readonly SCAN_FAILED: "SCAN_FAILED";
+    readonly GET_FAILED: "GET_FAILED";
+    readonly PUT_FAILED: "PUT_FAILED";
+    readonly DELETE_FAILED: "DELETE_FAILED";
+    readonly UPDATE_FAILED: "UPDATE_FAILED";
+    readonly BATCH_GET_FAILED: "BATCH_GET_FAILED";
+    readonly BATCH_WRITE_FAILED: "BATCH_WRITE_FAILED";
+    readonly NO_UPDATE_ACTIONS: "NO_UPDATE_ACTIONS";
+    readonly CONDITIONAL_CHECK_FAILED: "CONDITIONAL_CHECK_FAILED";
+    readonly TRANSACTION_FAILED: "TRANSACTION_FAILED";
+    readonly TRANSACTION_DUPLICATE_ITEM: "TRANSACTION_DUPLICATE_ITEM";
+    readonly TRANSACTION_EMPTY: "TRANSACTION_EMPTY";
+    readonly TRANSACTION_UNSUPPORTED_TYPE: "TRANSACTION_UNSUPPORTED_TYPE";
+    readonly TRANSACTION_ITEM_LIMIT: "TRANSACTION_ITEM_LIMIT";
+    readonly TRANSACTION_CANCELLED: "TRANSACTION_CANCELLED";
+    readonly BATCH_EMPTY: "BATCH_EMPTY";
+    readonly BATCH_UNSUPPORTED_TYPE: "BATCH_UNSUPPORTED_TYPE";
+    readonly BATCH_UNPROCESSED_ITEMS: "BATCH_UNPROCESSED_ITEMS";
+    readonly BATCH_SIZE_EXCEEDED: "BATCH_SIZE_EXCEEDED";
+    readonly GSI_NOT_FOUND: "GSI_NOT_FOUND";
+    readonly SORT_KEY_REQUIRED: "SORT_KEY_REQUIRED";
+    readonly SORT_KEY_NOT_DEFINED: "SORT_KEY_NOT_DEFINED";
+    readonly PRIMARY_KEY_MISSING: "PRIMARY_KEY_MISSING";
+    readonly INVALID_CHUNK_SIZE: "INVALID_CHUNK_SIZE";
+    readonly CONDITION_REQUIRED: "CONDITION_REQUIRED";
+    readonly CONDITION_GENERATION_FAILED: "CONDITION_GENERATION_FAILED";
+    readonly PK_EXTRACTION_FAILED: "PK_EXTRACTION_FAILED";
+    readonly CONFIGURATION_INVALID: "CONFIGURATION_INVALID";
+    readonly CONFIGURATION_MISSING_SORT_KEY: "CONFIGURATION_MISSING_SORT_KEY";
+    readonly CONFIGURATION_INVALID_GSI: "CONFIGURATION_INVALID_GSI";
+};
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];

package/dist/expression.d.ts

@@ -0,0 +1,9 @@
+import type { Condition, ExpressionParams } from "./conditions";
+export declare const generateAttributeName: (params: ExpressionParams, attr: string) => string;
+export declare const generateValueName: (params: ExpressionParams, value: unknown) => string;
+export declare const buildExpression: (condition: Condition, params: ExpressionParams) => string;
+export declare const prepareExpressionParams: (condition?: Condition) => {
+    expression?: string;
+    names?: Record<string, string>;
+    values?: Record<string, unknown>;
+};

package/dist/index-definition.d.ts

@@ -0,0 +1,10 @@
+import type { DynamoItem } from "./types";
+export interface IndexDefinition<T extends DynamoItem, P extends (item: T) => string, S extends ((item: T) => string) | undefined = undefined> {
+    name: string;
+    partitionKey: P;
+    sortKey?: S;
+    generateKey: (item: T) => {
+        pk: string;
+        sk?: string;
+    };
+}