betterddb 0.2.0 → 0.4.0

package/lib/builders/get-builder.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetBuilder = void 0;
+class GetBuilder {
+    constructor(parent, key) {
+        this.parent = parent;
+        this.key = key;
+        this.expressionAttributeNames = {};
+        this.extraTransactItems = [];
+    }
+    /**
+     * Specify a projection by providing an array of attribute names.
+     */
+    withProjection(attributes) {
+        this.projectionExpression = attributes.map(attr => `#${String(attr)}`).join(', ');
+        for (const attr of attributes) {
+            this.expressionAttributeNames[`#${String(attr)}`] = String(attr);
+        }
+        return this;
+    }
+    async execute() {
+        if (this.extraTransactItems.length > 0) {
+            // Build our update transaction item.
+            const myTransactItem = this.toTransactGet();
+            // Combine with extra transaction items.
+            const allItems = [...this.extraTransactItems, myTransactItem];
+            await this.parent.getClient().transactGet({
+                TransactItems: allItems
+            }).promise();
+            // After transaction, retrieve the updated item.
+            const result = await this.parent.get(this.key).execute();
+            return result;
+        }
+        else {
+            const params = {
+                TableName: this.parent.getTableName(),
+                Key: this.parent.buildKey(this.key)
+            };
+            if (this.projectionExpression) {
+                params.ProjectionExpression = this.projectionExpression;
+                params.ExpressionAttributeNames = this.expressionAttributeNames;
+            }
+            const result = await this.parent.getClient().get(params).promise();
+            if (!result.Item)
+                return null;
+            return this.parent.getSchema().parse(result.Item);
+        }
+    }
+    transactGet(ops) {
+        if (Array.isArray(ops)) {
+            this.extraTransactItems.push(...ops);
+        }
+        else {
+            this.extraTransactItems.push(ops);
+        }
+        return this;
+    }
+    toTransactGet() {
+        const getItem = {
+            TableName: this.parent.getTableName(),
+            Key: this.parent.buildKey(this.key)
+        };
+        if (this.projectionExpression) {
+            getItem.ProjectionExpression = this.projectionExpression;
+            getItem.ExpressionAttributeNames = this.expressionAttributeNames;
+        }
+        return { Get: getItem };
+    }
+    then(onfulfilled, onrejected) {
+        return this.execute().then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.execute().catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.execute().finally(onfinally);
+    }
+}
+exports.GetBuilder = GetBuilder;

package/lib/builders/query-builder.d.ts

@@ -0,0 +1,27 @@
+import { BetterDDB } from '../betterddb';
+export declare class QueryBuilder<T> {
+    private parent;
+    private key;
+    private filters;
+    private expressionAttributeNames;
+    private expressionAttributeValues;
+    private indexName?;
+    private sortKeyCondition?;
+    private limit?;
+    private lastKey?;
+    private ascending;
+    constructor(parent: BetterDDB<T>, key: Partial<T>);
+    usingIndex(indexName: string): this;
+    sortAscending(): this;
+    sortDescending(): this;
+    where(attribute: keyof T, operator: 'eq' | 'begins_with' | 'between', values: any | [any, any]): this;
+    limitResults(limit: number): this;
+    startFrom(lastKey: Record<string, any>): this;
+    /**
+     * Executes the query and returns a Promise that resolves with an array of items.
+     */
+    execute(): Promise<T[]>;
+    then<TResult1 = T[], TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<T[] | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<T[]>;
+}

package/lib/builders/query-builder.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryBuilder = void 0;
+class QueryBuilder {
+    constructor(parent, key) {
+        this.parent = parent;
+        this.key = key;
+        this.filters = [];
+        this.expressionAttributeNames = {};
+        this.expressionAttributeValues = {};
+        this.ascending = true;
+    }
+    usingIndex(indexName) {
+        this.indexName = indexName;
+        return this;
+    }
+    sortAscending() {
+        this.ascending = true;
+        return this;
+    }
+    sortDescending() {
+        this.ascending = false;
+        return this;
+    }
+    where(attribute, operator, values) {
+        const attrStr = String(attribute);
+        const nameKey = `#attr_${attrStr}`;
+        this.expressionAttributeNames[nameKey] = attrStr;
+        if (operator === 'eq') {
+            const valueKey = `:val_${attrStr}`;
+            this.expressionAttributeValues[valueKey] = values;
+            this.filters.push(`${nameKey} = ${valueKey}`);
+        }
+        else if (operator === 'begins_with') {
+            const valueKey = `:val_${attrStr}`;
+            this.expressionAttributeValues[valueKey] = values;
+            this.filters.push(`begins_with(${nameKey}, ${valueKey})`);
+        }
+        else if (operator === 'between') {
+            if (!Array.isArray(values) || values.length !== 2) {
+                throw new Error(`For 'between' operator, values must be a tuple of two items`);
+            }
+            const valueKeyStart = `:val_start_${attrStr}`;
+            const valueKeyEnd = `:val_end_${attrStr}`;
+            this.expressionAttributeValues[valueKeyStart] = values[0];
+            this.expressionAttributeValues[valueKeyEnd] = values[1];
+            this.filters.push(`${nameKey} BETWEEN ${valueKeyStart} AND ${valueKeyEnd}`);
+        }
+        else {
+            throw new Error(`Unsupported operator: ${operator}`);
+        }
+        return this;
+    }
+    limitResults(limit) {
+        this.limit = limit;
+        return this;
+    }
+    startFrom(lastKey) {
+        this.lastKey = lastKey;
+        return this;
+    }
+    /**
+     * Executes the query and returns a Promise that resolves with an array of items.
+     */
+    async execute() {
+        // Build a simple key condition for the partition key.
+        const keys = this.parent.getKeys();
+        const pkName = keys.primary.name;
+        this.expressionAttributeNames['#pk'] = pkName;
+        // Cast the built key to a record so that we can index by string.
+        const builtKey = this.parent.buildKey(this.key);
+        this.expressionAttributeValues[':pk_value'] = builtKey[pkName];
+        let keyConditionExpression = `#pk = :pk_value`;
+        // If a sortKeyCondition was set via another fluent method, append it.
+        if (this.sortKeyCondition) {
+            keyConditionExpression += ` AND ${this.sortKeyCondition}`;
+        }
+        // If any filters were added, set them as FilterExpression.
+        const params = {
+            TableName: this.parent.getTableName(),
+            KeyConditionExpression: keyConditionExpression,
+            ExpressionAttributeNames: this.expressionAttributeNames,
+            ExpressionAttributeValues: this.expressionAttributeValues,
+            ScanIndexForward: this.ascending,
+            Limit: this.limit,
+            ExclusiveStartKey: this.lastKey,
+            IndexName: this.indexName
+        };
+        if (this.filters.length > 0) {
+            params.FilterExpression = this.filters.join(' AND ');
+        }
+        const result = await this.parent.getClient().query(params).promise();
+        return this.parent.getSchema().array().parse(result.Items);
+    }
+    // Thenable implementation.
+    then(onfulfilled, onrejected) {
+        return this.execute().then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.execute().catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.execute().finally(onfinally);
+    }
+}
+exports.QueryBuilder = QueryBuilder;

package/lib/builders/scan-builder.d.ts

@@ -0,0 +1,20 @@
+import { BetterDDB } from '../betterddb';
+export declare class ScanBuilder<T> {
+    private parent;
+    private filters;
+    private expressionAttributeNames;
+    private expressionAttributeValues;
+    private limit?;
+    private lastKey?;
+    constructor(parent: BetterDDB<T>);
+    where(attribute: keyof T, operator: 'eq' | 'begins_with' | 'between', values: any | [any, any]): this;
+    limitResults(limit: number): this;
+    startFrom(lastKey: Record<string, any>): this;
+    /**
+     * Executes the scan and returns a Promise that resolves with an array of items.
+     */
+    execute(): Promise<T[]>;
+    then<TResult1 = T[], TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<T[] | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<T[]>;
+}

package/lib/builders/scan-builder.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScanBuilder = void 0;
+class ScanBuilder {
+    constructor(parent) {
+        this.parent = parent;
+        this.filters = [];
+        this.expressionAttributeNames = {};
+        this.expressionAttributeValues = {};
+    }
+    where(attribute, operator, values) {
+        const attrStr = String(attribute);
+        const nameKey = `#attr_${attrStr}`;
+        this.expressionAttributeNames[nameKey] = attrStr;
+        if (operator === 'eq') {
+            const valueKey = `:val_${attrStr}`;
+            this.expressionAttributeValues[valueKey] = values;
+            this.filters.push(`${nameKey} = ${valueKey}`);
+        }
+        else if (operator === 'begins_with') {
+            const valueKey = `:val_${attrStr}`;
+            this.expressionAttributeValues[valueKey] = values;
+            this.filters.push(`begins_with(${nameKey}, ${valueKey})`);
+        }
+        else if (operator === 'between') {
+            if (!Array.isArray(values) || values.length !== 2) {
+                throw new Error(`For 'between' operator, values must be a tuple of two items`);
+            }
+            const valueKeyStart = `:val_start_${attrStr}`;
+            const valueKeyEnd = `:val_end_${attrStr}`;
+            this.expressionAttributeValues[valueKeyStart] = values[0];
+            this.expressionAttributeValues[valueKeyEnd] = values[1];
+            this.filters.push(`${nameKey} BETWEEN ${valueKeyStart} AND ${valueKeyEnd}`);
+        }
+        else {
+            throw new Error(`Unsupported operator: ${operator}`);
+        }
+        return this;
+    }
+    limitResults(limit) {
+        this.limit = limit;
+        return this;
+    }
+    startFrom(lastKey) {
+        this.lastKey = lastKey;
+        return this;
+    }
+    /**
+     * Executes the scan and returns a Promise that resolves with an array of items.
+     */
+    async execute() {
+        const params = {
+            TableName: this.parent.getTableName(),
+            ExpressionAttributeNames: this.expressionAttributeNames,
+            ExpressionAttributeValues: this.expressionAttributeValues,
+            Limit: this.limit,
+            ExclusiveStartKey: this.lastKey
+        };
+        if (this.filters.length > 0) {
+            params.FilterExpression = this.filters.join(' AND ');
+        }
+        const result = await this.parent.getClient().scan(params).promise();
+        return this.parent.getSchema().array().parse(result.Items);
+    }
+    // Thenable implementation.
+    then(onfulfilled, onrejected) {
+        return this.execute().then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.execute().catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.execute().finally(onfinally);
+    }
+}
+exports.ScanBuilder = ScanBuilder;

package/lib/builders/update-builder.d.ts

@@ -0,0 +1,35 @@
+import { DynamoDB } from 'aws-sdk';
+import { BetterDDB } from '../betterddb';
+export declare class UpdateBuilder<T> {
+    private parent;
+    private key;
+    private actions;
+    private condition?;
+    private expectedVersion?;
+    private extraTransactItems;
+    constructor(parent: BetterDDB<T>, key: Partial<T>, expectedVersion?: number);
+    set(attrs: Partial<T>): this;
+    remove(attrs: (keyof T)[]): this;
+    add(attrs: Partial<Record<keyof T, number | Set<any>>>): this;
+    delete(attrs: Partial<Record<keyof T, Set<any>>>): this;
+    /**
+     * Adds a condition expression to the update.
+     */
+    setCondition(expression: string, attributeValues: Record<string, any>): this;
+    /**
+     * Specifies additional transaction items to include when executing this update as a transaction.
+     */
+    transactWrite(ops: DynamoDB.DocumentClient.TransactWriteItemList | DynamoDB.DocumentClient.TransactWriteItem): this;
+    /**
+     * Builds the update expression and associated maps.
+     */
+    private buildExpression;
+    /**
+     * Returns a transaction update item that can be included in a transactWrite call.
+     */
+    toTransactUpdate(): DynamoDB.DocumentClient.TransactWriteItem;
+    /**
+     * Commits the update immediately by calling the parent's update method.
+     */
+    execute(): Promise<T>;
+}

package/lib/builders/update-builder.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpdateBuilder = void 0;
+class UpdateBuilder {
+    // Reference to the parent BetterDDB instance and key.
+    constructor(parent, key, expectedVersion) {
+        this.parent = parent;
+        this.key = key;
+        this.actions = {};
+        // When using transaction mode, we store extra transaction items.
+        this.extraTransactItems = [];
+        this.expectedVersion = expectedVersion;
+    }
+    // Chainable methods:
+    set(attrs) {
+        this.actions.set = { ...this.actions.set, ...attrs };
+        return this;
+    }
+    remove(attrs) {
+        this.actions.remove = [...(this.actions.remove || []), ...attrs];
+        return this;
+    }
+    add(attrs) {
+        this.actions.add = { ...this.actions.add, ...attrs };
+        return this;
+    }
+    delete(attrs) {
+        this.actions.delete = { ...this.actions.delete, ...attrs };
+        return this;
+    }
+    /**
+     * Adds a condition expression to the update.
+     */
+    setCondition(expression, attributeValues) {
+        if (this.condition) {
+            // Merge conditions with AND.
+            this.condition.expression += ` AND ${expression}`;
+            Object.assign(this.condition.attributeValues, attributeValues);
+        }
+        else {
+            this.condition = { expression, attributeValues };
+        }
+        return this;
+    }
+    /**
+     * Specifies additional transaction items to include when executing this update as a transaction.
+     */
+    transactWrite(ops) {
+        if (Array.isArray(ops)) {
+            this.extraTransactItems.push(...ops);
+        }
+        else {
+            this.extraTransactItems.push(ops);
+        }
+        return this;
+    }
+    /**
+     * Builds the update expression and associated maps.
+     */
+    buildExpression() {
+        const ExpressionAttributeNames = {};
+        const ExpressionAttributeValues = {};
+        const clauses = [];
+        // Build SET clause.
+        if (this.actions.set) {
+            const setParts = [];
+            for (const [attr, value] of Object.entries(this.actions.set)) {
+                const nameKey = `#set_${attr}`;
+                const valueKey = `:set_${attr}`;
+                ExpressionAttributeNames[nameKey] = attr;
+                ExpressionAttributeValues[valueKey] = value;
+                setParts.push(`${nameKey} = ${valueKey}`);
+            }
+            if (setParts.length > 0) {
+                clauses.push(`SET ${setParts.join(', ')}`);
+            }
+        }
+        // Build REMOVE clause.
+        if (this.actions.remove && this.actions.remove.length > 0) {
+            const removeParts = this.actions.remove.map(attr => {
+                const nameKey = `#remove_${String(attr)}`;
+                ExpressionAttributeNames[nameKey] = String(attr);
+                return nameKey;
+            });
+            clauses.push(`REMOVE ${removeParts.join(', ')}`);
+        }
+        // Build ADD clause.
+        if (this.actions.add) {
+            const addParts = [];
+            for (const [attr, value] of Object.entries(this.actions.add)) {
+                const nameKey = `#add_${attr}`;
+                const valueKey = `:add_${attr}`;
+                ExpressionAttributeNames[nameKey] = attr;
+                ExpressionAttributeValues[valueKey] = value;
+                addParts.push(`${nameKey} ${valueKey}`);
+            }
+            if (addParts.length > 0) {
+                clauses.push(`ADD ${addParts.join(', ')}`);
+            }
+        }
+        // Build DELETE clause.
+        if (this.actions.delete) {
+            const deleteParts = [];
+            for (const [attr, value] of Object.entries(this.actions.delete)) {
+                const nameKey = `#delete_${attr}`;
+                const valueKey = `:delete_${attr}`;
+                ExpressionAttributeNames[nameKey] = attr;
+                ExpressionAttributeValues[valueKey] = value;
+                deleteParts.push(`${nameKey} ${valueKey}`);
+            }
+            if (deleteParts.length > 0) {
+                clauses.push(`DELETE ${deleteParts.join(', ')}`);
+            }
+        }
+        // Incorporate expectedVersion if provided.
+        if (this.expectedVersion !== undefined) {
+            ExpressionAttributeNames['#version'] = 'version';
+            ExpressionAttributeValues[':expectedVersion'] = this.expectedVersion;
+            ExpressionAttributeValues[':newVersion'] = this.expectedVersion + 1;
+            // Append version update in SET clause.
+            const versionClause = '#version = :newVersion';
+            const setIndex = clauses.findIndex(clause => clause.startsWith('SET '));
+            if (setIndex >= 0) {
+                clauses[setIndex] += `, ${versionClause}`;
+            }
+            else {
+                clauses.push(`SET ${versionClause}`);
+            }
+            // Ensure condition expression includes version check.
+            if (this.condition && this.condition.expression) {
+                this.condition.expression += ` AND #version = :expectedVersion`;
+            }
+            else {
+                this.condition = { expression: '#version = :expectedVersion', attributeValues: {} };
+            }
+        }
+        // Merge any provided condition attribute values.
+        if (this.condition) {
+            Object.assign(ExpressionAttributeValues, this.condition.attributeValues);
+        }
+        return {
+            updateExpression: clauses.join(' '),
+            attributeNames: ExpressionAttributeNames,
+            attributeValues: ExpressionAttributeValues
+        };
+    }
+    /**
+     * Returns a transaction update item that can be included in a transactWrite call.
+     */
+    toTransactUpdate() {
+        const { updateExpression, attributeNames, attributeValues } = this.buildExpression();
+        const updateItem = {
+            TableName: this.parent.getTableName(),
+            Key: this.parent.buildKey(this.key),
+            UpdateExpression: updateExpression,
+            ExpressionAttributeNames: attributeNames,
+            ExpressionAttributeValues: attributeValues
+        };
+        if (this.condition && this.condition.expression) {
+            updateItem.ConditionExpression = this.condition.expression;
+        }
+        return { Update: updateItem };
+    }
+    /**
+     * Commits the update immediately by calling the parent's update method.
+     */
+    async execute() {
+        if (this.extraTransactItems.length > 0) {
+            // Build our update transaction item.
+            const myTransactItem = this.toTransactUpdate();
+            // Combine with extra transaction items.
+            const allItems = [...this.extraTransactItems, myTransactItem];
+            await this.parent.getClient().transactWrite({
+                TransactItems: allItems
+            }).promise();
+            // After transaction, retrieve the updated item.
+            const result = await this.parent.get(this.key).execute();
+            if (result === null) {
+                throw new Error('Item not found after transaction update');
+            }
+            return result;
+        }
+        else {
+            // Normal update flow.
+            const { updateExpression, attributeNames, attributeValues } = this.buildExpression();
+            const params = {
+                TableName: this.parent.getTableName(),
+                Key: this.parent.buildKey(this.key),
+                UpdateExpression: updateExpression,
+                ExpressionAttributeNames: attributeNames,
+                ExpressionAttributeValues: attributeValues,
+                ReturnValues: 'ALL_NEW'
+            };
+            if (this.condition && this.condition.expression) {
+                params.ConditionExpression = this.condition.expression;
+            }
+            const result = await this.parent.getClient().update(params).promise();
+            if (!result.Attributes) {
+                throw new Error('No attributes returned after update');
+            }
+            return this.parent.getSchema().parse(result.Attributes);
+        }
+    }
+}
+exports.UpdateBuilder = UpdateBuilder;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "betterddb",
-  "version": "0.2.0",
+  "version": "0.4.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",