dyno-table 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,344 @@
+# 🦖 dyno-table
+
+A powerful, type-safe, and fluent DynamoDB table abstraction layer for Node.js applications.
+
+Allows you to work with DynamoDB in a single table design pattern
+
+## ✨ Features
+
+- **Type-safe operations**: Ensures type safety for all DynamoDB operations.
+- **Builders for operations**: Provides builders for put, update, delete, query, and scan operations.
+- **Transaction support**: Supports transactional operations.
+- **Batch operations**: Handles batch write operations with automatic chunking for large datasets.
+- **Conditional operations**: Supports conditional puts, updates, and deletes.
+- **Repository pattern**: Provides a base repository class for implementing the repository pattern.
+- **Error handling**: Custom error classes for handling DynamoDB errors gracefully.
+
+## 📦 Installation
+
+Get started with Dyno Table by installing it via npm:
+
+```bash
+npm install dyno-table
+```
+
+## 🦕 Getting Started
+
+### Setting Up the Table
+
+First, set up the `Table` instance with your DynamoDB client and table configuration.
+
+```ts
+import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";
+import { Table } from "dyno-table";
+import { docClient } from "./ddb-client"; // Your DynamoDB client instance
+
+const table = new Table({
+  client: docClient,
+  tableName: "DinoTable",
+  tableIndexes: {
+    primary: {
+      pkName: "pk",
+      skName: "sk",
+    },
+    GSI1: {
+      pkName: "GSI1PK",
+      skName: "GSI1SK",
+    },
+  },
+});
+```
+
+### CRUD Operations
+
+#### Create (Put)
+
+```ts
+// Simple put
+const dino = {
+  pk: "SPECIES#trex",
+  sk: "PROFILE#001",
+  name: "Rex",
+  diet: "Carnivore",
+  length: 40,
+  type: "DINOSAUR",
+};
+
+await table.put(dino).execute();
+
+// Conditional put
+await table
+  .put(dino)
+  .whereNotExists("pk")  // Only insert if dinosaur doesn't exist
+  .whereNotExists("sk")
+  .execute();
+```
+
+#### Read (Get)
+
+```ts
+const key = { pk: "SPECIES#trex", sk: "PROFILE#001" };
+const result = await table.get(key);
+console.log(result);
+
+// Get with specific index
+const result = await table.get(key, { indexName: "GSI1" });
+```
+
+#### Update
+
+```ts
+// Simple update
+const updates = { length: 42, diet: "Carnivore" };
+await table.update(key).setMany(updates).execute();
+
+// Advanced update operations
+await table
+  .update(key)
+  .set("diet", "Omnivore")              // Set a single field
+  .set({ length: 45, name: "Rexy" })    // Set multiple fields
+  .remove("optional_field")              // Remove fields
+  .increment("sightings", 1)             // Increment a number
+  .whereEquals("length", 42)             // Conditional update
+  .execute();
+```
+
+#### Delete
+
+```ts
+// Simple delete
+await table.delete(key).execute();
+
+// Conditional delete
+await table
+  .delete(key)
+  .whereExists("pk")
+  .whereEquals("type", "DINOSAUR")
+  .execute();
+```
+
+### Query Operations
+
+```ts
+// Basic query
+const result = await table
+  .query({ pk: "SPECIES#trex" })
+  .execute();
+
+// Advanced query with conditions
+const result = await table
+  .query({
+    pk: "SPECIES#velociraptor",
+    sk: { operator: "begins_with", value: "PROFILE#" }
+  })
+  .where("type", "=", "DINOSAUR")
+  .whereGreaterThan("length", 6)
+  .limit(10)
+  .useIndex("GSI1")
+  .execute();
+
+// Available query conditions:
+// .where(field, operator, value)        // Generic condition
+// .whereEquals(field, value)            // Equality check
+// .whereBetween(field, start, end)      // Range check
+// .whereIn(field, values)               // IN check
+// .whereLessThan(field, value)          // < check
+// .whereLessThanOrEqual(field, value)   // <= check
+// .whereGreaterThan(field, value)       // > check
+// .whereGreaterThanOrEqual(field, value) // >= check
+// .whereNotEqual(field, value)          // <> check
+// .whereBeginsWith(field, value)        // begins_with check
+// .whereContains(field, value)          // contains check
+// .whereNotContains(field, value)       // not_contains check
+// .whereExists(field)                   // attribute_exists check
+// .whereNotExists(field)                // attribute_not_exists check
+// .whereAttributeType(field, type)      // attribute_type check
+```
+
+### Scan Operations
+
+```ts
+// Basic scan
+const result = await table.scan().execute();
+
+// Filtered scan
+const result = await table
+  .scan()
+  .whereEquals("type", "DINOSAUR")
+  .where("length", ">", 20)
+  .limit(20)
+  .execute();
+
+// Scan supports all the same conditions as Query operations
+```
+
+### Batch Operations
+
+```ts
+// Batch write (put)
+const dinos = [
+  { pk: "SPECIES#trex", sk: "PROFILE#001", name: "Rex", length: 40 },
+  { pk: "SPECIES#raptor", sk: "PROFILE#001", name: "Blue", length: 6 },
+];
+
+await table.batchWrite(
+  dinos.map((dino) => ({ type: "put", item: dino }))
+);
+
+// Batch write (delete)
+await table.batchWrite([
+  { type: "delete", key: { pk: "SPECIES#trex", sk: "PROFILE#001" } },
+  { type: "delete", key: { pk: "SPECIES#raptor", sk: "PROFILE#001" } },
+]);
+
+// Batch operations automatically handle chunking for large datasets
+```
+
+### Pagination
+
+```ts
+// Limit to 10 items per page
+const paginator = await table.query({ pk: "SPECIES#trex" }).limit(10).paginate();
+// const paginator = await table.scan().limit(10).paginate();
+
+while (paginator.hasNextPage()) {
+  const page = await paginator.getPage();
+  console.log(page);
+}
+```
+
+### Transaction Operations
+
+Two ways to perform transactions:
+
+#### Using withTransaction
+
+```ts
+await table.withTransaction(async (trx) => {
+  table.put(trex).withTransaction(trx);
+  table.put(raptor).withTransaction(trx);
+  table.delete(brontoKey).withTransaction(trx);
+});
+```
+
+#### Using TransactionBuilder
+
+```ts
+const transaction = new TransactionBuilder();
+
+transaction
+  .addOperation({
+    put: { item: trex }
+  })
+  .addOperation({
+    put: { item: raptor }
+  })
+  .addOperation({
+    delete: { key: brontoKey }
+  });
+
+await table.transactWrite(transaction);
+```
+
+## Repository Pattern
+
+Create a repository by extending the `BaseRepository` class.
+
+```ts
+import { BaseRepository } from "dyno-table";
+
+type DinoRecord = {
+  id: string;
+  name: string;
+  diet: string;
+  length: number;
+};
+
+class DinoRepository extends BaseRepository<DinoRecord> {
+  protected createPrimaryKey(data: DinoRecord) {
+    return {
+      pk: `SPECIES#${data.id}`,
+      sk: `PROFILE#${data.id}`,
+    };
+  }
+
+  protected getType() {
+    return "DINOSAUR";
+  }
+
+  // Add custom methods
+  async findByDiet(diet: string) {
+    return this.scan()
+      .whereEquals("diet", diet)
+      .execute();
+  }
+
+  async findLargerThan(length: number) {
+    return this.scan()
+      .whereGreaterThan("length", length)
+      .execute();
+  }
+}
+```
+
+### Repository Operations
+
+The repository pattern in dyno-table not only provides a clean abstraction but also ensures data isolation through type-scoping. All operations available on the `Table` class are also available on your repository, but they're automatically scoped to the repository's type.
+
+```ts
+const dinoRepo = new DinoRepository(table);
+
+// Query all T-Rexes - automatically includes type="DINOSAUR" condition
+const rexes = await dinoRepo
+  .query({ pk: "SPECIES#trex" })
+  .execute();
+
+// Scan for large carnivores - automatically includes type="DINOSAUR"
+const largeCarnivores = await dinoRepo
+  .scan()
+  .whereEquals("diet", "Carnivore")
+  .whereGreaterThan("length", 30)
+  .execute();
+
+// Put operation, the type attribute is automatically along with the primary key/secondary key is created
+await dinoRepo.create({
+  id: "trex",
+  name: "Rex",
+  diet: "Carnivore",
+  length: 40
+}).execute();
+
+// Update operation
+await dinoRepo
+  .update({ pk: "SPECIES#trex", sk: "PROFILE#001" })
+  .set("diet", "Omnivore")
+  .execute();
+
+// Delete operation
+await dinoRepo
+  .delete({ pk: "SPECIES#trex", sk: "PROFILE#001" })
+  .execute();
+```
+
+This type-scoping ensures that:
+- Each repository only accesses its own data type
+- Queries automatically include type filtering
+- Put operations automatically include the type attribute
+- Updates and deletes are constrained to the correct type
+
+This pattern is particularly useful in single-table designs where multiple entity types share the same table. Each repository provides a type-safe, isolated view of its own data while preventing accidental cross-type operations.
+
+## Contributing 🤝
+```bash
+# Installing the dependencies
+pnpm i
+
+# Installing the peerDependencies manually
+pnpm i @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
+```
+
+### Developing
+
+```bash
+docker run -p 8000:8000 amazon/dynamodb-local
+```

package/dist/index.d.ts

@@ -1,6 +1,4 @@
-import * as _aws_sdk_lib_dynamodb from '@aws-sdk/lib-dynamodb';
 import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
-import { z } from 'zod';
 
 interface ExpressionAttributes {
     names?: Record<string, string>;
@@ -94,6 +92,13 @@ interface DynamoDeleteOperation {
     key: PrimaryKeyWithoutExpression;
     condition?: DynamoExpression;
 }
+interface DynamoScanOperation {
+    type: "scan";
+    filter?: DynamoExpression;
+    limit?: number;
+    pageKey?: Record<string, unknown>;
+    indexName?: string;
+}
 interface DynamoBatchWriteOperation {
     type: "batchWrite";
     operations: DynamoBatchWriteItem[];
@@ -116,7 +121,7 @@ interface DynamoTransactOperation {
         };
     }>;
 }
-type DynamoOperation = DynamoPutOperation | DynamoUpdateOperation | DynamoQueryOperation | DynamoDeleteOperation | DynamoBatchWriteOperation | DynamoTransactOperation;
+type DynamoOperation = DynamoPutOperation | DynamoUpdateOperation | DynamoQueryOperation | DynamoDeleteOperation | DynamoBatchWriteOperation | DynamoTransactOperation | DynamoScanOperation;
 type PrimaryKeyWithoutExpression = {
     pk: string;
     sk?: string;
@@ -129,72 +134,121 @@ type BatchWriteOperation = {
     key: PrimaryKeyWithoutExpression;
 };
 
-declare abstract class OperationBuilder<T extends DynamoOperation> {
+interface DynamoRecord {
+    [key: string]: unknown;
+}
+
+type StringKeys<T> = Extract<keyof T, string>;
+/**
+ * Base builder class for DynamoDB operations that supports condition expressions
+ * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html
+ */
+declare abstract class OperationBuilder<T extends DynamoRecord, TOperation extends DynamoOperation> {
     protected expressionBuilder: IExpressionBuilder;
     protected conditions: Array<{
-        field: string;
+        field: keyof T;
         operator: ConditionOperator;
         value?: unknown;
     }>;
     constructor(expressionBuilder: IExpressionBuilder);
-    where(field: string, operator: FilterOperator, value: unknown): this;
-    whereExists(field: string): this;
-    whereNotExists(field: string): this;
-    whereEquals(field: string, value: unknown): this;
-    whereBetween(field: string, start: unknown, end: unknown): this;
-    whereIn(field: string, values: unknown[]): this;
+    where<K extends keyof T>(field: K, operator: FilterOperator, value: T[K] | T[K][]): this;
+    whereExists<K extends StringKeys<T>>(field: K): this;
+    whereNotExists<K extends keyof T>(field: K): this;
+    whereEquals<K extends keyof T>(field: K, value: T[K]): this;
+    whereBetween<K extends keyof T>(field: K, start: T[K], end: T[K]): this;
+    whereIn<K extends keyof T>(field: K, values: T[K][]): this;
+    whereLessThan<K extends keyof T>(field: K, value: T[K]): this;
+    whereLessThanOrEqual<K extends keyof T>(field: K, value: T[K]): this;
+    whereGreaterThan<K extends keyof T>(field: K, value: T[K]): this;
+    whereGreaterThanOrEqual<K extends keyof T>(field: K, value: T[K]): this;
+    whereNotEqual<K extends keyof T>(field: K, value: T[K]): this;
+    whereBeginsWith<K extends keyof T>(field: K, value: T[K]): this;
+    whereContains<K extends keyof T>(field: K, value: T[K]): this;
+    whereNotContains<K extends keyof T>(field: K, value: T[K]): this;
+    whereAttributeType<K extends keyof T>(field: K, value: "S" | "SS" | "N" | "NS" | "B" | "BS" | "BOOL" | "NULL" | "M" | "L"): this;
+    whereSize<K extends keyof T>(field: K, value: T[K]): this;
     protected buildConditionExpression(): ExpressionResult;
-    abstract build(): T;
+    abstract build(): TOperation;
 }
 
-declare class PutBuilder extends OperationBuilder<DynamoPutOperation> {
-    private readonly item;
+declare class PutBuilder<T extends DynamoRecord> extends OperationBuilder<T, DynamoPutOperation> {
     private readonly onBuild;
-    constructor(item: Record<string, unknown>, expressionBuilder: IExpressionBuilder, onBuild: (operation: DynamoPutOperation) => Promise<void>);
+    private item;
+    constructor(item: T, expressionBuilder: IExpressionBuilder, onBuild: (operation: DynamoPutOperation) => Promise<T>);
+    set<K extends keyof T>(field: K, value: T[K]): this;
+    setMany(attributes: Partial<T>): this;
     build(): DynamoPutOperation;
-    execute(): Promise<void>;
+    /**
+     * Runs the put operation to insert the provided attributes into the table.
+     *
+     * @returns The provided attributes. This does not load the model from the DB after insert
+     */
+    execute(): Promise<T>;
+}
+
+interface DynamoQueryResponse {
+    Items?: Record<string, unknown>[];
+    Count?: number;
+    ScannedCount?: number;
+    LastEvaluatedKey?: Record<string, unknown>;
 }
 
-declare class QueryBuilder extends OperationBuilder<DynamoQueryOperation> {
+declare class QueryBuilder<T extends DynamoRecord> extends OperationBuilder<T, DynamoQueryOperation> {
     private readonly key;
     private readonly indexConfig;
     private readonly onBuild;
     private limitValue?;
     private indexNameValue?;
-    constructor(key: PrimaryKey, indexConfig: TableIndexConfig, expressionBuilder: IExpressionBuilder, onBuild: (operation: DynamoQueryOperation) => Promise<{
-        Items?: Record<string, unknown>[];
-        Count?: number;
-        ScannedCount?: number;
-        LastEvaluatedKey?: Record<string, unknown>;
-    }>);
+    constructor(key: PrimaryKey, indexConfig: TableIndexConfig, expressionBuilder: IExpressionBuilder, onBuild: (operation: DynamoQueryOperation) => Promise<DynamoQueryResponse>);
     limit(value: number): this;
     useIndex(indexName: string): this;
     build(): DynamoQueryOperation;
-    execute(): Promise<{
-        Items?: Record<string, unknown>[];
-        Count?: number;
-        ScannedCount?: number;
-        LastEvaluatedKey?: Record<string, unknown>;
-    }>;
+    execute(): Promise<DynamoQueryResponse>;
 }
 
-declare class UpdateBuilder extends OperationBuilder<DynamoUpdateOperation> {
+declare class UpdateBuilder<T extends DynamoRecord> extends OperationBuilder<T, DynamoUpdateOperation> {
     private readonly key;
     private readonly onBuild;
     private updates;
     constructor(key: PrimaryKeyWithoutExpression, expressionBuilder: IExpressionBuilder, onBuild: (operation: DynamoUpdateOperation) => Promise<{
-        Attributes?: Record<string, unknown>;
+        Attributes?: T;
     }>);
-    set(field: string, value: unknown): this;
-    setMany(attribtues: Record<string, unknown>): this;
-    remove(...fields: string[]): this;
-    increment(field: string, by?: number): this;
+    set<K extends keyof T>(field: K, value: T[K]): this;
+    setMany(attributes: Partial<T>): this;
+    remove(...fields: Array<keyof T>): this;
+    increment<K extends keyof T>(field: K, by?: number): this;
     build(): DynamoUpdateOperation;
     execute(): Promise<{
-        Attributes?: Record<string, unknown>;
+        Attributes?: T;
     }>;
 }
 
+declare class ScanBuilder<T extends DynamoRecord> extends OperationBuilder<T, DynamoScanOperation> {
+    private readonly onBuild;
+    private limitValue?;
+    private indexNameValue?;
+    private pageKeyValue?;
+    constructor(expressionBuilder: IExpressionBuilder, onBuild: (operation: DynamoScanOperation) => Promise<DynamoQueryResponse>);
+    limit(value: number): this;
+    useIndex(indexName: string): this;
+    startKey(key: Record<string, unknown>): this;
+    build(): {
+        type: "scan";
+        filter: {
+            expression: string;
+            names: Record<string, string> | undefined;
+            values: Record<string, unknown> | undefined;
+        } | undefined;
+        limit: number | undefined;
+        pageKey: Record<string, unknown> | undefined;
+        indexName: string | undefined;
+    };
+    execute(): Promise<DynamoQueryResponse>;
+}
+
+type IndexConfig = Record<string, TableIndexConfig> & {
+    primary: TableIndexConfig;
+};
 declare class Table {
     private readonly dynamoService;
     private readonly expressionBuilder;
@@ -202,22 +256,18 @@ declare class Table {
     constructor({ client, tableName, tableIndexes, expressionBuilder, }: {
         client: DynamoDBDocument;
         tableName: string;
-        tableIndexes: Record<string, TableIndexConfig>;
+        tableIndexes: IndexConfig;
         expressionBuilder?: ExpressionBuilder;
     });
     getIndexConfig(indexName?: string): TableIndexConfig;
-    put(item: Record<string, unknown>): PutBuilder;
-    update(key: PrimaryKeyWithoutExpression, data?: Record<string, unknown>): UpdateBuilder;
-    query(key: PrimaryKey): QueryBuilder;
+    put<T extends DynamoRecord>(item: T): PutBuilder<T>;
+    update<T extends DynamoRecord>(key: PrimaryKeyWithoutExpression, data?: Partial<T>): UpdateBuilder<T>;
+    query<T extends DynamoRecord>(key: PrimaryKey): QueryBuilder<T>;
     get(key: PrimaryKeyWithoutExpression, options?: {
         indexName?: string;
     }): Promise<Record<string, any> | undefined>;
     delete(key: PrimaryKeyWithoutExpression): Promise<unknown>;
-    scan(filters?: FilterCondition[], options?: {
-        limit?: number;
-        pageKey?: Record<string, unknown>;
-        indexName?: string;
-    }): Promise<_aws_sdk_lib_dynamodb.ScanCommandOutput>;
+    scan<T extends DynamoRecord>(): ScanBuilder<T>;
     batchWrite(operations: BatchWriteOperation[]): Promise<unknown>;
     transactWrite(operations: Array<{
         put?: {
@@ -255,29 +305,100 @@ declare class Table {
     private validateKey;
 }
 
-type InferZodSchema<T extends z.ZodType> = z.infer<T>;
-declare abstract class BaseRepository<TSchema extends z.ZodType> {
+declare abstract class BaseRepository<TData extends DynamoRecord> {
     protected readonly table: Table;
-    protected readonly schema: TSchema;
-    constructor(table: Table, schema: TSchema);
-    protected abstract createPrimaryKey(data: InferZodSchema<TSchema>): PrimaryKeyWithoutExpression;
-    protected abstract getIndexKeys(): {
-        pk: string;
-        sk?: string;
-    };
+    constructor(table: Table);
+    /**
+     * Templates out the primary key for the record, it is consumed for create, put, update and delete actions
+     *
+     * Unfortunately, TypeScript is not inferring the TData type when implmenting this method in a subclass.
+     * https://github.com/microsoft/TypeScript/issues/32082
+     */
+    protected abstract createPrimaryKey(data: TData): PrimaryKeyWithoutExpression;
     /**
      * Default attribute applied to ALL records that get stored in DDB
+     * Defines the type of the record.
+     * For example User, Post, Comment etc.
+     *
+     * This helps to ensure isolation of models when using a single table design
+     * @returns The type of the record as a string.
      */
     protected abstract getType(): string;
+    /**
+     * Used to define the attribute name for the type.
+     * @returns The type attribute name as a string.
+     */
     protected abstract getTypeAttributeName(): string;
-    protected beforeInsert(data: InferZodSchema<TSchema>): InferZodSchema<TSchema>;
-    protected beforeUpdate(data: InferZodSchema<TSchema>): InferZodSchema<TSchema>;
-    create(data: InferZodSchema<TSchema>): Promise<InferZodSchema<TSchema>>;
-    update(key: PrimaryKeyWithoutExpression, updates: Partial<InferZodSchema<TSchema>>): Promise<InferZodSchema<TSchema>>;
-    delete(key: PrimaryKeyWithoutExpression): Promise<void>;
-    findOne(key: PrimaryKeyWithoutExpression): Promise<InferZodSchema<TSchema> | null>;
-    findOrFail(key: PrimaryKeyWithoutExpression): Promise<InferZodSchema<TSchema>>;
-    protected query(key: PrimaryKeyWithoutExpression): QueryBuilder;
+    /**
+     * Hook method called before inserting a record.
+     * Subclasses can override this method to modify the data before insertion.
+     * @param data - The record data.
+     * @returns The modified record data.
+     */
+    protected beforeInsert(data: TData): TData;
+    /**
+     * Hook method called before updating a record.
+     * Subclasses can override this method to modify the data before updating.
+     * @param data - The partial record data to be updated.
+     * @returns The modified partial record data.
+     */
+    protected beforeUpdate(data: Partial<TData>): Partial<TData>;
+    /**
+     * Checks if a record exists in the table.
+     * @param key - The primary key of the record.
+     * @returns A promise that resolves to true if the record exists, false otherwise.
+     */
+    exists(key: PrimaryKeyWithoutExpression): Promise<boolean>;
+    /**
+     * Type guard to check if the value is a primary key.
+     * @param value - The value to check.
+     * @returns True if the value is a primary key, false otherwise.
+     */
+    protected isPrimaryKey(value: PrimaryKeyWithoutExpression | TData): value is PrimaryKeyWithoutExpression;
+    /**
+     * Creates a new record in the table.
+     * @param data - The record data.
+     * @returns A PutBuilder instance to execute the put operation.
+     */
+    create(data: TData): PutBuilder<TData>;
+    /**
+     * Updates an existing record in the table.
+     * @param key - The primary key of the record.
+     * @param updates - The partial record data to be updated.
+     * @returns A promise that resolves to the updated record or null if the record does not exist.
+     */
+    update(key: PrimaryKeyWithoutExpression, updates: Partial<TData>): Promise<TData | null>;
+    /**
+     * Upserts (inserts or updates) a record in the table.
+     * @param data - The record data.
+     * @returns A PutBuilder instance to execute the put operation.
+     */
+    upsert(data: TData): PutBuilder<TData>;
+    /**
+     * Deletes a record from the table.
+     * @param keyOrDTO - The primary key or the record data.
+     * @returns A promise that resolves when the record is deleted.
+     */
+    delete(keyOrDTO: PrimaryKeyWithoutExpression | TData): Promise<void>;
+    /**
+     * Finds a single record by its primary key.
+     * @param key - The primary key of the record.
+     * @returns A promise that resolves to the record or null if the record does not exist.
+     */
+    findOne(key: PrimaryKey): Promise<TData | null>;
+    /**
+     * Finds a single record by its primary key or throws an error if the record does not exist.
+     * @param key - The primary key of the record.
+     * @returns A promise that resolves to the record.
+     * @throws An error if the record does not exist.
+     */
+    findOrFail(key: PrimaryKeyWithoutExpression): Promise<TData>;
+    /**
+     * Creates a query builder for querying records by their primary key.
+     * @param key - The primary key of the record.
+     * @returns A QueryBuilder instance to build and execute the query.
+     */
+    query(key: PrimaryKey): QueryBuilder<TData>;
 }
 
 interface RetryStrategy {