dynoquery 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # DynoQuery
 
-A lightweight wrapper for Amazon DynamoDB using the AWS SDK v3.
+A lightweight wrapper for Amazon DynamoDB using the AWS SDK v3, specifically designed for **Single-Table Design** patterns.
 
 ## Installation
 
@@ -11,6 +11,7 @@ npm install dynoquery
 ## Features
 
 - Basic CRUD operations (create, get, update, delete)
+- Optimized for **Single-Table Design**
 - Model-based approach for easy data management
 - Query and Scan support
 - Batch operations (batchGet, batchWrite)
@@ -24,11 +25,16 @@ 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'
   partitions: {
     User: { pkPrefix: 'USER#' },
+  },
+  indexes: {
+    ByCategory: { indexName: 'GSI1', pkName: 'GSI1PK', skName: 'GSI1SK', pkPrefix: 'CAT#' }
   }
 });
 
@@ -37,8 +43,23 @@ async function example() {
   // Resulting PK: TENANT#A#USER#john@example.com
   const john = db.User('john@example.com');
   
+  // Use registered index
+  // Resulting GSI1PK: TENANT#A#CAT#1
+  const categories = db.ByCategory('1');
+  const items = await categories.get('100');
+  const allItems = await categories.getAll();
+  
+  // Index results are automatically mapped to models based on PK prefix
+  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();
+    }
+  });
+  
   // Load all data for this partition (optional, but good for multiple reads)
-  await john.loadAll();
+  const allJohnData = await john.getAll();
   
   // john.get() loads data immediately (using cache if loaded)
   const userMetadata = await john.get('METADATA');
@@ -90,11 +111,17 @@ A model-based abstraction for a specific data type.
 ### Partition
 A way to manage models and data within a specific partition.
 - `get(sk)`: Fetches data for a specific sort key (returns a Promise).
-- `loadAll()`: Fetches all items in the partition and caches them.
+- `getAll()`: Fetches all items in the partition and caches them. Returns the items.
 - `create(sk, data)`: Creates an item in the partition and returns its `Model`.
 - `model(sk)`: Get a `Model` instance for a specific sort key.
 - `deleteAll()`: Deletes all items in the partition.
 
+### IndexQuery
+A way to query Global Secondary Indexes.
+- `get(skValue | options)`: Query items in the index. Supports `skValue` (string) for `begins_with` search, or an options object with `skValue`, `limit`, and `scanIndexForward`.
+- `getAll()`: Fetches all items in the index for the given partition key.
+- Automatically identifies models in results using `__model` and provides `getPartition()` helper.
+
 ## License
 
 MIT

package/dist/index-query.d.ts

@@ -0,0 +1,25 @@
+import { DynoQuery } from "./index";
+export interface IndexQueryConfig {
+    tableName?: string;
+    indexName: string;
+    pkName?: string;
+    skName?: string;
+    pkPrefix?: string;
+    pkValue: string;
+}
+export declare class IndexQuery {
+    protected db: DynoQuery;
+    protected tableName: string;
+    protected indexName: string;
+    protected pkName: string;
+    protected skName: string;
+    protected pkValue: string;
+    constructor(db: DynoQuery, config: IndexQueryConfig);
+    get<T = any>(skValueOrOptions?: string | {
+        skValue?: string;
+        limit?: number;
+        scanIndexForward?: boolean;
+    }): Promise<T[]>;
+    getAll<T = any>(): Promise<T[]>;
+    private mapItemToModel;
+}

package/dist/index-query.js

@@ -0,0 +1,100 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IndexQuery = void 0;
+const partition_1 = require("./partition");
+class IndexQuery {
+    constructor(db, config) {
+        this.db = db;
+        this.tableName = config.tableName || db.getTableName() || "";
+        this.indexName = config.indexName;
+        this.pkName = config.pkName || "GSI1PK";
+        this.skName = config.skName || "GSI1SK";
+        const globalPrefix = db.getPkPrefix();
+        const indexPrefix = config.pkPrefix || "";
+        let finalPrefix = indexPrefix;
+        if (globalPrefix && !indexPrefix.startsWith(globalPrefix)) {
+            finalPrefix = globalPrefix + indexPrefix;
+        }
+        this.pkValue = `${finalPrefix}${config.pkValue}`;
+        if (!this.tableName) {
+            throw new Error("TableName must be provided in IndexQueryConfig or DynoQueryConfig");
+        }
+    }
+    get(skValueOrOptions) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let options = {};
+            if (typeof skValueOrOptions === 'string') {
+                options.skValue = skValueOrOptions;
+            }
+            else if (typeof skValueOrOptions === 'object') {
+                options = skValueOrOptions;
+            }
+            let keyCondition = "#pk = :pk";
+            const expressionAttributeNames = {
+                "#pk": this.pkName,
+            };
+            const expressionAttributeValues = {
+                ":pk": this.pkValue,
+            };
+            if (options.skValue) {
+                keyCondition += " AND begins_with(#sk, :sk)";
+                expressionAttributeNames["#sk"] = this.skName;
+                expressionAttributeValues[":sk"] = options.skValue;
+            }
+            const response = yield this.db.query({
+                TableName: this.tableName,
+                IndexName: this.indexName,
+                KeyConditionExpression: keyCondition,
+                ExpressionAttributeNames: expressionAttributeNames,
+                ExpressionAttributeValues: expressionAttributeValues,
+                Limit: options.limit,
+                ScanIndexForward: options.scanIndexForward,
+            });
+            const items = (response.Items || []);
+            return items.map(item => this.mapItemToModel(item));
+        });
+    }
+    getAll() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.get();
+        });
+    }
+    mapItemToModel(item) {
+        const pkName = this.db.getPkName();
+        const pkValue = item[pkName];
+        if (!pkValue)
+            return item;
+        const registeredPartitions = this.db.getRegisteredPartitions();
+        const globalPrefix = this.db.getPkPrefix();
+        for (const [name, def] of Object.entries(registeredPartitions)) {
+            const fullPrefix = globalPrefix + def.pkPrefix;
+            if (pkValue.startsWith(fullPrefix)) {
+                // Find the ID by removing the prefix
+                const id = pkValue.substring(fullPrefix.length);
+                // Return a Partition instance and attach the data to its cache.
+                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;
+                }
+                // 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;
+                return item;
+            }
+        }
+        return item;
+    }
+}
+exports.IndexQuery = IndexQuery;

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { PutCommandInput, GetCommandInput, UpdateCommandInput, DeleteCommandInput, QueryCommandInput, ScanCommandInput, BatchGetCommandInput, BatchWriteCommandInput } from "@aws-sdk/lib-dynamodb";
 export interface DynoQueryConfig {
     tableName?: string;
+    pkName?: string;
+    skName?: string;
     region?: string;
     endpoint?: string;
     pkPrefix?: string;
@@ -12,12 +14,21 @@ export interface DynoQueryConfig {
     partitions?: Record<string, {
         pkPrefix: string;
     }>;
+    indexes?: Record<string, {
+        indexName: string;
+        pkName?: string;
+        skName?: string;
+        pkPrefix?: string;
+    }>;
 }
 export declare class DynoQuery {
     private client;
     private docClient;
     private defaultTableName?;
     private globalPkPrefix;
+    private pkName;
+    private skName;
+    private registeredPartitions;
     [key: string]: any;
     constructor(config?: DynoQueryConfig);
     /**
@@ -54,6 +65,12 @@ export declare class DynoQuery {
     batchWrite(params: BatchWriteCommandInput): Promise<import("@aws-sdk/lib-dynamodb").BatchWriteCommandOutput>;
     getTableName(): string | undefined;
     getPkPrefix(): string;
+    getPkName(): string;
+    getSkName(): string;
+    getRegisteredPartitions(): Record<string, {
+        pkPrefix: string;
+    }>;
 }
 export * from "./model";
 export * from "./partition";
+export * from "./index-query";

package/dist/index.js

@@ -29,11 +29,15 @@ const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
 const partition_1 = require("./partition");
 class DynoQuery {
     constructor(config = {}) {
+        this.registeredPartitions = {};
         const clientConfig = Object.assign({}, config);
         // Remove properties that are not part of DynamoDBClientConfig
         delete clientConfig.tableName;
         delete clientConfig.pkPrefix;
         delete clientConfig.partitions;
+        delete clientConfig.indexes;
+        delete clientConfig.pkName;
+        delete clientConfig.skName;
         this.client = new client_dynamodb_1.DynamoDBClient(clientConfig);
         this.docClient = lib_dynamodb_1.DynamoDBDocumentClient.from(this.client, {
             marshallOptions: {
@@ -42,13 +46,30 @@ class DynoQuery {
         });
         this.defaultTableName = config.tableName;
         this.globalPkPrefix = config.pkPrefix || "";
+        this.pkName = config.pkName || "PK";
+        this.skName = config.skName || "SK";
         if (config.partitions) {
+            this.registeredPartitions = config.partitions;
             Object.entries(config.partitions).forEach(([name, def]) => {
                 this[name] = (id) => {
                     return new partition_1.Partition(this, { pkPrefix: this.globalPkPrefix + def.pkPrefix }, id);
                 };
             });
         }
+        if (config.indexes) {
+            const { IndexQuery } = require("./index-query");
+            Object.entries(config.indexes).forEach(([name, def]) => {
+                this[name] = (id) => {
+                    return new IndexQuery(this, {
+                        indexName: def.indexName,
+                        pkName: def.pkName,
+                        skName: def.skName,
+                        pkPrefix: def.pkPrefix,
+                        pkValue: id
+                    });
+                };
+            });
+        }
     }
     /**
      * Create or replace an item in the table.
@@ -129,9 +150,9 @@ class DynoQuery {
         return __awaiter(this, void 0, void 0, function* () {
             if (this.defaultTableName && params.RequestItems) {
                 // Note: Batch operations are a bit trickier because TableName is a key in RequestItems
-                // This wrapper doesn't automatically add it to RequestItems yet, 
-                // but let's see if we should handle it. 
-                // For now, let's keep it as is or add it if RequestItems is empty? 
+                // This wrapper doesn't automatically add it to RequestItems yet,
+                // but let's see if we should handle it.
+                // For now, let's keep it as is or add it if RequestItems is empty?
                 // Usually BatchGetCommandInput is complex.
             }
             const command = new lib_dynamodb_1.BatchGetCommand(params);
@@ -153,7 +174,17 @@ class DynoQuery {
     getPkPrefix() {
         return this.globalPkPrefix;
     }
+    getPkName() {
+        return this.pkName;
+    }
+    getSkName() {
+        return this.skName;
+    }
+    getRegisteredPartitions() {
+        return this.registeredPartitions;
+    }
 }
 exports.DynoQuery = DynoQuery;
 __exportStar(require("./model"), exports);
 __exportStar(require("./partition"), exports);
+__exportStar(require("./index-query"), exports);

package/dist/model.d.ts

@@ -10,6 +10,8 @@ export declare class Model<T = any> {
     protected tableName?: string;
     protected pkPrefix: string;
     protected skValue: string;
+    protected pkName: string;
+    protected skName: string;
     protected onUpdate?: (sk: any, data: any) => void;
     constructor(db: DynoQuery, config: ModelConfig<T>);
     protected getTableName(): string;

package/dist/model.js

@@ -16,6 +16,8 @@ class Model {
         this.tableName = config.tableName || db.getTableName();
         this.pkPrefix = config.pkPrefix;
         this.skValue = config.skValue;
+        this.pkName = db.getPkName();
+        this.skName = db.getSkName();
         this.onUpdate = config.onUpdate;
         if (!this.tableName) {
             throw new Error("TableName must be provided in ModelConfig or DynoQueryConfig");
@@ -36,8 +38,8 @@ class Model {
             const response = yield this.db.get({
                 TableName: this.getTableName(),
                 Key: {
-                    PK: this.getPK(id),
-                    SK: this.skValue,
+                    [this.pkName]: this.getPK(id),
+                    [this.skName]: this.skValue,
                 },
             });
             return response.Item || null;
@@ -48,7 +50,7 @@ class Model {
      */
     save(data_1) {
         return __awaiter(this, arguments, void 0, function* (data, id = "") {
-            const item = Object.assign({ PK: this.getPK(id), SK: this.skValue }, data);
+            const item = Object.assign({ [this.pkName]: this.getPK(id), [this.skName]: this.skValue }, data);
             yield this.db.create({
                 TableName: this.getTableName(),
                 Item: item,
@@ -70,8 +72,8 @@ class Model {
             const response = yield this.db.get({
                 TableName: this.getTableName(),
                 Key: {
-                    PK: this.getPK(id),
-                    SK: this.skValue,
+                    [this.pkName]: this.getPK(id),
+                    [this.skName]: this.skValue,
                 },
             });
             const current = response.Item || {};
@@ -87,8 +89,8 @@ class Model {
             yield this.db.delete({
                 TableName: this.getTableName(),
                 Key: {
-                    PK: this.getPK(id),
-                    SK: this.skValue,
+                    [this.pkName]: this.getPK(id),
+                    [this.skName]: this.skValue,
                 },
             });
             if (this.onUpdate) {

package/dist/partition.d.ts

@@ -9,13 +9,16 @@ export declare class Partition {
     protected db: DynoQuery;
     protected tableName?: string;
     protected pk: string;
+    protected pkName: string;
+    protected skName: string;
     protected cache: Record<string, any>;
     protected isLoaded: boolean;
     constructor(db: DynoQuery, config: PartitionConfig, id?: string);
     /**
-     * Load all data for this partition key.
+     * Fetches all items in the partition and caches them.
+     * Returns the data and caches it.
      */
-    loadAll(): Promise<this>;
+    getAll<T = any>(): Promise<T[]>;
     /**
      * Get a model instance for a specific SK within this partition.
      */

package/dist/partition.js

@@ -17,6 +17,8 @@ class Partition {
         this.isLoaded = false;
         this.db = db;
         this.tableName = config.tableName || db.getTableName();
+        this.pkName = db.getPkName();
+        this.skName = db.getSkName();
         if (config.pk) {
             this.pk = config.pk;
         }
@@ -50,26 +52,29 @@ class Partition {
         }
     }
     /**
-     * Load all data for this partition key.
+     * Fetches all items in the partition and caches them.
+     * Returns the data and caches it.
      */
-    loadAll() {
+    getAll() {
         return __awaiter(this, void 0, void 0, function* () {
             const response = yield this.db.query({
                 TableName: this.tableName,
-                KeyConditionExpression: "PK = :pk",
+                KeyConditionExpression: "#pk = :pk",
+                ExpressionAttributeNames: {
+                    "#pk": this.pkName,
+                },
                 ExpressionAttributeValues: {
                     ":pk": this.pk,
                 },
             });
-            if (response.Items) {
-                response.Items.forEach((item) => {
-                    if (item.SK) {
-                        this.cache[item.SK] = item;
-                    }
-                });
-            }
+            const items = (response.Items || []);
+            items.forEach((item) => {
+                if (item[this.skName]) {
+                    this.cache[item[this.skName]] = item;
+                }
+            });
             this.isLoaded = true;
-            return this;
+            return items;
         });
     }
     /**
@@ -132,7 +137,10 @@ class Partition {
         return __awaiter(this, void 0, void 0, function* () {
             const response = yield this.db.query({
                 TableName: this.tableName,
-                KeyConditionExpression: "PK = :pk",
+                KeyConditionExpression: "#pk = :pk",
+                ExpressionAttributeNames: {
+                    "#pk": this.pkName,
+                },
                 ExpressionAttributeValues: {
                     ":pk": this.pk,
                 },
@@ -148,8 +156,8 @@ class Partition {
                     const deleteRequests = chunk.map((item) => ({
                         DeleteRequest: {
                             Key: {
-                                PK: item.PK,
-                                SK: item.SK,
+                                [this.pkName]: item[this.pkName],
+                                [this.skName]: item[this.skName],
                             },
                         },
                     }));

package/package.json

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