betterddb 0.1.0

package/lib/betterddb.js

@@ -0,0 +1,458 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BetterDDB = void 0;
+/**
+ * BetterDDB is a definition-based DynamoDB wrapper library.
+ */
+class BetterDDB {
+    constructor(options) {
+        var _a;
+        this.schema = options.schema;
+        this.tableName = options.tableName;
+        this.keys = options.keys;
+        this.client = options.client;
+        this.autoTimestamps = (_a = options.autoTimestamps) !== null && _a !== void 0 ? _a : false;
+    }
+    // Helper: Retrieve the key value from a KeyDefinition.
+    getKeyValue(def, rawKey) {
+        if (typeof def === 'string' || typeof def === 'number' || typeof def === 'symbol') {
+            return String(rawKey[def]);
+        }
+        else {
+            return def.build(rawKey);
+        }
+    }
+    /**
+     * Build the primary key from a raw key object.
+     */
+    buildKey(rawKey) {
+        const keyObj = {};
+        // For primary (partition) key:
+        const pkConfig = this.keys.primary;
+        keyObj[pkConfig.name] =
+            (typeof pkConfig.definition === 'string' ||
+                typeof pkConfig.definition === 'number' ||
+                typeof pkConfig.definition === 'symbol')
+                ? String(rawKey[pkConfig.definition])
+                : pkConfig.definition.build(rawKey);
+        // For sort key, if defined:
+        if (this.keys.sort) {
+            const skConfig = this.keys.sort;
+            keyObj[skConfig.name] =
+                (typeof skConfig.definition === 'string' ||
+                    typeof skConfig.definition === 'number' ||
+                    typeof skConfig.definition === 'symbol')
+                    ? String(rawKey[skConfig.definition])
+                    : skConfig.definition.build(rawKey);
+        }
+        return keyObj;
+    }
+    /**
+     * Build index attributes for each defined GSI.
+     */
+    buildIndexes(rawItem) {
+        const indexAttributes = {};
+        if (this.keys.gsis) {
+            for (const gsiName in this.keys.gsis) {
+                const gsiConfig = this.keys.gsis[gsiName];
+                // Compute primary index attribute.
+                const primaryConfig = gsiConfig.primary;
+                indexAttributes[primaryConfig.name] =
+                    (typeof primaryConfig.definition === 'string' ||
+                        typeof primaryConfig.definition === 'number' ||
+                        typeof primaryConfig.definition === 'symbol')
+                        ? String(rawItem[primaryConfig.definition])
+                        : primaryConfig.definition.build(rawItem);
+                // Compute sort index attribute if provided.
+                if (gsiConfig.sort) {
+                    const sortConfig = gsiConfig.sort;
+                    indexAttributes[sortConfig.name] =
+                        (typeof sortConfig.definition === 'string' ||
+                            typeof sortConfig.definition === 'number' ||
+                            typeof sortConfig.definition === 'symbol')
+                            ? String(rawItem[sortConfig.definition])
+                            : sortConfig.definition.build(rawItem);
+                }
+            }
+        }
+        return indexAttributes;
+    }
+    /**
+     * Create an item:
+     * - Computes primary key and index attributes,
+     * - Optionally injects timestamps,
+     * - Validates the item and writes it to DynamoDB.
+     */
+    async create(item) {
+        if (this.autoTimestamps) {
+            const now = new Date().toISOString();
+            item = { ...item, createdAt: now, updatedAt: now };
+        }
+        const validated = this.schema.parse(item);
+        let finalItem = { ...validated };
+        // Compute and merge primary key.
+        const computedKeys = this.buildKey(validated);
+        finalItem = { ...finalItem, ...computedKeys };
+        // Compute and merge index attributes.
+        const indexAttributes = this.buildIndexes(validated);
+        finalItem = { ...finalItem, ...indexAttributes };
+        try {
+            await this.client.put({ TableName: this.tableName, Item: finalItem }).promise();
+            return validated;
+        }
+        catch (error) {
+            console.error('Error during create operation:', error);
+            throw error;
+        }
+    }
+    async get(rawKey) {
+        const Key = this.buildKey(rawKey);
+        try {
+            const result = await this.client.get({ TableName: this.tableName, Key }).promise();
+            if (!result.Item)
+                return null;
+            return this.schema.parse(result.Item);
+        }
+        catch (error) {
+            console.error('Error during get operation:', error);
+            throw error;
+        }
+    }
+    async update(rawKey, update, options) {
+        const ExpressionAttributeNames = {};
+        const ExpressionAttributeValues = {};
+        const UpdateExpressionParts = [];
+        const ConditionExpressionParts = [];
+        // Exclude key fields from update.
+        const keyFieldNames = [
+            this.keys.primary.name,
+            this.keys.sort ? this.keys.sort.name : undefined
+        ].filter(Boolean);
+        for (const [attr, value] of Object.entries(update)) {
+            if (keyFieldNames.includes(attr))
+                continue;
+            const attributeKey = `#${attr}`;
+            const valueKey = `:${attr}`;
+            ExpressionAttributeNames[attributeKey] = attr;
+            ExpressionAttributeValues[valueKey] = value;
+            UpdateExpressionParts.push(`${attributeKey} = ${valueKey}`);
+        }
+        if (this.autoTimestamps) {
+            const now = new Date().toISOString();
+            ExpressionAttributeNames['#updatedAt'] = 'updatedAt';
+            ExpressionAttributeValues[':updatedAt'] = now;
+            UpdateExpressionParts.push('#updatedAt = :updatedAt');
+        }
+        if ((options === null || options === void 0 ? void 0 : options.expectedVersion) !== undefined) {
+            ExpressionAttributeNames['#version'] = 'version';
+            ExpressionAttributeValues[':expectedVersion'] = options.expectedVersion;
+            ExpressionAttributeValues[':newVersion'] = options.expectedVersion + 1;
+            UpdateExpressionParts.push('#version = :newVersion');
+            ConditionExpressionParts.push('#version = :expectedVersion');
+        }
+        if (UpdateExpressionParts.length === 0) {
+            throw new Error('No attributes provided to update');
+        }
+        const UpdateExpression = 'SET ' + UpdateExpressionParts.join(', ');
+        const params = {
+            TableName: this.tableName,
+            Key: this.buildKey(rawKey),
+            UpdateExpression,
+            ExpressionAttributeNames,
+            ExpressionAttributeValues,
+            ReturnValues: 'ALL_NEW'
+        };
+        if (ConditionExpressionParts.length > 0) {
+            params.ConditionExpression = ConditionExpressionParts.join(' AND ');
+        }
+        try {
+            const result = await this.client.update(params).promise();
+            if (!result.Attributes) {
+                throw new Error('No attributes returned after update');
+            }
+            return this.schema.parse(result.Attributes);
+        }
+        catch (error) {
+            console.error('Error during update operation:', error);
+            throw error;
+        }
+    }
+    async delete(rawKey) {
+        const Key = this.buildKey(rawKey);
+        try {
+            await this.client.delete({ TableName: this.tableName, Key }).promise();
+        }
+        catch (error) {
+            console.error('Error during delete operation:', error);
+            throw error;
+        }
+    }
+    async queryByGsi(gsiName, key, sortKeyCondition) {
+        if (!this.keys.gsis || !this.keys.gsis[gsiName]) {
+            throw new Error(`GSI "${gsiName}" is not configured`);
+        }
+        const indexConfig = this.keys.gsis[gsiName];
+        const ExpressionAttributeNames = {
+            [`#${indexConfig.primary.name}`]: indexConfig.primary.name
+        };
+        const ExpressionAttributeValues = {
+            [`:${indexConfig.primary.name}`]: (typeof indexConfig.primary.definition === 'string' ||
+                typeof indexConfig.primary.definition === 'number' ||
+                typeof indexConfig.primary.definition === 'symbol')
+                ? String(key[indexConfig.primary.definition])
+                : indexConfig.primary.definition.build(key)
+        };
+        let KeyConditionExpression = `#${indexConfig.primary.name} = :${indexConfig.primary.name}`;
+        if (indexConfig.sort && sortKeyCondition) {
+            const skFieldName = indexConfig.sort.name;
+            ExpressionAttributeNames['#gsiSk'] = skFieldName;
+            switch (sortKeyCondition.operator) {
+                case 'eq':
+                    ExpressionAttributeValues[':gsiSk'] = sortKeyCondition.values;
+                    KeyConditionExpression += ' AND #gsiSk = :gsiSk';
+                    break;
+                case 'begins_with':
+                    ExpressionAttributeValues[':gsiSk'] = sortKeyCondition.values;
+                    KeyConditionExpression += ' AND begins_with(#gsiSk, :gsiSk)';
+                    break;
+                case 'between':
+                    if (!Array.isArray(sortKeyCondition.values) || sortKeyCondition.values.length !== 2) {
+                        throw new Error("For 'between' operator, values must be a tuple of two items");
+                    }
+                    ExpressionAttributeValues[':gsiSkStart'] = sortKeyCondition.values[0];
+                    ExpressionAttributeValues[':gsiSkEnd'] = sortKeyCondition.values[1];
+                    KeyConditionExpression += ' AND #gsiSk BETWEEN :gsiSkStart AND :gsiSkEnd';
+                    break;
+                default:
+                    throw new Error(`Unsupported sort key operator: ${sortKeyCondition.operator}`);
+            }
+        }
+        try {
+            const result = await this.client
+                .query({
+                TableName: this.tableName,
+                IndexName: gsiName,
+                KeyConditionExpression,
+                ExpressionAttributeNames,
+                ExpressionAttributeValues
+            })
+                .promise();
+            return (result.Items || []).map(item => this.schema.parse(item));
+        }
+        catch (error) {
+            console.error('Error during queryByGsi operation:', error);
+            throw error;
+        }
+    }
+    /**
+     * Query by primary key (using the computed primary key) and an optional sort key condition.
+     */
+    async queryByPrimaryKey(rawKey, sortKeyCondition, options) {
+        const pkAttrName = this.keys.primary.name;
+        const pkValue = (typeof this.keys.primary.definition === 'string' ||
+            typeof this.keys.primary.definition === 'number' ||
+            typeof this.keys.primary.definition === 'symbol')
+            ? String(rawKey[this.keys.primary.definition])
+            : this.keys.primary.definition.build(rawKey);
+        const ExpressionAttributeNames = {
+            [`#${pkAttrName}`]: pkAttrName
+        };
+        const ExpressionAttributeValues = {
+            [`:${pkAttrName}`]: pkValue
+        };
+        let KeyConditionExpression = `#${pkAttrName} = :${pkAttrName}`;
+        if (this.keys.sort && sortKeyCondition) {
+            const skAttrName = this.keys.sort.name;
+            ExpressionAttributeNames[`#${skAttrName}`] = skAttrName;
+            switch (sortKeyCondition.operator) {
+                case 'eq':
+                    ExpressionAttributeValues[':skValue'] = sortKeyCondition.values;
+                    KeyConditionExpression += ` AND #${skAttrName} = :skValue`;
+                    break;
+                case 'begins_with':
+                    ExpressionAttributeValues[':skValue'] = sortKeyCondition.values;
+                    KeyConditionExpression += ` AND begins_with(#${skAttrName}, :skValue)`;
+                    break;
+                case 'between':
+                    if (!Array.isArray(sortKeyCondition.values) || sortKeyCondition.values.length !== 2) {
+                        throw new Error("For 'between' operator, values must be a tuple of two items");
+                    }
+                    ExpressionAttributeValues[':skStart'] = sortKeyCondition.values[0];
+                    ExpressionAttributeValues[':skEnd'] = sortKeyCondition.values[1];
+                    KeyConditionExpression += ` AND #${skAttrName} BETWEEN :skStart AND :skEnd`;
+                    break;
+                default:
+                    throw new Error(`Unsupported sort key operator: ${sortKeyCondition.operator}`);
+            }
+        }
+        const queryParams = {
+            TableName: this.tableName,
+            KeyConditionExpression,
+            ExpressionAttributeNames,
+            ExpressionAttributeValues
+        };
+        if (options === null || options === void 0 ? void 0 : options.limit) {
+            queryParams.Limit = options.limit;
+        }
+        if (options === null || options === void 0 ? void 0 : options.lastKey) {
+            queryParams.ExclusiveStartKey = options.lastKey;
+        }
+        const result = await this.client.query(queryParams).promise();
+        const items = (result.Items || []).map(item => this.schema.parse(item));
+        return { items, lastKey: result.LastEvaluatedKey };
+    }
+    // ───── Transaction Helpers ─────────────────────────────
+    buildTransactPut(item) {
+        const computedKeys = this.buildKey(item);
+        const indexAttributes = this.buildIndexes(item);
+        const finalItem = { ...item, ...computedKeys, ...indexAttributes };
+        const validated = this.schema.parse(finalItem);
+        return {
+            Put: {
+                TableName: this.tableName,
+                Item: validated
+            }
+        };
+    }
+    buildTransactUpdate(rawKey, update, options) {
+        const ExpressionAttributeNames = {};
+        const ExpressionAttributeValues = {};
+        const UpdateExpressionParts = [];
+        const ConditionExpressionParts = [];
+        const keyFieldNames = [
+            this.keys.primary.name,
+            this.keys.sort ? this.keys.sort.name : undefined
+        ].filter(Boolean);
+        for (const [attr, value] of Object.entries(update)) {
+            if (keyFieldNames.includes(attr))
+                continue;
+            const attributeKey = `#${attr}`;
+            const valueKey = `:${attr}`;
+            ExpressionAttributeNames[attributeKey] = attr;
+            ExpressionAttributeValues[valueKey] = value;
+            UpdateExpressionParts.push(`${attributeKey} = ${valueKey}`);
+        }
+        if (this.autoTimestamps) {
+            const now = new Date().toISOString();
+            ExpressionAttributeNames['#updatedAt'] = 'updatedAt';
+            ExpressionAttributeValues[':updatedAt'] = now;
+            UpdateExpressionParts.push('#updatedAt = :updatedAt');
+        }
+        if ((options === null || options === void 0 ? void 0 : options.expectedVersion) !== undefined) {
+            ExpressionAttributeNames['#version'] = 'version';
+            ExpressionAttributeValues[':expectedVersion'] = options.expectedVersion;
+            ExpressionAttributeValues[':newVersion'] = options.expectedVersion + 1;
+            UpdateExpressionParts.push('#version = :newVersion');
+            ConditionExpressionParts.push('#version = :expectedVersion');
+        }
+        if (UpdateExpressionParts.length === 0) {
+            throw new Error('No attributes provided to update in transactUpdate');
+        }
+        const UpdateExpression = 'SET ' + UpdateExpressionParts.join(', ');
+        const updateItem = {
+            TableName: this.tableName,
+            Key: this.buildKey(rawKey),
+            UpdateExpression,
+            ExpressionAttributeNames,
+            ExpressionAttributeValues
+        };
+        if (ConditionExpressionParts.length > 0) {
+            updateItem.ConditionExpression = ConditionExpressionParts.join(' AND ');
+        }
+        return { Update: updateItem };
+    }
+    buildTransactDelete(rawKey) {
+        return {
+            Delete: {
+                TableName: this.tableName,
+                Key: this.buildKey(rawKey)
+            }
+        };
+    }
+    async transactWrite(operations) {
+        try {
+            await this.client.transactWrite({ TransactItems: operations }).promise();
+        }
+        catch (error) {
+            console.error('Error during transactWrite operation:', error);
+            throw error;
+        }
+    }
+    async transactGetByKeys(rawKeys) {
+        const getItems = rawKeys.map(key => ({ TableName: this.tableName, Key: this.buildKey(key) }));
+        return this.transactGet(getItems);
+    }
+    async transactGet(getItems) {
+        try {
+            const response = await this.client
+                .transactGet({
+                TransactItems: getItems.map(item => ({ Get: item }))
+            })
+                .promise();
+            return (response.Responses || [])
+                .filter(r => r.Item)
+                .map(r => this.schema.parse(r.Item));
+        }
+        catch (error) {
+            console.error('Error during transactGet operation:', error);
+            throw error;
+        }
+    }
+    // ───── Batch Write Support ─────────────────────────────
+    async batchWrite(ops) {
+        const putRequests = (ops.puts || []).map(item => {
+            const computedKeys = this.buildKey(item);
+            const indexAttributes = this.buildIndexes(item);
+            const finalItem = { ...item, ...computedKeys, ...indexAttributes };
+            const validated = this.schema.parse(finalItem);
+            return { PutRequest: { Item: validated } };
+        });
+        const deleteRequests = (ops.deletes || []).map(rawKey => {
+            const key = this.buildKey(rawKey);
+            return { DeleteRequest: { Key: key } };
+        });
+        const allRequests = [...putRequests, ...deleteRequests];
+        for (let i = 0; i < allRequests.length; i += 25) {
+            const chunk = allRequests.slice(i, i + 25);
+            let unprocessed = await this.batchWriteChunk(chunk);
+            while (unprocessed && Object.keys(unprocessed).length > 0) {
+                await new Promise(resolve => setTimeout(resolve, 1000));
+                unprocessed = await this.retryBatchWrite(unprocessed);
+            }
+        }
+    }
+    async batchWriteChunk(chunk) {
+        const params = {
+            RequestItems: {
+                [this.tableName]: chunk
+            }
+        };
+        const result = await this.client.batchWrite(params).promise();
+        return result.UnprocessedItems;
+    }
+    async retryBatchWrite(unprocessed) {
+        const params = { RequestItems: unprocessed };
+        const result = await this.client.batchWrite(params).promise();
+        return result.UnprocessedItems;
+    }
+    // ───── Batch Get Support ─────────────────────────────
+    async batchGet(rawKeys) {
+        const keys = rawKeys.map(key => this.buildKey(key));
+        const results = [];
+        for (let i = 0; i < keys.length; i += 100) {
+            const chunk = keys.slice(i, i + 100);
+            const params = {
+                RequestItems: {
+                    [this.tableName]: {
+                        Keys: chunk
+                    }
+                }
+            };
+            const result = await this.client.batchGet(params).promise();
+            const items = result.Responses ? result.Responses[this.tableName] : [];
+            results.push(...items.map(item => this.schema.parse(item)));
+        }
+        return results;
+    }
+}
+exports.BetterDDB = BetterDDB;

package/lib/index.d.ts

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

package/lib/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("./betterddb"), exports);

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "betterddb",
+  "version": "0.1.0",
+  "description": "A definition-based DynamoDB wrapper library that provides a schema-driven and fully typesafe DAL.",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "docker:up": "docker-compose up -d",
+    "docker:down": "docker-compose down",
+    "test": "npm run docker:up && jest && npm run docker:down",
+    "test:watch": "npm run docker:up && jest --watch",
+    "test:coverage": "npm run docker:up && jest --coverage && npm run docker:down"
+  },
+  "keywords": [
+    "dynamodb",
+    "dal",
+    "aws-sdk",
+    "zod",
+    "typescript",
+    "wrapper",
+    "compound-key",
+    "transactions",
+    "batch",
+    "pagination"
+  ],
+  "author": "R.R. Wang",
+  "license": "MIT",
+  "dependencies": {
+    "aws-sdk": "^2.1370.0",
+    "zod": "^3.21.4"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^18.15.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^4.9.5"
+  }
+}