betterddb 0.6.8 → 0.6.9

package/src/betterddb.ts

@@ -1,263 +0,0 @@
-import { z } from "zod";
-import { QueryBuilder } from "./builders/query-builder";
-import { ScanBuilder } from "./builders/scan-builder";
-import { UpdateBuilder } from "./builders/update-builder";
-import { CreateBuilder } from "./builders/create-builder";
-import { GetBuilder } from "./builders/get-builder";
-import { DeleteBuilder } from "./builders/delete-builder";
-import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
-import { BatchGetBuilder } from "./builders/batch-get-builder";
-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?: {
-    [gsiName: string]: GSIConfig<T>;
-  };
-}
-
-/**
- * Options for initializing BetterDDB.
- */
-export interface BetterDDBOptions<T> {
-  schema: z.ZodType<T, z.ZodTypeDef, any>;
-  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 class BetterDDB<T> {
-  protected schema: z.ZodType<T, z.ZodTypeDef, any>;
-  protected tableName: string;
-  protected entityType?: string;
-  protected client: DynamoDBDocumentClient;
-  protected keys: KeysConfig<T>;
-  protected timestamps: boolean;
-  protected counter: boolean;
-
-  constructor(options: BetterDDBOptions<T>) {
-    this.schema = options.schema;
-    this.tableName = options.tableName;
-    this.entityType = options.entityType?.toUpperCase();
-    this.keys = options.keys;
-    this.client = options.client;
-    this.timestamps = options.timestamps ?? false;
-    this.counter = options.counter ?? false;
-  }
-
-  public getCounter(): boolean {
-    return this.counter;
-  }
-
-  public getKeys(): KeysConfig<T> {
-    return this.keys;
-  }
-
-  public getTableName(): string {
-    return this.tableName;
-  }
-
-  public getClient(): DynamoDBDocumentClient {
-    return this.client;
-  }
-
-  public getSchema(): z.ZodType<T, z.ZodTypeDef, any> {
-    return this.schema;
-  }
-
-  public getTimestamps(): boolean {
-    return this.timestamps;
-  }
-
-  public getEntityType(): string | undefined {
-    return this.entityType;
-  }
-
-  // Helper: Retrieve the key value from a KeyDefinition.
-  protected getKeyValue(def: KeyDefinition<T>, rawKey: Partial<T>): string {
-    if (
-      typeof def === "string" ||
-      typeof def === "number" ||
-      typeof def === "symbol"
-    ) {
-      return String(rawKey[def]);
-    } else {
-      return def.build(rawKey);
-    }
-  }
-
-  /**
-   * Build the primary key from a raw key object.
-   */
-  public buildKey(rawKey: Partial<T>): Record<string, any> {
-    const keyObj: Record<string, any> = {};
-
-    // For primary (partition) key:
-    const pkConfig = this.keys.primary;
-    keyObj[pkConfig.name] =
-      typeof pkConfig.definition === "string" ||
-      typeof pkConfig.definition === "number" ||
-      typeof pkConfig.definition === "symbol"
-        ? String((rawKey as any)[pkConfig.definition])
-        : pkConfig.definition.build(rawKey);
-
-    // For sort key, if defined:
-    if (this.keys.sort) {
-      const skConfig = this.keys.sort;
-      keyObj[skConfig.name] =
-        typeof skConfig.definition === "string" ||
-        typeof skConfig.definition === "number" ||
-        typeof skConfig.definition === "symbol"
-          ? String((rawKey as any)[skConfig.definition])
-          : skConfig.definition.build(rawKey);
-    }
-    return keyObj;
-  }
-
-  /**
-   * Build index attributes for each defined GSI.
-   */
-  public buildIndexes(rawItem: Partial<T>): Record<string, any> {
-    const indexAttributes: Record<string, any> = {};
-    if (this.keys.gsis) {
-      for (const gsiName in this.keys.gsis) {
-        const gsiConfig = this.keys.gsis[gsiName];
-
-        // Compute primary index attribute.
-        const primaryConfig = gsiConfig!.primary;
-        indexAttributes[primaryConfig.name] =
-          typeof primaryConfig.definition === "string" ||
-          typeof primaryConfig.definition === "number" ||
-          typeof primaryConfig.definition === "symbol"
-            ? String((rawItem as any)[primaryConfig.definition])
-            : primaryConfig.definition.build(rawItem);
-
-        // Compute sort index attribute if provided.
-        if (gsiConfig?.sort) {
-          const sortConfig = gsiConfig.sort;
-          indexAttributes[sortConfig.name] =
-            typeof sortConfig.definition === "string" ||
-            typeof sortConfig.definition === "number" ||
-            typeof sortConfig.definition === "symbol"
-              ? String((rawItem as any)[sortConfig.definition])
-              : sortConfig.definition.build(rawItem);
-        }
-      }
-    }
-    return indexAttributes;
-  }
-
-  /**
-   * Create an item:
-   * - Computes primary key and index attributes,
-   * - Optionally injects timestamps,
-   * - Validates the item and writes it to DynamoDB.
-   */
-  public create(item: T): CreateBuilder<T> {
-    return new CreateBuilder<T>(this, item);
-  }
-
-  /**
-   * Get an item by its primary key.
-   */
-  public get(rawKey: Partial<T>): GetBuilder<T> {
-    return new GetBuilder<T>(this, rawKey);
-  }
-
-  /**
-   * Get multiple items by their primary keys.
-   */
-  public batchGet(rawKeys: Partial<T>[]): BatchGetBuilder<T> {
-    return new BatchGetBuilder<T>(this, rawKeys);
-  }
-
-  /**
-   * Update an item.
-   */
-  public update(key: Partial<T>): UpdateBuilder<T> {
-    return new UpdateBuilder<T>(this, key);
-  }
-
-  /**
-   * Delete an item.
-   */
-  public delete(rawKey: Partial<T>): DeleteBuilder<T> {
-    return new DeleteBuilder<T>(this, rawKey);
-  }
-
-  /**
-   * Query items.
-   */
-  public query(key: Partial<T>): QueryBuilder<T> {
-    return new QueryBuilder<T>(this, key);
-  }
-
-  /**
-   * Scan for items.
-   */
-  public scan(): ScanBuilder<T> {
-    return new ScanBuilder<T>(this);
-  }
-}

package/src/builders/batch-get-builder.ts

@@ -1,56 +0,0 @@
-import { BetterDDB } from "../betterddb";
-import { BatchGetCommand } from "@aws-sdk/lib-dynamodb";
-import { BatchGetItemInput } from "@aws-sdk/client-dynamodb";
-
-export class BatchGetBuilder<T> {
-  /**
-   * @param parent - The BetterDDB instance for the table.
-   * @param keys - An array of partial keys for the items you wish to retrieve.
-   */
-  constructor(
-    private parent: BetterDDB<T>,
-    private keys: Partial<T>[],
-  ) {}
-
-  /**
-   * Executes the batch get operation.
-   * Returns an array of parsed items of type T.
-   */
-  public async execute(): Promise<T[]> {
-    if (this.keys.length === 0) {
-      return [];
-    }
-
-    const seen = new Set();
-    const deduplicatedKeys = this.keys.filter((key) => {
-      const keyString = JSON.stringify(key);
-      if (seen.has(keyString)) {
-        return false;
-      }
-      seen.add(keyString);
-      return true;
-    });
-    const tableName = this.parent.getTableName();
-    // Build an array of keys using the parent's key builder.
-    const keysArray = deduplicatedKeys.map((key) => this.parent.buildKey(key));
-
-    // Construct the BatchGet parameters.
-    const params: BatchGetItemInput = {
-      RequestItems: {
-        [tableName]: {
-          Keys: keysArray,
-        },
-      },
-    };
-
-    const result = await this.parent
-      .getClient()
-      .send(new BatchGetCommand(params));
-    const responses = result.Responses ? result.Responses[tableName] : [];
-    if (!responses) {
-      return [];
-    }
-
-    return this.parent.getSchema().array().parse(responses) as T[];
-  }
-}

package/src/builders/create-builder.ts

@@ -1,97 +0,0 @@
-import {
-  AttributeValue,
-  Put,
-  TransactWriteItem,
-} from "@aws-sdk/client-dynamodb";
-import { BetterDDB } from "../betterddb";
-import { PutCommand, TransactWriteCommand } from "@aws-sdk/lib-dynamodb";
-
-export class CreateBuilder<T> {
-  private extraTransactItems: TransactWriteItem[] = [];
-
-  constructor(
-    private parent: BetterDDB<T>,
-    private item: T,
-  ) {}
-
-  public async execute(): Promise<T> {
-    const validated = this.parent.getSchema().parse(this.item);
-    if (this.extraTransactItems.length > 0) {
-      // Build our update transaction item.
-      const myTransactItem = this.toTransactPut();
-      // Combine with extra transaction items.
-      const allItems = [...this.extraTransactItems, myTransactItem];
-      await this.parent.getClient().send(
-        new TransactWriteCommand({
-          TransactItems: allItems,
-        }),
-      );
-      // After transaction, retrieve the updated item.
-      const result = await this.parent.get(this.item).execute();
-      if (result === null) {
-        throw new Error("Item not found after transaction create");
-      }
-      return result;
-    } else {
-      let finalItem: T = {
-        ...this.item,
-        entityType: this.parent.getEntityType(),
-      };
-      if (this.parent.getTimestamps()) {
-        const now = new Date().toISOString();
-        finalItem = { ...finalItem, createdAt: now, updatedAt: now } as T;
-      }
-
-      // Compute and merge primary key.
-      const computedKeys = this.parent.buildKey(validated as Partial<T>);
-      finalItem = { ...finalItem, ...computedKeys };
-
-      // Compute and merge index attributes.
-      const indexAttributes = this.parent.buildIndexes(validated as Partial<T>);
-      finalItem = { ...finalItem, ...indexAttributes };
-
-      await this.parent.getClient().send(
-        new PutCommand({
-          TableName: this.parent.getTableName(),
-          Item: finalItem as Record<string, AttributeValue>,
-        }),
-      );
-
-      return validated as T;
-    }
-  }
-
-  public transactWrite(ops: TransactWriteItem[] | TransactWriteItem): this {
-    if (Array.isArray(ops)) {
-      this.extraTransactItems.push(...ops);
-    } else {
-      this.extraTransactItems.push(ops);
-    }
-    return this;
-  }
-
-  public toTransactPut(): TransactWriteItem {
-    const validated = this.parent.getSchema().parse(this.item);
-    let finalItem: T = {
-      ...this.item,
-      entityType: this.parent.getEntityType(),
-    };
-    if (this.parent.getTimestamps()) {
-      const now = new Date().toISOString();
-      finalItem = { ...finalItem, createdAt: now, updatedAt: now } as T;
-    }
-
-    // Compute and merge primary key.
-    const computedKeys = this.parent.buildKey(validated as Partial<T>);
-    finalItem = { ...finalItem, ...computedKeys };
-
-    // Compute and merge index attributes.
-    const indexAttributes = this.parent.buildIndexes(validated as Partial<T>);
-    finalItem = { ...finalItem, ...indexAttributes };
-    const putItem: Put = {
-      TableName: this.parent.getTableName(),
-      Item: finalItem as Record<string, AttributeValue>,
-    };
-    return { Put: putItem };
-  }
-}

package/src/builders/delete-builder.ts

@@ -1,80 +0,0 @@
-import { BetterDDB } from "../betterddb";
-import { TransactWriteItem, DeleteItemInput } from "@aws-sdk/client-dynamodb";
-import { TransactWriteCommand, DeleteCommand } from "@aws-sdk/lib-dynamodb";
-export class DeleteBuilder<T> {
-  private condition?: {
-    expression: string;
-    attributeValues: Record<string, any>;
-  };
-  private extraTransactItems: TransactWriteItem[] = [];
-  constructor(
-    private parent: BetterDDB<T>,
-    private key: Partial<T>,
-  ) {}
-
-  /**
-   * Specify a condition expression for the delete operation.
-   */
-  public withCondition(
-    expression: string,
-    attributeValues: Record<string, any>,
-  ): this {
-    if (this.condition) {
-      this.condition.expression += ` AND ${expression}`;
-      Object.assign(this.condition.attributeValues, attributeValues);
-    } else {
-      this.condition = { expression, attributeValues };
-    }
-    return this;
-  }
-
-  public async execute(): Promise<void> {
-    if (this.extraTransactItems.length > 0) {
-      // Build our update transaction item.
-      const myTransactItem = this.toTransactDelete();
-      // Combine with extra transaction items.
-      const allItems = [...this.extraTransactItems, myTransactItem];
-      await this.parent.getClient().send(
-        new TransactWriteCommand({
-          TransactItems: allItems,
-        }),
-      );
-      // After transaction, retrieve the updated item.
-      const result = await this.parent.get(this.key).execute();
-      if (result === null) {
-        throw new Error("Item not found after transaction delete");
-      }
-    } else {
-      const params: DeleteItemInput = {
-        TableName: this.parent.getTableName(),
-        Key: this.parent.buildKey(this.key),
-      };
-      if (this.condition) {
-        params.ConditionExpression = this.condition.expression;
-        params.ExpressionAttributeValues = this.condition.attributeValues;
-      }
-      await this.parent.getClient().send(new DeleteCommand(params));
-    }
-  }
-
-  public transactWrite(ops: TransactWriteItem[] | TransactWriteItem): this {
-    if (Array.isArray(ops)) {
-      this.extraTransactItems.push(...ops);
-    } else {
-      this.extraTransactItems.push(ops);
-    }
-    return this;
-  }
-
-  public toTransactDelete(): TransactWriteItem {
-    const deleteItem: DeleteItemInput = {
-      TableName: this.parent.getTableName(),
-      Key: this.parent.buildKey(this.key),
-    };
-    if (this.condition) {
-      deleteItem.ConditionExpression = this.condition.expression;
-      deleteItem.ExpressionAttributeValues = this.condition.attributeValues;
-    }
-    return { Delete: deleteItem };
-  }
-}

package/src/builders/get-builder.ts

@@ -1,75 +0,0 @@
-import { BetterDDB } from "../betterddb";
-import { TransactGetCommand, GetCommand } from "@aws-sdk/lib-dynamodb";
-import { GetItemInput, TransactGetItem } from "@aws-sdk/client-dynamodb";
-export class GetBuilder<T> {
-  private projectionExpression?: string;
-  private expressionAttributeNames: Record<string, string> = {};
-  private extraTransactItems: TransactGetItem[] = [];
-  constructor(
-    private parent: BetterDDB<T>,
-    private key: Partial<T>,
-  ) {}
-
-  /**
-   * Specify a projection by providing an array of attribute names.
-   */
-  public withProjection(attributes: (keyof T)[]): this {
-    this.projectionExpression = attributes
-      .map((attr) => `#${String(attr)}`)
-      .join(", ");
-    for (const attr of attributes) {
-      this.expressionAttributeNames[`#${String(attr)}`] = String(attr);
-    }
-    return this;
-  }
-
-  public async execute(): Promise<T | null> {
-    if (this.extraTransactItems.length > 0) {
-      // Build our update transaction item.
-      const myTransactItem = this.toTransactGet();
-      // Combine with extra transaction items.
-      const allItems = [...this.extraTransactItems, myTransactItem];
-      await this.parent.getClient().send(
-        new TransactGetCommand({
-          TransactItems: allItems,
-        }),
-      );
-      // After transaction, retrieve the updated item.
-      const result = await this.parent.get(this.key).execute();
-      return result;
-    } else {
-      const params: GetItemInput = {
-        TableName: this.parent.getTableName(),
-        Key: this.parent.buildKey(this.key),
-      };
-      if (this.projectionExpression) {
-        params.ProjectionExpression = this.projectionExpression;
-        params.ExpressionAttributeNames = this.expressionAttributeNames;
-      }
-      const result = await this.parent.getClient().send(new GetCommand(params));
-      if (!result.Item) return null;
-      return this.parent.getSchema().parse(result.Item) as T;
-    }
-  }
-
-  public transactGet(ops: TransactGetItem[] | TransactGetItem): this {
-    if (Array.isArray(ops)) {
-      this.extraTransactItems.push(...ops);
-    } else {
-      this.extraTransactItems.push(ops);
-    }
-    return this;
-  }
-
-  public toTransactGet(): TransactGetItem {
-    const getItem: GetItemInput = {
-      TableName: this.parent.getTableName(),
-      Key: this.parent.buildKey(this.key),
-    };
-    if (this.projectionExpression) {
-      getItem.ProjectionExpression = this.projectionExpression;
-      getItem.ExpressionAttributeNames = this.expressionAttributeNames;
-    }
-    return { Get: getItem };
-  }
-}