betterddb 0.6.13 → 0.7.0

package/CONTRIBUTING.md

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

@@ -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

@@ -23,9 +23,9 @@ npm install betterddb
 ## Quick Start
 
 ```typescript
-import { BetterDDB } from 'betterddb';
-import { z } from 'zod';
-import { DynamoDBDocumentClient, DynamoDB } from '@aws-sdk/lib-dynamodb';
+import { BetterDDB } from "betterddb";
+import { z } from "zod";
+import { DynamoDBDocumentClient, DynamoDB } from "@aws-sdk/lib-dynamodb";
 
 // 1. Define your schema with Zod
 const UserSchema = z.object({
@@ -38,37 +38,39 @@ const UserSchema = z.object({
 type User = z.infer<typeof UserSchema>;
 
 // 2. Initialize DynamoDB client
-const client = DynamoDBDocumentClient.from(new DynamoDB({
-  region: 'us-east-1',
-}));
+const client = DynamoDBDocumentClient.from(
+  new DynamoDB({
+    region: "us-east-1",
+  }),
+);
 
 // 3. Create your BetterDDB instance
 const userDdb = new BetterDDB<User>({
   schema: UserSchema,
-  tableName: 'Users',
-  entityType: 'USER',
+  tableName: "Users",
+  entityType: "USER",
   keys: {
-    primary: { 
-      name: 'pk', 
-      definition: { build: (raw) => `USER#${raw.id}` } 
+    primary: {
+      name: "pk",
+      definition: { build: (raw) => `USER#${raw.id}` },
     },
-    sort: { 
-      name: 'sk', 
-      definition: { build: (raw) => `EMAIL#${raw.email}` } 
+    sort: {
+      name: "sk",
+      definition: { build: (raw) => `EMAIL#${raw.email}` },
     },
     gsis: {
       EmailIndex: {
-        name: 'EmailIndex',
-        primary: { 
-          name: 'gsi1pk', 
-          definition: { build: (raw) => `USER#${raw.email}` } 
+        name: "EmailIndex",
+        primary: {
+          name: "gsi1pk",
+          definition: { build: (raw) => `USER#${raw.email}` },
+        },
+        sort: {
+          name: "gsi1sk",
+          definition: { build: (raw) => `USER#${raw.email}` },
         },
-        sort: { 
-          name: 'gsi1sk', 
-          definition: { build: (raw) => `USER#${raw.email}` } 
-        }
-      }
-    }
+      },
+    },
   },
   client,
   timestamps: true,
@@ -77,22 +79,26 @@ const userDdb = new BetterDDB<User>({
 // 4. Use the fluent API for operations
 async function example() {
   // Create with automatic validation
-  const user = await userDdb.create({
-    id: 'user-123',
-    name: 'Alice',
-    email: 'alice@example.com'
-  }).execute();
+  const user = await userDdb
+    .create({
+      id: "user-123",
+      name: "Alice",
+      email: "alice@example.com",
+    })
+    .execute();
 
   // Query with type-safe filters
-  const results = await userDdb.query({ email: 'alice@example.com' })
-    .usingIndex('EmailIndex')
-    .filter('name', 'begins_with', 'A')
+  const results = await userDdb
+    .query({ email: "alice@example.com" })
+    .usingIndex("EmailIndex")
+    .filter("name", "begins_with", "A")
     .limitResults(10)
     .execute();
 
   // Update with automatic timestamp handling
-  const updated = await userDdb.update({ id: 'user-123' })
-    .set({ name: 'Alice B.' })
+  const updated = await userDdb
+    .update({ id: "user-123" })
+    .set({ name: "Alice B." })
     .execute();
 }
 ```
@@ -104,11 +110,13 @@ async function example() {
 BetterDDB uses Zod for both runtime validation and TypeScript type inference:
 
 ```typescript
-const Schema = z.object({
-  id: z.string(),
-  name: z.string(),
-  email: z.string().email(),
-}).passthrough(); // Allow computed fields
+const Schema = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string().email(),
+  })
+  .passthrough(); // Allow computed fields
 
 type Entity = z.infer<typeof Schema>; // TypeScript type inference
 ```
@@ -121,14 +129,14 @@ Define how your keys should be computed from your entity:
 const ddb = new BetterDDB<User>({
   keys: {
     primary: {
-      name: 'pk',
-      definition: { build: (raw) => `USER#${raw.id}` }
+      name: "pk",
+      definition: { build: (raw) => `USER#${raw.id}` },
     },
     sort: {
-      name: 'sk',
-      definition: { build: (raw) => `TYPE#${raw.type}` }
-    }
-  }
+      name: "sk",
+      definition: { build: (raw) => `TYPE#${raw.type}` },
+    },
+  },
 });
 ```
 
@@ -137,10 +145,11 @@ const ddb = new BetterDDB<User>({
 Fluent API for building type-safe queries:
 
 ```typescript
-const results = await ddb.query({ id: 'user-123' })
-  .usingIndex('EmailIndex')
-  .where('begins_with', { email: 'alice' })
-  .filter('name', 'contains', 'Smith')
+const results = await ddb
+  .query({ id: "user-123" })
+  .usingIndex("EmailIndex")
+  .where("begins_with", { email: "alice" })
+  .filter("name", "contains", "Smith")
   .limitResults(10)
   .execute();
 ```
@@ -164,4 +173,4 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 
 ## License
 
-MIT © Ryan Krumholz
+MIT © Ryan Rawlings Wang

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

@@ -0,0 +1,29 @@
+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.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/package.json

@@ -1,14 +1,18 @@
 {
   "name": "betterddb",
-  "version": "0.6.13",
+  "version": "0.7.0",
   "description": "A definition-based DynamoDB wrapper library that provides a schema-driven and fully typesafe DAL.",
-  "main": "dist/index.js",
-  "types": "dist/types/index.d.ts",
-  "files": [
-    "dist/**/*"
-  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "scripts": {
-    "prepublishOnly": "npm run build",
+    "build": "tsc",
     "docker:up": "docker-compose up -d",
     "docker:down": "docker-compose down",
     "test": "npm run docker:up && jest && npm run docker:down",
@@ -17,8 +21,7 @@
     "format": "prettier --write 'src/**/*.ts'",
     "lint": "eslint src/**/*.ts",
     "clean": "del-cli ./dist",
-    "build": "npm run clean && tsc -p ./tsconfig.json",
-    "prepack": "npm run build"
+    "typecheck": "tsc --noEmit"
   },
   "keywords": [
     "dynamodb",
@@ -40,9 +43,11 @@
     "zod": "^3.24.2"
   },
   "devDependencies": {
+    "@eslint/js": "^9.11.1",
     "@types/jest": "^29.5.14",
     "@types/node": "^22.13.5",
     "@typescript-eslint/eslint-plugin": "^8.24.1",
+    "@typescript-eslint/parser": "^8.24.1",
     "del-cli": "^6.0.0",
     "eslint": "^8.57.1",
     "eslint-config-prettier": "^9.1.0",
@@ -50,6 +55,6 @@
     "jest": "^29.7.0",
     "prettier": "^3.3.3",
     "ts-jest": "^29.2.5",
-    "typescript": "^4.9.5"
+    "typescript": "latest"
   }
 }

package/prettier.config.js

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