@lafken/dynamo 0.10.1

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aníbal Emilio Jorquera Cornejo
+
+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,503 @@
+# @lafken/dynamo
+
+Define and manage DynamoDB tables using TypeScript decorators. `@lafken/dynamo` lets you declare table schemas, indexes, streams, and TTL directly in your classes — and provides a type-safe repository for performing operations at runtime.
+
+## Installation
+
+```bash
+npm install @lafken/dynamo
+```
+
+## Getting Started
+
+Define a table class with `@Table`, register it in the `DynamoResolver`, and use `createRepository` to interact with it:
+
+```typescript
+import { createApp } from '@lafken/main';
+import { DynamoResolver } from '@lafken/dynamo/resolver';
+import { Table, PartitionKey, SortKey, Field, type PrimaryPartition } from '@lafken/dynamo/main';
+import { createRepository } from '@lafken/dynamo/service';
+
+// 1. Define the table schema
+@Table({ name: 'contacts' })
+export class Contact {
+  @PartitionKey(String)
+  email: PrimaryPartition<string>;
+
+  @SortKey(String)
+  company: PrimaryPartition<string>;
+
+  @Field()
+  name: string;
+
+  @Field()
+  age: number;
+}
+
+// 2. Create a repository for runtime operations
+export const contactRepository = createRepository(Contact);
+
+// 3. Register the table in the resolver
+createApp({
+  name: 'my-app',
+  resolvers: [
+    new DynamoResolver([Contact]),
+  ],
+});
+```
+
+## Features
+
+### Defining a Table
+
+Use the `@Table` decorator on a class to declare a DynamoDB table. Each property decorated with `@PartitionKey`, `@SortKey`, or `@Field` becomes an attribute in the table schema.
+
+Every table requires exactly one `@PartitionKey`. A `@SortKey` is optional and creates a composite primary key. Both accept `String` or `Number` as the key type.
+
+```typescript
+import { Table, PartitionKey, SortKey, Field, type PrimaryPartition } from '@lafken/dynamo/main';
+
+@Table({ name: 'events' })
+export class EventLog {
+  @PartitionKey(String)
+  source: PrimaryPartition<string>;
+
+  @SortKey(Number)
+  timestamp: PrimaryPartition<number>;
+
+  @Field()
+  payload: string;
+
+  @Field({ type: Number })
+  severity: number;
+}
+```
+
+The `@Field` decorator registers a regular attribute. Its type is inferred automatically, but can be overridden with the `type` option.
+
+### Indexes
+
+Secondary indexes enable alternative query patterns. Define them in the `indexes` option of `@Table`.
+
+#### Local Secondary Index
+
+Shares the same partition key as the table but uses a different sort key:
+
+```typescript
+@Table({
+  name: 'orders',
+  indexes: [
+    {
+      type: 'local',
+      name: 'orders_by_total',
+      sortKey: 'total',
+    },
+  ],
+})
+export class Order {
+  @PartitionKey(String)
+  customerId: PrimaryPartition<string>;
+
+  @SortKey(String)
+  orderId: PrimaryPartition<string>;
+
+  @Field()
+  total: number;
+
+  @Field()
+  status: string;
+}
+```
+
+#### Global Secondary Index
+
+Has its own partition key and optional sort key, enabling queries across the entire table:
+
+```typescript
+@Table({
+  name: 'orders',
+  indexes: [
+    {
+      type: 'global',
+      name: 'orders_by_status',
+      partitionKey: 'status',
+      sortKey: 'total',
+      projection: ['customerId', 'orderId'],
+    },
+  ],
+})
+export class Order {
+  @PartitionKey(String)
+  customerId: PrimaryPartition<string>;
+
+  @SortKey(String)
+  orderId: PrimaryPartition<string>;
+
+  @Field()
+  total: number;
+
+  @Field()
+  status: string;
+}
+```
+
+Use `projection` to control which attributes are included in the index. Pass an array of field names or `'ALL'` to project every attribute.
+
+### TTL (Time to Live)
+
+Enable automatic item expiration by specifying the `ttl` option with the name of a numeric field. DynamoDB will delete items whose TTL value (Unix timestamp in seconds) has passed:
+
+```typescript
+@Table({
+  name: 'sessions',
+  ttl: 'expiresAt',
+})
+export class Session {
+  @PartitionKey(String)
+  sessionId: PrimaryPartition<string>;
+
+  @Field()
+  userId: string;
+
+  @Field()
+  expiresAt: number;
+}
+```
+
+### Streams
+
+Enable a DynamoDB Stream to capture item-level changes. When enabled, the stream is automatically connected to EventBridge via EventBridge Pipes, allowing other services to react to table changes in near real-time.
+
+Use the `@lafken/event` package to consume and process these stream events.
+
+```typescript
+@Table({
+  name: 'notifications',
+  stream: {
+    enabled: true,
+    type: 'NEW_AND_OLD_IMAGES',
+    batchSize: 10,
+    maximumBatchingWindowInSeconds: 5,
+  },
+})
+export class Notification {
+  @PartitionKey(String)
+  id: PrimaryPartition<string>;
+
+  @Field()
+  channel: string;
+
+  @Field()
+  message: string;
+}
+```
+
+#### Stream Filters
+
+Apply filters to process only specific change events, reducing unnecessary invocations:
+
+```typescript
+@Table({
+  name: 'notifications',
+  stream: {
+    enabled: true,
+    type: 'NEW_IMAGE',
+    filters: {
+      eventName: ['INSERT'],
+      newImage: {
+        channel: ['email', 'sms'],
+      },
+    },
+  },
+})
+export class Notification {
+  @PartitionKey(String)
+  id: PrimaryPartition<string>;
+
+  @Field()
+  channel: string;
+
+  @Field()
+  message: string;
+}
+```
+
+Available filter criteria:
+
+| Filter      | Description                                            |
+| ----------- | ------------------------------------------------------ |
+| `eventName` | Event types: `'INSERT'`, `'MODIFY'`, `'REMOVE'`       |
+| `keys`      | Filter by partition/sort key values                    |
+| `newImage`  | Conditions on the new item (after INSERT or MODIFY)    |
+| `oldImage`  | Conditions on the old item (before MODIFY or REMOVE)   |
+
+### Billing Mode
+
+Tables default to `pay_per_request` (on-demand). For provisioned throughput, set `billingMode` and specify capacity units:
+
+```typescript
+@Table({
+  name: 'high-throughput',
+  billingMode: 'provisioned',
+  readCapacity: 100,
+  writeCapacity: 50,
+})
+export class HighThroughputTable {
+  @PartitionKey(String)
+  id: PrimaryPartition<string>;
+
+  @Field()
+  data: string;
+}
+```
+
+### Global Tables (Replicas)
+
+Create multi-region replicas for global applications using the `replica` option:
+
+```typescript
+@Table({
+  name: 'global-config',
+  replica: [
+    { regionName: 'eu-west-1', consistenceMode: 'EVENTUAL' },
+    { regionName: 'ap-southeast-1' },
+  ],
+})
+export class GlobalConfig {
+  @PartitionKey(String)
+  key: PrimaryPartition<string>;
+
+  @Field()
+  value: string;
+}
+```
+
+### Repository
+
+`createRepository` provides a type-safe API for DynamoDB operations at runtime. All methods return a builder that is executed by calling `.exec()`.
+
+```typescript
+import { createRepository } from '@lafken/dynamo/service';
+
+export const contactRepository = createRepository(Contact);
+```
+
+#### Create
+
+Insert a new item into the table:
+
+```typescript
+await contactRepository
+  .create({
+    email: 'jane@example.com',
+    company: 'Acme',
+    name: 'Jane Doe',
+    age: 30,
+  })
+  .exec();
+```
+
+#### Find All
+
+Query items using a key condition. Supports filtering, projections, pagination, and sort direction:
+
+```typescript
+const result = await contactRepository
+  .findAll({
+    keyCondition: {
+      partition: { email: 'jane@example.com' },
+    },
+    filter: {
+      age: { greaterThan: 25 },
+    },
+    projection: ['name', 'company'],
+    sortDirection: 'desc',
+    limit: 10,
+  })
+  .exec();
+
+// result.data    → matched items
+// result.cursor  → pagination cursor for the next page
+```
+
+#### Find One
+
+Retrieve a single item matching a key condition:
+
+```typescript
+const item = await contactRepository
+  .findOne({
+    keyCondition: {
+      partition: { email: 'jane@example.com' },
+      sort: { company: 'Acme' },
+    },
+  })
+  .exec();
+```
+
+#### Scan
+
+Scan the entire table with optional filters:
+
+```typescript
+const all = await contactRepository
+  .scan({
+    filter: {
+      age: { greaterThan: 18 },
+    },
+    limit: 50,
+  })
+  .exec();
+```
+
+#### Update
+
+Update specific attributes of an existing item:
+
+```typescript
+await contactRepository
+  .update({
+    keyCondition: {
+      email: 'jane@example.com',
+      company: 'Acme',
+    },
+    setValues: {
+      age: 31,
+    },
+    replaceValues: {
+      name: 'Jane Smith',
+    },
+  })
+  .exec();
+```
+
+Update supports three operation types:
+
+| Operation       | Description                                                      |
+| --------------- | ---------------------------------------------------------------- |
+| `setValues`     | Update specific nested fields without overwriting the object     |
+| `replaceValues` | Replace entire attribute values                                  |
+| `removeValues`  | Remove attributes from the item                                  |
+
+Numeric fields support `incrementValue` and `decrementValue`, and any field supports `ifNotExistValue` for conditional defaults:
+
+```typescript
+await contactRepository
+  .update({
+    keyCondition: { email: 'jane@example.com', company: 'Acme' },
+    setValues: {
+      age: { incrementValue: 1 },
+    },
+  })
+  .exec();
+```
+
+#### Upsert
+
+Insert an item or update it if it already exists:
+
+```typescript
+await contactRepository
+  .upsert({
+    email: 'jane@example.com',
+    company: 'Acme',
+    name: 'Jane Doe',
+    age: 30,
+  })
+  .exec();
+```
+
+#### Delete
+
+Remove an item by its primary key:
+
+```typescript
+await contactRepository
+  .delete({
+    email: 'jane@example.com',
+    company: 'Acme',
+  })
+  .exec();
+```
+
+#### Bulk Operations
+
+Create or delete multiple items at once:
+
+```typescript
+// Bulk create
+await contactRepository
+  .bulkCreate([
+    { email: 'a@example.com', company: 'X', name: 'Alice', age: 28 },
+    { email: 'b@example.com', company: 'Y', name: 'Bob', age: 35 },
+  ])
+  .exec();
+
+// Bulk delete
+await contactRepository
+  .bulkDelete([
+    { email: 'a@example.com', company: 'X' },
+    { email: 'b@example.com', company: 'Y' },
+  ])
+  .exec();
+```
+
+#### Querying an Index
+
+Specify `indexName` in your query to use a secondary index:
+
+```typescript
+const result = await orderRepository
+  .findAll({
+    keyCondition: {
+      partition: { status: 'pending' },
+    },
+    indexName: 'orders_by_status',
+  })
+  .exec();
+```
+
+If `indexName` is omitted, the repository automatically selects the best matching index based on the key condition attributes.
+
+### Transactions
+
+Group multiple write operations (create, update, upsert, delete) into an atomic transaction. All operations succeed or fail together:
+
+```typescript
+import { transaction } from '@lafken/dynamo/service';
+
+await transaction([
+  contactRepository.create({
+    email: 'new@example.com',
+    company: 'Acme',
+    name: 'New Contact',
+    age: 25,
+  }),
+  orderRepository.update({
+    keyCondition: { customerId: 'cust-1', orderId: 'ord-1' },
+    setValues: { status: 'confirmed' },
+  }),
+  contactRepository.delete({
+    email: 'old@example.com',
+    company: 'Acme',
+  }),
+]);
+```
+
+> [!NOTE]
+> Transaction builders are passed without calling `.exec()` — the `transaction` function handles execution internally.
+
+### Extending the Table
+
+The `DynamoResolver` supports an `extends` function for applying advanced CDKTN configuration to the generated table resource:
+
+```typescript
+new DynamoResolver([
+  {
+    table: Contact,
+    extends: ({ table, scope }) => {
+      // Add alarms, policies, or any CDKTN construct
+    },
+  },
+]);
+```

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export * from './main';
+export * from './resolver';
+export * from './service';

package/lib/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./main"), exports);
+__exportStar(require("./resolver"), exports);
+__exportStar(require("./service"), exports);

package/lib/main/index.d.ts

@@ -0,0 +1 @@
+export * from './table';

package/lib/main/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./table"), exports);

package/lib/main/table/index.d.ts

@@ -0,0 +1,2 @@
+export * from './table';
+export * from './table.types';

package/lib/main/table/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./table"), exports);
+__exportStar(require("./table.types"), exports);

package/lib/main/table/table.d.ts

@@ -0,0 +1,107 @@
+import { type DynamoTableProps, type FieldProps } from './table.types';
+/**
+ * Class decorator that registers a class as a DynamoDB table resource.
+ *
+ * The decorated class represents a DynamoDB table and its schema.
+ * Use `@PartitionKey`, `@SortKey`, and `@Field` on the class
+ * properties to define the table structure. Options such as billing
+ * mode, indexes, streams, TTL, and replicas can be set through the
+ * decorator props.
+ *
+ * @typeParam T - The class being decorated.
+ * @param props - Optional table configuration. If omitted, the class
+ *                name is used as the table name with pay-per-request billing.
+ *
+ * @example
+ * ```ts
+ * @Table({ stream: { enabled: true, type: 'NEW_AND_OLD_IMAGES' } })
+ * export class UserTable {
+ *   @PartitionKey(String)
+ *   id: PrimaryPartition<string>;
+ *
+ *   @SortKey(Number)
+ *   createdAt: PrimaryPartition<string>;
+ *
+ *   @Field()
+ *   email: string;
+ * }
+ * ```
+ */
+export declare const Table: <T extends Function>(props?: DynamoTableProps<T>) => (constructor: T) => void;
+/**
+ * Property decorator that registers a class field as a DynamoDB
+ * table attribute.
+ *
+ * The attribute type is inferred from the property's TypeScript type
+ * by default, but can be overridden via the `type` option. Use this
+ * decorator for regular attributes that are neither the partition key
+ * nor the sort key.
+ *
+ * @param props - Optional field configuration.
+ * @param props.type - Explicit type override (`String`, `Number`, `Boolean`,
+ *                     a class, or an array wrapper).
+ *
+ * @example
+ * ```ts
+ * @Table()
+ * export class OrderTable {
+ *   @PartitionKey(String)
+ *   id: string;
+ *
+ *   @Field()
+ *   status: string;
+ *
+ *   @Field({ type: Number })
+ *   total: number;
+ * }
+ * ```
+ */
+export declare const Field: (props?: FieldProps) => (constructor: any, name: string) => void;
+/**
+ * Property decorator that marks a field as the DynamoDB table
+ * **partition key** (hash key).
+ *
+ * Every DynamoDB table requires exactly one partition key. The
+ * accepted types are `String` or `Number`.
+ *
+ * Internally registers the field as a regular `@Field` as well,
+ * so there is no need to apply both decorators.
+ *
+ * @param type - The key type (`String` or `Number`).
+ *
+ * @example
+ * ```ts
+ * @Table()
+ * export class UserTable {
+ *   @PartitionKey(String)
+ *   id: string;
+ * }
+ * ```
+ */
+export declare const PartitionKey: (type: StringConstructor | NumberConstructor) => (constructor: any, name: string) => void;
+/**
+ * Property decorator that marks a field as the DynamoDB table
+ * **sort key** (range key).
+ *
+ * A sort key is optional but, when present, works together with
+ * the partition key to form a composite primary key. The accepted
+ * types are `String` or `Number`.
+ *
+ * Internally registers the field as a regular `@Field` as well,
+ * so there is no need to apply both decorators.
+ *
+ * @param type - The key type (`String` or `Number`).
+ *
+ * @example
+ * ```ts
+ * @Table()
+ * export class EventTable {
+ *   @PartitionKey(String)
+ *   userId: string;
+ *
+ *   @SortKey(Number)
+ *   timestamp: number;
+ * }
+ * ```
+ */
+export declare const SortKey: (type: StringConstructor | NumberConstructor) => (constructor: any, name: string) => void;