betterddb 0.6.4 → 0.6.5

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "betterddb",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "A definition-based DynamoDB wrapper library that provides a schema-driven and fully typesafe DAL.",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
+  "types": "./lib/index.d.ts",
+  "main": "./lib/index.js",
+  "files": [
+    "lib/**/*"
+  ],
   "scripts": {
     "prepublishOnly": "npm run build",
     "docker:up": "docker-compose up -d",

package/.eslintrc.cjs

@@ -1,41 +0,0 @@
-/** @type {import("eslint").Linter.Config} */
-const config = {
-  "parser": "@typescript-eslint/parser",
-  "parserOptions": {
-    "project": true
-  },
-  "plugins": [
-    "@typescript-eslint"
-  ],
-  "extends": [
-    "plugin:@typescript-eslint/recommended-type-checked",
-    "plugin:@typescript-eslint/stylistic-type-checked"
-  ],
-  "rules": {
-    "@typescript-eslint/array-type": "off",
-    "@typescript-eslint/consistent-type-definitions": "off",
-    "@typescript-eslint/consistent-type-imports": [
-      "warn",
-      {
-        "prefer": "type-imports",
-        "fixStyle": "inline-type-imports"
-      }
-    ],
-    "@typescript-eslint/no-unused-vars": [
-      "warn",
-      {
-        "argsIgnorePattern": "^_"
-      }
-    ],
-    "@typescript-eslint/require-await": "off",
-    "@typescript-eslint/no-misused-promises": [
-      "error",
-      {
-        "checksVoidReturn": {
-          "attributes": false
-        }
-      }
-    ]
-  }
-}
-module.exports = config;

package/.github/workflows/npm-publish.yml

@@ -1,33 +0,0 @@
-# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
-# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
-
-name: Node.js Package
-
-on:
-  release:
-    types: [created]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-      - run: npm ci
-      - run: npm test
-
-  publish-npm:
-    needs: build
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org/
-      - run: npm ci
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/LICENCSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Ryan Rawlings Wang
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/docker-compose.yml

@@ -1,16 +0,0 @@
-version: '3.8'
-services:
-  betterddb-localstack:
-    image: localstack/localstack:latest
-    container_name: betterddb-localstack
-    ports:
-      - "4566:4566"  # Main edge port
-      - "4571:4571"
-    environment:
-      - SERVICES=dynamodb
-      - DEFAULT_REGION=us-east-1
-      - DATA_DIR=/tmp/localstack_data
-      - HOST_TMP_FOLDER=${TMPDIR:-/tmp}/localstack
-      - LOCALSTACK_UI=1
-    volumes:
-      - "./localstack-tmp:/tmp/localstack_data"

package/jest.config.js

@@ -1,16 +0,0 @@
-const config = {
-  testEnvironment: 'node',
-  roots: ['<rootDir>/test/'],
-  testMatch: ['**/*.test.ts'],
-  transform: {
-    '^.+\\.(ts|tsx|js|jsx)$': 'ts-jest'
-  },
-  moduleNameMapper: {
-    '^@/(.*)$': '<rootDir>/src/$1',
-    '^~/(.*)$': '<rootDir>/src/$1'
-  },
-  extensionsToTreatAsEsm: ['.ts', '.tsx'],
-  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node']
-}
- 
-export default config;

package/prettier.config.js

@@ -1,6 +0,0 @@
-/** @type {import('prettier').Config} */
-const config = {
-  tabWidth: 2,
-};
-
-export default config;

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 };
-  }
-}