dynoquery 0.1.11 → 0.1.14

package/README.md

@@ -11,119 +11,172 @@ npm install dynoquery
 ## Features
 
 - Basic CRUD operations (create, get, update, delete)
-- Optimized for **Single-Table Design**
-- Query and Scan support
+- Optimized for **Single-Table Design** (Partitions and GSIs)
+- Automatic result mapping to models
+- Built-in caching for partition instances
 - TypeScript support
 
-## Usage
+## Quick Start (Basic Usage)
+
+First, initialize the client with your table name.
 
 ```typescript
 import { DynoQuery } from 'dynoquery';
 
 const db = new DynoQuery({
   region: 'us-east-1',
-  tableName: 'MyTable', // Define default table for single-table structure
-  pkName: 'PK', // Optional: Custom attribute name for Partition Key (default: 'PK')
-  skName: 'SK', // Optional: Custom attribute name for Sort Key (default: 'SK')
-  pkPrefix: 'TENANT#A#', // Optional: Global prefix for all partitions (useful for multitenancy)
-  // optional endpoint for local development
-  // endpoint: 'http://localhost:8000'
+  tableName: 'MyTable'
+});
+```
+
+### 1. Working with Partitions (Models)
+
+Define your models to handle different types of data within your single table.
+
+```typescript
+const db = new DynoQuery({
+  region: 'us-east-1',
+  tableName: 'MyTable',
   models: {
-    User: { pkPrefix: 'USER#' }, // TENANT#A#USER#
+    User: { pkPrefix: 'USER#' }, // Resulting PK: USER#<id>
+    Product: { pkPrefix: 'PROD#' }
+  }
+});
+
+async function userExample() {
+  const john = db.User('john@example.com');
+  
+  // Create an item (SK: PROFILE)
+  await john.create('PROFILE', { name: 'John Doe', email: 'john@example.com' });
+  
+  // Get an item (uses cache if already loaded)
+  const profile = await john.get('PROFILE');
+  console.log(profile.name); // 'John Doe'
+
+  // Update an item (partial update)
+  await john.update('PROFILE', { theme: 'dark' });
+
+  // Delete an item
+  await john.delete('PROFILE');
+  
+  // Fetch all items in this partition
+  const allData = await john.getAll();
+}
+```
+
+### 2. Global Secondary Indexes (findBy)
+
+Use `findBy` to query your GSIs easily.
+
+```typescript
+const db = new DynoQuery({
+  region: 'us-east-1',
+  tableName: 'MyTable',
+  models: {
+    Product: { pkPrefix: 'PROD#' }
   },
   findBy: {
-    //  TENANT#A#CAT#
     Category: { indexName: 'GSI1', pkPrefix: 'CAT#' }, // pkName defaults to GSI1PK, skName defaults to GSI1SK
-    Date: { indexName: 'GSI2', pkPrefix: 'DATE#' }
   }
 });
 
-async function example() {
-  // Use registered partition
-  // Resulting PK: TENANT#A#USER#john@example.com
-  const john = db.User('john@example.com');
+async function indexExample() {
+  // Query by Category PK: CAT#ELECTRONICS
+  const electronics = db.findByCategory('ELECTRONICS');
   
-  // Use registered index
-  // Resulting GSI1PK: TENANT#A#CAT#1
-  const categories = db.findByCategory('1');
-  const items = await categories.get('100');
-  const allItems = await categories.getAll();
+  // Get all items in this category
+  const items = await electronics.getAll();
   
-  // Index results are automatically mapped to models based on PK prefix
+  // If results match a registered model prefix, they are automatically mapped
   items.forEach(item => {
-    if (item.__model === 'User') {
-      console.log('Found user:', item.name);
-      // You can also get a Partition instance for this item
-      const userPartition = item.getPartition();
+    if (item.__model === 'Product') {
+      const productPartition = item.getPartition(); // Returns a Partition instance
     }
   });
-  
-  // Load all data for this partition (optional, but good for multiple reads)
-  const allJohnData = await john.getAll();
-  
-  // john.get() loads data immediately (using cache if loaded)
-  const userMetadata = await john.get('METADATA');
-  console.log(userMetadata);
+}
+```
 
-  // Create an item through partition
-  await john.create('PROFILE', { name: 'John Doe', email: 'john@example.com' });
-  
-  // Resulting GSI1PK: TENANT#A#CAT#USER
-  const cat = db.findByCategory('USER', '1');
-  const date = db.findByDate('2026-10-11', '2');
-  console.log(cat.getSkValue()); // '1'
-  await john.create('PROFILE', { 
-    name: 'John Doe', 
-    email: 'john@example.com', 
-  }, [cat, date]);
-
-  // Update the item (updates both DB and partition cache)
-  await john.update('PROFILE', { theme: 'dark' });
+### 3. Creating Items with GSI Support
 
-  // Delete an item
-  await john.delete('METADATA');
+You can pass index queries directly to `create()` to automatically populate GSI attributes.
 
-  // Advanced Partition usage (Subclassing)
-  class UserPartition extends Partition {
-    constructor(db: DynoQuery, email: string) {
-      super(db, { pkPrefix: 'USER#' }, email);
-    }
+```typescript
+const electronics = db.findByCategory('ELECTRONICS', 'RANK#1');
+
+// This will automatically set GSI1PK='CAT#ELECTRONICS' and GSI1SK='RANK#1'
+await db.Product('p123').create('INFO', { 
+  name: 'Gaming Mouse',
+  price: 50
+}, [electronics]);
+```
+
+## Optional Configuration Parameters
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `pkName` | `string` | `'PK'` | Custom attribute name for Partition Key. |
+| `skName` | `string` | `'SK'` | Custom attribute name for Sort Key. |
+| `pkPrefix` | `string` | `''` | Global prefix for all partitions (useful for multitenancy, e.g., `TENANT#A#`). |
+| `endpoint` | `string` | - | Optional endpoint for local development (e.g., `http://localhost:8000`). |
+| `credentials` | `object` | - | Custom AWS credentials (`{ accessKeyId, secretAccessKey, sessionToken? }`). |
+
+### Example with Optional Parameters
+
+```typescript
+const db = new DynoQuery({
+  region: 'us-east-1',
+  tableName: 'MyTable',
+  pkName: 'PartitionKey', // Custom PK name
+  skName: 'SortKey',      // Custom SK name
+  pkPrefix: 'TENANT#A#',   // Global prefix for multitenancy
+  endpoint: 'http://localhost:8000', // For local DynamoDB
+  credentials: {
+    accessKeyId: 'MY_ACCESS_KEY',
+    secretAccessKey: 'MY_SECRET_KEY'
   }
+});
+```
+
+## Advanced Usage
+
+### Pagination
+
+Both `Partition.getAll()` and `IndexQuery.getAll()` support pagination.
+
+```typescript
+const index = db.findByCategory('ELECTRONICS');
+const items = await index.getAll({ limit: 10 });
 
-  const user2 = new UserPartition(db, 'jane@example.com');
-  const data2 = await user2.get('METADATA');
-  console.log(data2);
+const token = index.getLastEvaluatedKey();
+if (token) {
+  // Fetch next page
+  const nextItems = await index.getAll({ limit: 10, exclusiveStartKey: token });
 }
 ```
 
 ## API Reference
 
 ### DynoQuery
-The main client for interacting with DynamoDB.
-- `create(params)`: Put an item.
-- `get(params)`: Get an item.
-- `update(params)`: Update an item.
-- `delete(params)`: Delete an item.
-- `query(params)`: Query items.
-- `scan(params)`: Scan items.
+- `create(params)`: Low-level PutCommand wrapper.
+- `get(params)`: Low-level GetCommand wrapper.
+- `update(params)`: Low-level UpdateCommand wrapper.
+- `delete(params)`: Low-level DeleteCommand wrapper.
+- `query(params)`: Low-level QueryCommand wrapper.
+- `scan(params)`: Low-level ScanCommand wrapper.
 
 ### Partition
-A way to manage data within a specific partition.
-- `getPkValue()`: Returns the generated partition key value.
-- `get(sk)`: Fetches data for a specific sort key (returns a Promise).
-- `getAll()`: Fetches all items in the partition and caches them. Returns the items.
-- `create(sk, data, indices?)`: Creates an item in the partition. If `indices` (array of `IndexQuery`) are provided, it automatically adds the index PK and SK to the item.
-- `update(sk, data)`: Updates an existing item (partial update).
+- `get(sk)`: Fetches data for a specific SK (returns a Promise).
+- `getAll(options?)`: Fetches items in the partition. Options: `{ limit, exclusiveStartKey }`.
+- `create(sk, data, indices?)`: Creates an item. `indices` is an array of `IndexQuery` for GSI population.
+- `update(sk, data)`: Partial update of an item.
 - `delete(sk)`: Deletes an item.
 - `deleteAll()`: Deletes all items in the partition.
+- `getLastEvaluatedKey()`: Returns the pagination token from the last `getAll()`.
 
 ### IndexQuery
-A way to query Global Secondary Indexes.
-- `getPkValue()`: Returns the generated partition key value for this index.
-- `getSkValue()`: Returns the sort key value if it was provided when calling the index query method.
-- `get(skValue | options)`: Query items in the index. Supports `skValue` (string) for `begins_with` search, or an options object with `skValue`, `limit`, and `scanIndexForward`. If `skValue` was provided when the `IndexQuery` was created, it will be used as the default if no `skValue` is passed here.
-- `getAll()`: Fetches all items in the index for the given partition key. If `skValue` was provided when the `IndexQuery` was created, it will filter by it using `begins_with`.
-- Automatically identifies the model name in results using `__model` (based on registered models) and provides `getPartition()` helper.
+- `get(skValue?)`: Get a single item from the index.
+- `getAll(options?)`: Query index. Options: `{ limit, scanIndexForward, exclusiveStartKey, skValue }`.
+- `getLastEvaluatedKey()`: Returns the pagination token from the last `getAll()`.
 
 ## License
 

package/dist/index-query.d.ts

@@ -16,16 +16,22 @@ export declare class IndexQuery {
     protected skName: string;
     protected pkValue: string;
     protected skValue?: string;
+    protected lastEvaluatedKey: any;
     constructor(db: DynoQuery, config: IndexQueryConfig);
-    get<T = any>(skValueOrOptions?: string | {
-        skValue?: string;
+    getAll<T = any>(options?: {
         limit?: number;
         scanIndexForward?: boolean;
+        exclusiveStartKey?: any;
+        skValue?: string;
+        filterExpression?: string;
+        expressionAttributeNames?: Record<string, string>;
+        expressionAttributeValues?: Record<string, any>;
     }): Promise<T[]>;
-    getAll<T = any>(): Promise<T[]>;
+    get<T = any>(skValue?: string): Promise<T | null>;
     getPkValue(): string;
     getPkName(): string;
     getSkName(): string;
     getSkValue(): string | undefined;
+    getLastEvaluatedKey(): any;
     private mapItemToModel;
 }

package/dist/index-query.js

@@ -13,6 +13,7 @@ exports.IndexQuery = void 0;
 const partition_1 = require("./partition");
 class IndexQuery {
     constructor(db, config) {
+        this.lastEvaluatedKey = null;
         this.db = db;
         this.tableName = config.tableName || db.getTableName() || "";
         this.indexName = config.indexName;
@@ -30,46 +31,38 @@ class IndexQuery {
             throw new Error("TableName must be provided in IndexQueryConfig or DynoQueryConfig");
         }
     }
-    get(skValueOrOptions) {
+    getAll(options) {
         return __awaiter(this, void 0, void 0, function* () {
-            let options = {};
-            if (typeof skValueOrOptions === 'string') {
-                options.skValue = skValueOrOptions;
-            }
-            else if (typeof skValueOrOptions === 'object') {
-                options = skValueOrOptions;
-            }
-            else if (this.skValue) {
-                options.skValue = this.skValue;
-            }
+            const finalSkValue = (options === null || options === void 0 ? void 0 : options.skValue) || this.skValue;
             let keyCondition = "#pk = :pk";
-            const expressionAttributeNames = {
-                "#pk": this.pkName,
-            };
-            const expressionAttributeValues = {
-                ":pk": this.pkValue,
-            };
-            if (options.skValue) {
+            const expressionAttributeNames = Object.assign({ "#pk": this.pkName }, options === null || options === void 0 ? void 0 : options.expressionAttributeNames);
+            const expressionAttributeValues = Object.assign({ ":pk": this.pkValue }, options === null || options === void 0 ? void 0 : options.expressionAttributeValues);
+            if (finalSkValue) {
                 keyCondition += " AND begins_with(#sk, :sk)";
                 expressionAttributeNames["#sk"] = this.skName;
-                expressionAttributeValues[":sk"] = options.skValue;
+                expressionAttributeValues[":sk"] = finalSkValue;
             }
             const response = yield this.db.query({
                 TableName: this.tableName,
                 IndexName: this.indexName,
                 KeyConditionExpression: keyCondition,
+                FilterExpression: options === null || options === void 0 ? void 0 : options.filterExpression,
                 ExpressionAttributeNames: expressionAttributeNames,
                 ExpressionAttributeValues: expressionAttributeValues,
-                Limit: options.limit,
-                ScanIndexForward: options.scanIndexForward,
+                Limit: options === null || options === void 0 ? void 0 : options.limit,
+                ScanIndexForward: options === null || options === void 0 ? void 0 : options.scanIndexForward,
+                ExclusiveStartKey: options === null || options === void 0 ? void 0 : options.exclusiveStartKey,
             });
             const items = (response.Items || []);
-            return items.map(item => this.mapItemToModel(item));
+            const mappedItems = items.map(item => this.mapItemToModel(item));
+            this.lastEvaluatedKey = response.LastEvaluatedKey || null;
+            return mappedItems;
         });
     }
-    getAll() {
+    get(skValue) {
         return __awaiter(this, void 0, void 0, function* () {
-            return this.get();
+            const items = yield this.getAll({ limit: 1, skValue });
+            return items.length > 0 ? items[0] : null;
         });
     }
     getPkValue() {
@@ -84,6 +77,9 @@ class IndexQuery {
     getSkValue() {
         return this.skValue;
     }
+    getLastEvaluatedKey() {
+        return this.lastEvaluatedKey;
+    }
     mapItemToModel(item) {
         const pkName = this.db.getPkName();
         const pkValue = item[pkName];

package/dist/partition.d.ts

@@ -13,12 +13,19 @@ export declare class Partition {
     protected skName: string;
     protected cache: Record<string, any>;
     protected isLoaded: boolean;
+    protected lastEvaluatedKey: any;
     constructor(db: DynoQuery, config: PartitionConfig, id?: string);
     /**
      * Fetches all items in the partition and caches them.
      * Returns the data and caches it.
      */
-    getAll<T = any>(): Promise<T[]>;
+    getAll<T = any>(options?: {
+        limit?: number;
+        exclusiveStartKey?: any;
+        filterExpression?: string;
+        expressionAttributeNames?: Record<string, string>;
+        expressionAttributeValues?: Record<string, any>;
+    }): Promise<T[]>;
     /**
      * Create an item in this partition.
      */
@@ -38,6 +45,7 @@ export declare class Partition {
      */
     get<T = any>(sk: string): Promise<T | null>;
     getPkValue(): string;
+    getLastEvaluatedKey(): any;
     /**
      * Delete all data in this partition.
      */

package/dist/partition.js

@@ -14,6 +14,7 @@ class Partition {
     constructor(db, config, id) {
         this.cache = {};
         this.isLoaded = false;
+        this.lastEvaluatedKey = null;
         this.db = db;
         this.tableName = config.tableName || db.getTableName();
         this.pkName = db.getPkName();
@@ -54,17 +55,16 @@ class Partition {
      * Fetches all items in the partition and caches them.
      * Returns the data and caches it.
      */
-    getAll() {
+    getAll(options) {
         return __awaiter(this, void 0, void 0, function* () {
             const response = yield this.db.query({
                 TableName: this.tableName,
                 KeyConditionExpression: "#pk = :pk",
-                ExpressionAttributeNames: {
-                    "#pk": this.pkName,
-                },
-                ExpressionAttributeValues: {
-                    ":pk": this.pkValue,
-                },
+                FilterExpression: options === null || options === void 0 ? void 0 : options.filterExpression,
+                ExpressionAttributeNames: Object.assign({ "#pk": this.pkName }, options === null || options === void 0 ? void 0 : options.expressionAttributeNames),
+                ExpressionAttributeValues: Object.assign({ ":pk": this.pkValue }, options === null || options === void 0 ? void 0 : options.expressionAttributeValues),
+                Limit: options === null || options === void 0 ? void 0 : options.limit,
+                ExclusiveStartKey: options === null || options === void 0 ? void 0 : options.exclusiveStartKey,
             });
             const items = (response.Items || []);
             items.forEach((item) => {
@@ -72,7 +72,10 @@ class Partition {
                     this.cache[item[this.skName]] = item;
                 }
             });
-            this.isLoaded = true;
+            if (!(options === null || options === void 0 ? void 0 : options.exclusiveStartKey) && !response.LastEvaluatedKey) {
+                this.isLoaded = true;
+            }
+            this.lastEvaluatedKey = response.LastEvaluatedKey || null;
             return items;
         });
     }
@@ -152,6 +155,9 @@ class Partition {
     getPkValue() {
         return this.pkValue;
     }
+    getLastEvaluatedKey() {
+        return this.lastEvaluatedKey;
+    }
     /**
      * Delete all data in this partition.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dynoquery",
-  "version": "0.1.11",
+  "version": "0.1.14",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/devspikejs/dynoquery.git"