betterddb 0.8.0 → 0.8.2

package/CONTRIBUTING.md

@@ -1,225 +0,0 @@
-# Contributing to BetterDDB
-
-First off, thank you for considering contributing to BetterDDB! It's people like you that make BetterDDB such a great tool.
-
-## Code of Conduct
-
-This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.
-
-## How Can I Contribute?
-
-### Reporting Bugs
-
-Before creating bug reports, please check the issue list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:
-
-- Use a clear and descriptive title
-- Describe the exact steps which reproduce the problem
-- Provide specific examples to demonstrate the steps
-- Describe the behavior you observed after following the steps
-- Explain which behavior you expected to see instead and why
-- Include code samples and error messages if applicable
-
-### Suggesting Enhancements
-
-Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include:
-
-- Use a clear and descriptive title
-- Provide a step-by-step description of the suggested enhancement
-- Provide specific examples to demonstrate the steps
-- Describe the current behavior and explain which behavior you expected to see instead
-- Explain why this enhancement would be useful
-
-### Pull Requests
-
-- Fork the repo and create your branch from `main`
-- If you've added code that should be tested, add tests
-- Ensure the test suite passes
-- Make sure your code lints
-- Update the documentation
-
-## Development Setup
-
-1. Fork and clone the repo
-2. Run `npm install` to install dependencies
-3. Start LocalStack for DynamoDB testing: `docker-compose up -d`
-4. Run `npm test` to run the tests
-5. Create a branch for your changes
-
-### Local Development Environment
-
-```bash
-# Install dependencies
-npm install
-
-# Start LocalStack (required for tests)
-docker-compose up -d
-
-# Run tests
-npm test
-
-# Run linter
-npm run lint
-
-# Build the project
-npm run build
-```
-
-## Testing
-
-We use Jest for testing against a local DynamoDB instance provided by LocalStack. All tests can be found in the `test/` directory.
-
-### Test Directory Structure
-
-```
-test/
-  ├── create.test.ts    # Tests for create operations
-  ├── get.test.ts       # Tests for get operations
-  ├── update.test.ts    # Tests for update operations
-  ├── delete.test.ts    # Tests for delete operations
-  ├── query.test.ts     # Tests for query operations
-  ├── scan.test.ts      # Tests for scan operations
-  ├── batch-get.test.ts # Tests for batch get operations
-  └── utils/
-      └── table-setup.ts # Utilities for setting up test tables
-```
-
-### Writing Tests
-
-Each test file focuses on a specific aspect of the library. Tests should follow this pattern:
-
-1. **Setup**: Define schema, table configuration, and BetterDDB instance
-2. **Initialize**: Create the test table in LocalStack before tests run
-3. **Test**: Write test cases for specific functionality
-4. **Cleanup**: Delete the test table after tests complete
-
-Here's an example of a basic test structure:
-
-```typescript
-import { z } from "zod";
-import { BetterDDB } from "../src/betterddb";
-import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
-import { DynamoDB } from "@aws-sdk/client-dynamodb";
-import { createTestTable, deleteTestTable } from "./utils/table-setup";
-
-// Constants for test configuration
-const TEST_TABLE = "my-test-table";
-const ENDPOINT = "http://localhost:4566";
-const REGION = "us-east-1";
-
-// Define schema and key configuration
-const MySchema = z.object({
-  id: z.string(),
-  name: z.string(),
-});
-
-// Create DynamoDB client
-const client = DynamoDBDocumentClient.from(
-  new DynamoDB({
-    region: REGION,
-    endpoint: ENDPOINT,
-  }),
-);
-
-// Create BetterDDB instance
-const myDdb = new BetterDDB({
-  schema: MySchema,
-  tableName: TEST_TABLE,
-  keys: {
-    primary: {
-      name: "pk",
-      definition: { build: (raw) => `ITEM#${raw.id}` },
-    },
-    sort: {
-      name: "sk",
-      definition: { build: (raw) => `ITEM` },
-    },
-  },
-  client,
-  timestamps: true,
-});
-
-// Setup and teardown
-beforeAll(async () => {
-  await createTestTable(TEST_TABLE, KEY_SCHEMA, ATTRIBUTE_DEFINITIONS, GSIS);
-});
-
-afterAll(async () => {
-  await deleteTestTable(TEST_TABLE);
-});
-
-// Test cases
-describe("My Feature", () => {
-  it("should do something specific", async () => {
-    // Test implementation
-    const result = await myDdb.create({ id: "123", name: "Test" }).execute();
-    expect(result.id).toBe("123");
-  });
-});
-```
-
-### Testing Utilities
-
-The `test/utils/table-setup.ts` file provides utilities for creating and deleting DynamoDB tables for testing:
-
-- **createTestTable**: Creates a DynamoDB table in LocalStack with the specified configuration
-- **deleteTestTable**: Deletes a DynamoDB table from LocalStack
-
-### Testing Best Practices
-
-1. **Isolated Tests**: Each test should be independent and not rely on other tests
-2. **Clean up after tests**: Always delete created resources to avoid interference
-3. **Test error cases**: Include tests for failure scenarios, not just success
-4. **Use constants**: Define table names, key names, etc. as constants
-5. **Test both simple and complex scenarios**: Cover the full range of functionality
-6. **Add tests for new features**: Any new functionality should have corresponding tests
-
-### Testing against LocalStack
-
-Tests run against a LocalStack instance, which provides a local DynamoDB implementation. To use this:
-
-1. Ensure Docker is installed and running
-2. Start LocalStack with `docker-compose up -d`
-3. Run tests with `npm test`
-
-The `docker-compose.yml` file in the repository configures the LocalStack environment.
-
-## Style Guide
-
-- We use ESLint and Prettier for code formatting
-- TypeScript is required for all new code
-- Follow the existing code style
-- Write descriptive commit messages
-- Add tests for new features
-- Update documentation for changes
-
-## Project Structure
-
-```
-src/
-  ├── builders/     # Query builders
-  ├── errors/       # Custom error types
-  ├── types/        # TypeScript type definitions
-  ├── betterddb.ts  # Main class
-  └── index.ts      # Public API
-test/
-  ├── *.test.ts     # Test files
-  └── utils/        # Test utilities
-```
-
-## Documentation
-
-- Keep README.md updated
-- Document new features
-- Keep code comments clear and relevant
-- Update TypeScript types
-- Update API_REFERENCE.md with new functionality
-
-## Community
-
-- Join our [Discussions](https://github.com/ryanrawlingswang/betterddb/discussions)
-
-## Questions?
-
-Feel free to open an issue or join our discussions if you have any questions.
-
-Thank you for contributing! 🎉

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/babel.config.cjs

@@ -1,6 +0,0 @@
-module.exports = {
-  presets: [
-    ['@babel/preset-env', { targets: { node: 'current' } }],
-    '@babel/preset-typescript',
-  ],
-}; 

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/eslint.config.mjs

@@ -1,29 +0,0 @@
-import js from '@eslint/js';
-import tseslint from '@typescript-eslint/eslint-plugin';
-import tsparser from '@typescript-eslint/parser';
-import prettier from 'eslint-plugin-prettier';
-
-export default [
-  js.configs.recommended,
-  {
-    files: ['**/*.ts'],
-    languageOptions: {
-      parser: tsparser,
-      parserOptions: {
-        ecmaVersion: 'latest',
-        sourceType: 'module',
-      },
-    },
-    plugins: {
-      '@typescript-eslint': tseslint,
-      prettier: prettier,
-    },
-    rules: {
-      'prettier/prettier': 'error',
-      // Basic TypeScript rules
-      '@typescript-eslint/no-unused-vars': 'warn',
-      '@typescript-eslint/no-explicit-any': 'warn',
-      '@typescript-eslint/no-non-null-assertion': 'warn',
-    },
-  },
-]; 

package/jest.config.cjs

@@ -1,17 +0,0 @@
-/** @type {import('jest').Config} */
-const config = {
-  testEnvironment: "node",
-  roots: ["<rootDir>/test/"],
-  testMatch: ["**/*.test.ts"],
-  transform: {
-    "^.+\\.(ts|tsx|js|jsx)$": "babel-jest"
-  },
-  moduleNameMapper: {
-    "^@/(.*)$": "<rootDir>/src/$1",
-    "^~/(.*)$": "<rootDir>/src/$1",
-    "^(\\.{1,2}/.*)\\.js$": "$1"
-  },
-  moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"]
-};
-
-module.exports = 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,267 +0,0 @@
-import { type 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 {
-  type NativeAttributeValue,
-  type 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?: 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 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>) {
-    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.AnyZodObject {
-    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, NativeAttributeValue> {
-    const keyObj: Record<string, NativeAttributeValue> = {};
-
-    // 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[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[skConfig.definition])
-          : skConfig.definition.build(rawKey);
-    }
-    return keyObj;
-  }
-
-  /**
-   * Build index attributes for each defined GSI.
-   */
-  public buildIndexes(
-    rawItem: Partial<T>,
-  ): Record<string, NativeAttributeValue> {
-    const indexAttributes: Record<string, NativeAttributeValue> = {};
-    if (this.keys.gsis) {
-      for (const gsiName in this.keys.gsis) {
-        const gsiConfig = this.keys.gsis[gsiName];
-        if (!gsiConfig) continue;
-
-        // 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[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[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 { type BetterDDB } from "../betterddb.js";
-import { BatchGetCommand } from "@aws-sdk/lib-dynamodb";
-import { type 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[];
-  }
-}