betterddb 0.1.0

package/LICENCSE

@@ -0,0 +1,21 @@
+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/README.md

@@ -0,0 +1,111 @@
+# betterddb
+
+**betterddb** is a definition-based DynamoDB wrapper library written in TypeScript. It provides a generic, schema-driven Data Access Layer (DAL) using [Zod](https://github.com/colinhacks/zod) for runtime validation and the AWS SDK for DynamoDB operations. With built-in support for compound keys, computed indexes, automatic timestamp injection, transactional and batch operations, and pagination for queries, **betterddb** lets you work with DynamoDB using definitions instead of ad hoc query code.
+
+## Installation
+
+```bash
+npm install betterddb
+```
+
+## Usage Example
+Below is an example of using betterddb for a User entity with a compound key.
+
+```ts
+import { BetterDDB } from 'betterddb';
+import { z } from 'zod';
+import { DynamoDB } from 'aws-sdk';
+
+// Define the User schema. Use .passthrough() if you want to allow extra keys (e.g. computed keys).
+const UserSchema = z.object({
+  tenantId: z.string(),
+  userId: z.string(),
+  email: z.string().email(),
+  name: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  version: z.number().optional()
+});
+
+// Configure the DynamoDB DocumentClient (for example, using LocalStack)
+const client = new DynamoDB.DocumentClient({
+  region: 'us-east-1',
+  endpoint: 'http://localhost:4566'
+});
+
+// Initialize BetterDDB with compound key definitions.
+const userDdb = new BetterDDB({
+  schema: UserSchema,
+  tableName: 'Users',
+  keys: {
+    primary: {
+      name: 'pk',
+      // Compute the partition key from tenantId
+      definition: { build: (raw) => `TENANT#${raw.tenantId}` }
+    },
+    sort: {
+      name: 'sk',
+      // Compute the sort key from userId
+      definition: { build: (raw) => `USER#${raw.userId}` }
+    },
+    gsis: {
+      // Example: a Global Secondary Index on email.
+      EmailIndex: {
+        primary: {
+          name: 'email',
+          definition: 'email'
+        }
+      }
+    }
+  },
+  client,
+  autoTimestamps: true
+});
+
+// Use the BetterDDB instance to create and query items.
+(async () => {
+  // Create a new user.
+  const newUser = await userDdb.create({
+    tenantId: 'tenant1',
+    userId: 'user123',
+    email: 'user@example.com',
+    name: 'Alice'
+  });
+  console.log('Created User:', newUser);
+
+  // Query by primary key with an optional sort key condition.
+  const { items, lastKey } = await userDdb.queryByPrimaryKey(
+    { tenantId: 'tenant1' },
+    { operator: 'begins_with', values: 'USER#user' },
+    { limit: 10 }
+  );
+  console.log('Queried Items:', items);
+  if (lastKey) {
+    console.log('More items available. Use lastKey for pagination:', lastKey);
+  }
+})();
+```
+
+## API
+betterddb exposes a generic class BetterDDB<T> with methods for:
+
+```ts
+create(item: T): Promise<T>
+get(rawKey: Partial<T>): Promise<T | null>
+update(rawKey: Partial<T>, update: Partial<T>, options?: { expectedVersion?: number }): Promise<T>
+delete(rawKey: Partial<T>): Promise<void>
+queryByGsi(gsiName: string, key: Partial<T>, sortKeyCondition?: { operator: "eq" | "begins_with" | "between"; values: any | [any, any] }): Promise<T[]>
+queryByPrimaryKey(rawKey: Partial<T>, sortKeyCondition?: { operator: "eq" | "begins_with" | "between"; values: any | [any, any] }, options?: { limit?: number; lastKey?: Record<string, any> }): Promise<{ items: T[]; lastKey?: Record<string, any> }>
+Batch operations:
+batchWrite(ops: { puts?: T[]; deletes?: Partial<T>[] }): Promise<void>
+batchGet(rawKeys: Partial<T>[]): Promise<T[]>
+Transaction helper methods:
+buildTransactPut(item: T)
+buildTransactUpdate(rawKey: Partial<T>, update: Partial<T>, options?: { expectedVersion?: number })
+buildTransactDelete(rawKey: Partial<T>)
+transactWrite(...) and transactGetByKeys(...)
+For complete details, please refer to the API documentation.
+```
+
+License
+MIT

package/docker-compose.yml

@@ -0,0 +1,16 @@
+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

@@ -0,0 +1,16 @@
+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/lib/betterddb.d.ts

@@ -0,0 +1,132 @@
+import { ZodSchema } from 'zod';
+import { DynamoDB } from 'aws-sdk';
+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> {
+    primary: PrimaryKeyConfig<T>;
+    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: ZodSchema<T>;
+    tableName: string;
+    keys: KeysConfig<T>;
+    client: DynamoDB.DocumentClient;
+    /**
+     * If true, automatically inject timestamp fields:
+     * - On create, sets both `createdAt` and `updatedAt`
+     * - On update, sets `updatedAt`
+     *
+     * (T should include these fields if enabled.)
+     */
+    autoTimestamps?: boolean;
+}
+/**
+ * BetterDDB is a definition-based DynamoDB wrapper library.
+ */
+export declare class BetterDDB<T> {
+    protected schema: ZodSchema<T>;
+    protected tableName: string;
+    protected client: DynamoDB.DocumentClient;
+    protected keys: KeysConfig<T>;
+    protected autoTimestamps: boolean;
+    constructor(options: BetterDDBOptions<T>);
+    protected getKeyValue(def: KeyDefinition<T>, rawKey: Partial<T>): string;
+    /**
+     * Build the primary key from a raw key object.
+     */
+    protected buildKey(rawKey: Partial<T>): Record<string, any>;
+    /**
+     * Build index attributes for each defined GSI.
+     */
+    protected buildIndexes(rawItem: Partial<T>): Record<string, any>;
+    /**
+     * Create an item:
+     * - Computes primary key and index attributes,
+     * - Optionally injects timestamps,
+     * - Validates the item and writes it to DynamoDB.
+     */
+    create(item: T): Promise<T>;
+    get(rawKey: Partial<T>): Promise<T | null>;
+    update(rawKey: Partial<T>, update: Partial<T>, options?: {
+        expectedVersion?: number;
+    }): Promise<T>;
+    delete(rawKey: Partial<T>): Promise<void>;
+    queryByGsi(gsiName: string, key: Partial<T>, sortKeyCondition?: {
+        operator: 'eq' | 'begins_with' | 'between';
+        values: any | [any, any];
+    }): Promise<T[]>;
+    /**
+     * Query by primary key (using the computed primary key) and an optional sort key condition.
+     */
+    queryByPrimaryKey(rawKey: Partial<T>, sortKeyCondition?: {
+        operator: 'eq' | 'begins_with' | 'between';
+        values: any | [any, any];
+    }, options?: {
+        limit?: number;
+        lastKey?: Record<string, any>;
+    }): Promise<{
+        items: T[];
+        lastKey?: Record<string, any>;
+    }>;
+    buildTransactPut(item: T): DynamoDB.DocumentClient.TransactWriteItem;
+    buildTransactUpdate(rawKey: Partial<T>, update: Partial<T>, options?: {
+        expectedVersion?: number;
+    }): DynamoDB.DocumentClient.TransactWriteItem;
+    buildTransactDelete(rawKey: Partial<T>): DynamoDB.DocumentClient.TransactWriteItem;
+    transactWrite(operations: DynamoDB.DocumentClient.TransactWriteItemList): Promise<void>;
+    transactGetByKeys(rawKeys: Partial<T>[]): Promise<T[]>;
+    transactGet(getItems: {
+        TableName: string;
+        Key: any;
+    }[]): Promise<T[]>;
+    batchWrite(ops: {
+        puts?: T[];
+        deletes?: Partial<T>[];
+    }): Promise<void>;
+    private batchWriteChunk;
+    private retryBatchWrite;
+    batchGet(rawKeys: Partial<T>[]): Promise<T[]>;
+}