betterddb/dist/betterddb.d.ts

A definition-based DynamoDB wrapper library that provides a schema-driven and fully typesafe DAL.

import { type z } from "zod";
import { QueryBuilder } from "./builders/query-builder.js";
import { ScanBuilder } from "./builders/scan-builder.js";
import { UpdateBuilder } from "./builders/update-builder.js";
import { CreateBuilder } from "./builders/create-builder.js";
import { GetBuilder } from "./builders/get-builder.js";
import { DeleteBuilder } from "./builders/delete-builder.js";
import { type NativeAttributeValue, type DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
import { BatchGetBuilder } from "./builders/batch-get-builder.js";
export type PrimaryKeyValue = string | number;
/**
 * A key definition can be either a simple key (a property name)
 * or an object containing a build function that computes the value.
 * (In this design, the attribute name is provided separately.)
 */
export type KeyDefinition<T> = keyof T | {
    build: (rawKey: Partial<T>) => string;
};
/**
 * Configuration for a primary (partition) key.
 */
export interface PrimaryKeyConfig<T> {
    /** The attribute name for the primary key in DynamoDB */
    name: string;
    /** How to compute the key value; if a keyof T, then the raw value is used;
     * if an object, the build function is used.
     */
    definition: KeyDefinition<T>;
}
/**
 * Configuration for a sort key.
 */
export interface SortKeyConfig<T> {
    /** The attribute name for the sort key in DynamoDB */
    name: string;
    /** How to compute the sort key value */
    definition: KeyDefinition<T>;
}
/**
 * Configuration for a Global Secondary Index (GSI).
 */
export interface GSIConfig<T> {
    /** The name of the GSI in DynamoDB */
    name: string;
    /** The primary key configuration for the GSI */
    primary: PrimaryKeyConfig<T>;
    /** The sort key configuration for the GSI, if any */
    sort?: SortKeyConfig<T>;
}
/**
 * Keys configuration for the table.
 */
export interface KeysConfig<T> {
    primary: PrimaryKeyConfig<T>;
    sort?: SortKeyConfig<T>;
    gsis?: Record<string, GSIConfig<T>>;
}
/**
 * Options for initializing BetterDDB.
 */
export interface BetterDDBOptions<T> {
    schema: z.AnyZodObject;
    tableName: string;
    entityType?: string;
    keys: KeysConfig<T>;
    client: DynamoDBDocumentClient;
    counter?: boolean;
    /**
     * If true, automatically inject timestamp fields:
     * - On create, sets both `createdAt` and `updatedAt`
     * - On update, sets `updatedAt`
     *
     * (T should include these fields if enabled.)
     */
    timestamps?: boolean;
}
/**
 * BetterDDB is a definition-based DynamoDB wrapper library.
 */
export declare class BetterDDB<T> {
    protected schema: z.AnyZodObject;
    protected tableName: string;
    protected entityType?: string;
    protected client: DynamoDBDocumentClient;
    protected keys: KeysConfig<T>;
    protected timestamps: boolean;
    protected counter: boolean;
    constructor(options: BetterDDBOptions<T>);
    getCounter(): boolean;
    getKeys(): KeysConfig<T>;
    getTableName(): string;
    getClient(): DynamoDBDocumentClient;
    getSchema(): z.AnyZodObject;
    getTimestamps(): boolean;
    getEntityType(): string | undefined;
    protected getKeyValue(def: KeyDefinition<T>, rawKey: Partial<T>): string;
    /**
     * Build the primary key from a raw key object.
     */
    buildKey(rawKey: Partial<T>): Record<string, NativeAttributeValue>;
    /**
     * Build index attributes for each defined GSI.
     */
    buildIndexes(rawItem: Partial<T>): Record<string, NativeAttributeValue>;
    /**
     * Create an item:
     * - Computes primary key and index attributes,
     * - Optionally injects timestamps,
     * - Validates the item and writes it to DynamoDB.
     */
    create(item: T): CreateBuilder<T>;
    /**
     * Get an item by its primary key.
     */
    get(rawKey: Partial<T>): GetBuilder<T>;
    /**
     * Get multiple items by their primary keys.
     */
    batchGet(rawKeys: Partial<T>[]): BatchGetBuilder<T>;
    /**
     * Update an item.
     */
    update(key: Partial<T>): UpdateBuilder<T>;
    /**
     * Delete an item.
     */
    delete(rawKey: Partial<T>): DeleteBuilder<T>;
    /**
     * Query items.
     */
    query(key: Partial<T>): QueryBuilder<T>;
    /**
     * Scan for items.
     */
    scan(): ScanBuilder<T>;
}
//# sourceMappingURL=betterddb.d.ts.map