dynoquery 0.1.15 → 0.1.17

package/README.md

@@ -12,7 +12,7 @@ npm install dynoquery
 
 - Basic CRUD operations (create, get, update, delete)
 - Optimized for **Single-Table Design** (Partitions and GSIs)
-- Automatic result mapping to models
+- Automatic result mapping to partition models
 - Built-in caching for partition instances
 - TypeScript support
 
@@ -64,6 +64,41 @@ async function userExample() {
 }
 ```
 
+#### Second-Level Objects (Single-Row Operations)
+
+For a more flexible way to work with individual rows, you can use `draft()` and `get()` to obtain an `Item` object, then call `create()`, `update()`, or `save()` on it directly. You can also use a shorthand by passing a second argument to your model function (as shown in the examples below).
+
+```typescript
+const john = db.User('john@example.com');
+
+// 1. Create a new row
+const johnMeta = john.draft('METADATA');
+johnMeta.name = 'John Doe';
+johnMeta.email = 'johndoe@johnmail.com';
+await johnMeta.save();
+
+// 2. Create with properties in arguments
+const johnStat = john.draft('STAT');
+await johnStat.create({ views: 100 });
+
+// 3. Get and update an existing row
+const johnBio = await john.get('BIO');
+johnBio.birthYear = 1986;
+await johnBio.save();
+
+// 4. Partial update without fetching
+const johnFriend1 = john.draft('FRIEND#1');
+await johnFriend1.update({ Name: 'Alice', rank: 1 });
+
+// 5. Set properties during initialization
+const johnPref = john.draft('PREF', { theme: 'dark' });
+await johnPref.save();
+
+// 6. Shorthand access (returns an Item object directly)
+const johnMeta = db.User('john@example.com', 'METADATA');
+await johnMeta.update({ name: 'John Doe' });
+```
+
 ### 2. Global Secondary Indexes (findBy)
 
 Use `findBy` to query your GSIs easily.
@@ -87,10 +122,14 @@ async function indexExample() {
   // Get all items in this category
   const items = await electronics.getAll();
   
-  // If results match a registered model prefix, they are automatically mapped
-  items.forEach(item => {
+  // If results match a registered item prefix, they are automatically mapped
+  items.forEach(async item => {
     if (item.__model === 'Product') {
       const productPartition = item.getPartition(); // Returns a Partition instance
+      
+      // Now you can also edit and save directly if it matches a item
+      item.price = 45;
+      await item.save();
     }
   });
 }
@@ -98,8 +137,9 @@ async function indexExample() {
 
 ### 3. Creating Items with GSI Support
 
-You can pass index queries directly to `create()` to automatically populate GSI attributes.
+You can pass index queries directly to `create()` or `update()` to automatically populate GSI attributes. This works on both the Partition level and the Item level.
 
+#### Using Partition.create() and Partition.update()
 ```typescript
 const electronics = db.findByCategory('ELECTRONICS', 'RANK#1');
 
@@ -108,6 +148,38 @@ await db.Product('p123').create('INFO', {
   name: 'Gaming Mouse',
   price: 50
 }, [electronics]);
+
+// Partial update with GSI support
+await db.Product('p123').update('INFO', { price: 45 }, [electronics]);
+```
+
+#### Using Item.create() and Item.update()
+```typescript
+const electronics = db.findByCategory('ELECTRONICS', 'RANK#1');
+const mouse = db.Product('p123', 'INFO');
+
+// Pass data and indices directly to create()
+await mouse.create({ 
+  name: 'Gaming Mouse', 
+  price: 50 
+}, [electronics]);
+
+// Or use update() directly on the item for partial updates
+await mouse.update({ price: 40 }, [electronics]);
+```
+
+#### Using setIndex() for persistence
+You can also use `setIndex()` to attach indices to an item so they are used automatically whenever you call `save()`.
+
+```typescript
+const electronics = db.findByCategory('ELECTRONICS', 'RANK#1');
+const mouse = db.Product('p123', 'INFO');
+
+mouse.setIndex(electronics);
+mouse.price = 50;
+
+// save() will now automatically include GSI attributes from the attached index
+await mouse.save();
 ```
 
 ## Optional Configuration Parameters
@@ -163,13 +235,16 @@ if (token) {
 - `delete(params)`: Low-level DeleteCommand wrapper.
 - `query(params)`: Low-level QueryCommand wrapper.
 - `scan(params)`: Low-level ScanCommand wrapper.
+- `[ModelName](id, skValue?)`: Returns a `Partition` instance for the given ID. If `skValue` is provided, returns an `Item` object directly.
+- `findBy[IndexName](id, skValue?)`: Returns an `IndexQuery` instance.
 
 ### Partition
-- `get(sk)`: Fetches data for a specific SK (returns a Promise).
+- `get(sk)`: Fetches data for a specific Sort Key value (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.
+- `draft(sk, data?)`: Returns an `Item` object initialized with `data` (optional).
 - `deleteAll()`: Deletes all items in the partition.
 - `getLastEvaluatedKey()`: Returns the pagination token from the last `getAll()`.
 
@@ -178,6 +253,12 @@ if (token) {
 - `getAll(options?)`: Query index. Options: `{ limit, scanIndexForward, exclusiveStartKey, skValue }`.
 - `getLastEvaluatedKey()`: Returns the pagination token from the last `getAll()`.
 
+### Item (returned by Partition.get or draft)
+- `create(data?, indices?)`: Persists the item as a new record with the provided data. Supports GSI indices.
+- `update(data, indices?)`: Partial update of the item. Supports GSI indices.
+- `save()`: Persists the current state of the item (alias for update of all properties). Uses indices attached via `setIndex()`.
+- `setIndex(indices)`: Attaches one or more `IndexQuery` objects to the item for use with `save()` or `create()`.
+
 ## License
 
 MIT

package/dist/index-query.d.ts

@@ -33,5 +33,5 @@ export declare class IndexQuery {
     getSkName(): string;
     getSkValue(): string | undefined;
     getLastEvaluatedKey(): any;
-    private mapItemToModel;
+    private mapItemToModelItem;
 }

package/dist/index-query.js

@@ -11,6 +11,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IndexQuery = void 0;
 const partition_1 = require("./partition");
+const partition_2 = require("./partition");
 class IndexQuery {
     constructor(db, config) {
         this.lastEvaluatedKey = null;
@@ -54,7 +55,7 @@ class IndexQuery {
                 ExclusiveStartKey: options === null || options === void 0 ? void 0 : options.exclusiveStartKey,
             });
             const items = (response.Items || []);
-            const mappedItems = items.map(item => this.mapItemToModel(item));
+            const mappedItems = items.map(item => this.mapItemToModelItem(item));
             this.lastEvaluatedKey = response.LastEvaluatedKey || null;
             return mappedItems;
         });
@@ -80,7 +81,7 @@ class IndexQuery {
     getLastEvaluatedKey() {
         return this.lastEvaluatedKey;
     }
-    mapItemToModel(item) {
+    mapItemToModelItem(item) {
         const pkName = this.db.getPkName();
         const pkValue = item[pkName];
         if (!pkValue)
@@ -96,13 +97,17 @@ class IndexQuery {
                 const partition = new partition_1.Partition(this.db, { pkPrefix: fullPrefix }, id);
                 // Pre-fill the cache if we have the SK
                 const skName = this.db.getSkName();
-                if (item[skName]) {
-                    partition["cache"][item[skName]] = item;
+                const skValue = item[skName];
+                if (skValue) {
+                    partition["cache"][skValue] = item;
                 }
                 // Add a property __model to the item if it matches.
                 item.__model = name;
                 // Also provide a way to get the partition instance from the item
                 item.getPartition = () => partition;
+                if (skValue) {
+                    return new partition_2.Item(partition, skValue, item);
+                }
                 return item;
             }
         }

package/dist/index.d.ts

@@ -64,4 +64,5 @@ export declare class DynoQuery {
     }>;
 }
 export * from "./partition";
+export { Item } from "./partition";
 export * from "./index-query";

package/dist/index.js

@@ -34,7 +34,7 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DynoQuery = void 0;
+exports.Item = exports.DynoQuery = void 0;
 const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
 const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
 const partition_1 = require("./partition");
@@ -55,8 +55,12 @@ class DynoQuery {
         if (models) {
             this.registeredModels = models;
             Object.entries(models).forEach(([name, def]) => {
-                this[name] = (id) => {
-                    return new partition_1.Partition(this, { pkPrefix: this.globalPkPrefix + def.pkPrefix }, id);
+                this[name] = (id, sk) => {
+                    const partition = new partition_1.Partition(this, { pkPrefix: this.globalPkPrefix + def.pkPrefix }, id);
+                    if (sk) {
+                        return partition.draft(sk);
+                    }
+                    return partition;
                 };
             });
         }
@@ -167,4 +171,6 @@ class DynoQuery {
 }
 exports.DynoQuery = DynoQuery;
 __exportStar(require("./partition"), exports);
+var partition_2 = require("./partition");
+Object.defineProperty(exports, "Item", { enumerable: true, get: function () { return partition_2.Item; } });
 __exportStar(require("./index-query"), exports);

package/dist/partition.d.ts

@@ -5,6 +5,11 @@ export interface PartitionConfig {
     pk?: string;
     pkPrefix?: string;
 }
+export declare class Item {
+    [key: string]: any;
+    private _indices;
+    constructor(partition: Partition, skValue: string, data: any);
+}
 export declare class Partition {
     protected db: DynoQuery;
     protected tableName?: string;
@@ -30,20 +35,28 @@ export declare class Partition {
      * Create an item in this partition.
      */
     create<T = any>(sk: string, data: T, indices?: IndexQuery[]): Promise<T>;
+    /**
+     * Internal method to get raw data for a specific SK.
+     */
+    private _getRaw;
     /**
      * Update an existing item in this partition.
      */
-    update<T = any>(sk: string, data: Partial<T>): Promise<T>;
+    update<T = any>(sk: string, data: Partial<T>, indices?: IndexQuery[]): Promise<T>;
     /**
      * Delete an item by its SK within this partition.
      */
     delete(sk: string): Promise<void>;
     /**
-     * Get data for a specific SK within this partition.
-     * If the partition is loaded, it returns from cache.
-     * Otherwise, it fetches the data immediately.
+     * Get data for a specific SK and return it wrapped in a Item object.
      */
     get<T = any>(sk: string): Promise<T | null>;
+    /**
+     * Pre-draft an item for creation. Returns an Item object.
+     * @param sk The sort key value
+     * @param data Initial data for the row
+     */
+    draft<T = any>(sk: string, data?: any): T;
     getPkValue(): string;
     getLastEvaluatedKey(): any;
     /**

package/dist/partition.js

@@ -9,7 +9,54 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Partition = void 0;
+exports.Partition = exports.Item = void 0;
+class Item {
+    constructor(partition, skValue, data) {
+        this._indices = [];
+        Object.assign(this, data);
+        const self = this;
+        return new Proxy(this, {
+            get(target, prop, receiver) {
+                if (prop === "save") {
+                    return () => {
+                        const dataToSave = {};
+                        for (const key in target) {
+                            if (Object.prototype.hasOwnProperty.call(target, key) && key !== "_indices" && typeof target[key] !== 'function') {
+                                dataToSave[key] = target[key];
+                            }
+                        }
+                        return partition.update(skValue, dataToSave, self._indices);
+                    };
+                }
+                if (prop === "create") {
+                    return (data, indices) => {
+                        const dataToSave = data || {};
+                        const finalIndices = indices || self._indices;
+                        return partition.create(skValue, dataToSave, finalIndices);
+                    };
+                }
+                if (prop === "update") {
+                    return (data, indices) => {
+                        return partition.update(skValue, data, indices);
+                    };
+                }
+                if (prop === "setIndex") {
+                    return (indexObj) => {
+                        if (Array.isArray(indexObj)) {
+                            self._indices.push(...indexObj);
+                        }
+                        else {
+                            self._indices.push(indexObj);
+                        }
+                        return receiver;
+                    };
+                }
+                return Reflect.get(target, prop, receiver);
+            },
+        });
+    }
+}
+exports.Item = Item;
 class Partition {
     constructor(db, config, id) {
         this.cache = {};
@@ -76,7 +123,7 @@ class Partition {
                 this.isLoaded = true;
             }
             this.lastEvaluatedKey = response.LastEvaluatedKey || null;
-            return items;
+            return items.map((item) => new Item(this, item[this.skName], item));
         });
     }
     /**
@@ -98,17 +145,42 @@ class Partition {
                 Item: item,
             });
             this.cache[sk] = item;
-            return item;
+            return new Item(this, sk, item);
+        });
+    }
+    /**
+     * Internal method to get raw data for a specific SK.
+     */
+    _getRaw(sk) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.cache[sk] !== undefined) {
+                return this.cache[sk] || null;
+            }
+            if (this.isLoaded) {
+                return null;
+            }
+            const response = yield this.db.get({
+                TableName: this.tableName,
+                Key: {
+                    [this.pkName]: this.pkValue,
+                    [this.skName]: sk,
+                },
+            });
+            const data = response.Item || null;
+            if (data) {
+                this.cache[sk] = data;
+            }
+            return data;
         });
     }
     /**
      * Update an existing item in this partition.
      */
-    update(sk, data) {
+    update(sk, data, indices) {
         return __awaiter(this, void 0, void 0, function* () {
-            const current = (yield this.get(sk)) || {};
+            const current = (yield this._getRaw(sk)) || {};
             const updated = Object.assign(Object.assign({}, current), data);
-            return yield this.create(sk, updated);
+            return yield this.create(sk, updated, indices);
         });
     }
     /**
@@ -127,32 +199,22 @@ class Partition {
         });
     }
     /**
-     * Get data for a specific SK within this partition.
-     * If the partition is loaded, it returns from cache.
-     * Otherwise, it fetches the data immediately.
+     * Get data for a specific SK and return it wrapped in a Item object.
      */
     get(sk) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (this.cache[sk] !== undefined) {
-                return this.cache[sk] || null;
-            }
-            if (this.isLoaded) {
-                return null;
-            }
-            const response = yield this.db.get({
-                TableName: this.tableName,
-                Key: {
-                    [this.pkName]: this.pkValue,
-                    [this.skName]: sk,
-                },
-            });
-            const data = response.Item || null;
-            if (data) {
-                this.cache[sk] = data;
-            }
-            return data;
+            const data = yield this._getRaw(sk);
+            return data ? new Item(this, sk, data) : null;
         });
     }
+    /**
+     * Pre-draft an item for creation. Returns an Item object.
+     * @param sk The sort key value
+     * @param data Initial data for the row
+     */
+    draft(sk, data = {}) {
+        return new Item(this, sk, data);
+    }
     getPkValue() {
         return this.pkValue;
     }

package/package.json

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