@aurios/mizzle 1.0.0

package/src/builders/relational-builder.ts

@@ -0,0 +1,211 @@
+import { SelectBase } from './select';
+import { operators, type Operators, eq, and } from '../expressions/operators';
+import { type Condition, Expression } from '../expressions/operators';
+import type { Entity, InferSelectedModel } from '../core/table';
+import { ItemCollectionParser } from '../core/parser';
+import type { InternalRelationalSchema } from '../core/relations';
+import { resolveStrategies } from '../core/strategies';
+import { TABLE_SYMBOLS, ENTITY_SYMBOLS, mapToLogical } from "@mizzle/shared";
+import { Column } from '../core/column';
+import { type IMizzleClient } from '../core/client';
+
+type WhereCallback<T extends Entity> = (
+        fields: T['_']['columns'],
+        ops: Operators
+) => Condition;
+
+/**
+ * Options for selecting related entities.
+ */
+export type IncludeOptions = boolean | {
+        where?: Condition;
+        limit?: number;
+        with?: Record<string, IncludeOptions>;
+        include?: Record<string, IncludeOptions>;
+};
+
+/**
+ * Options for a relational query.
+ */
+export type RelationalQueryOptions<T extends Entity> = {
+        where?: Condition | WhereCallback<T>;
+        limit?: number;
+        orderBy?: 'asc' | 'desc';
+        /**
+         * Select relationships to include (Drizzle-style).
+         */
+        with?: Record<string, IncludeOptions>;
+        /**
+         * Select relationships to include (Prisma-style).
+         */
+        include?: Record<string, IncludeOptions>;
+};
+
+export type InferRelationalModel<
+    T extends Entity,
+    TOptions extends RelationalQueryOptions<T> = Record<string, never>
+> = InferSelectedModel<T> & {
+    [K in keyof TOptions['with'] & string]: unknown; 
+} & {
+    [K in keyof TOptions['include'] & string]: unknown;
+};
+
+export class RelationnalQueryBuilder<T extends Entity> {
+        constructor(
+                private client: IMizzleClient,
+                private table: T,
+                private schema?: InternalRelationalSchema,
+                private entityName?: string
+        ) {}
+
+        async findFirst<TOptions extends RelationalQueryOptions<T>>(
+                options: TOptions = {} as TOptions
+        ): Promise<InferRelationalModel<T, TOptions> | undefined> {
+                const results = await this.findMany({ ...options, limit: 1 });
+                return results[0];
+        }
+
+        async findMany<TOptions extends RelationalQueryOptions<T>>(
+        options: TOptions = {} as TOptions
+    ): Promise<InferRelationalModel<T, TOptions>[]> {
+                const qb = new SelectBase<T, undefined>(this.table, this.client, undefined);
+
+                if (options.orderBy) {
+                        qb.sort(options.orderBy === 'asc');
+                }
+
+                let condition: Condition | undefined;
+
+                if (options.where) {
+                        const columns = (this.table._?.columns || (this.table as unknown as Record<string, Column>)) as Record<string, Column>;
+                        if (typeof options.where === 'function') {
+                                condition = (options.where as WhereCallback<T>)(columns as any, operators);
+                        } else {
+                                condition = options.where as Condition;
+                        }
+                }
+
+                let results: Record<string, unknown>[];
+
+                // Single-Table Optimization (Direct PK)
+                const resolution = resolveStrategies(this.table, condition);
+
+                if (this.schema && this.entityName && (options.with || options.include) && resolution.hasPartitionKey && !resolution.indexName) {
+                        const physicalTable = this.table[ENTITY_SYMBOLS.PHYSICAL_TABLE];
+                        // If we are here, we should have a physical table
+                        if (!physicalTable) throw new Error("Physical table not found for entity");
+                        
+                        const pkPhysicalName = ((physicalTable as any)[TABLE_SYMBOLS.PARTITION_KEY] as Column).name;
+                        
+                        const pkValue = resolution.keys[pkPhysicalName];
+
+                        // Override where to ONLY use the PK to get related items in the same collection
+                        qb.where(eq({ name: pkPhysicalName } as Column, pkValue));
+
+                        const rawItems = await qb;
+                        
+                        // Map physical attributes back to logical names for the parser
+                        // We need a helper since we are not inheriting from BaseBuilder here
+                        const logicalItems = rawItems.map(item => mapToLogical(this.table, item));
+
+                        const parser = new ItemCollectionParser(this.schema);
+                        results = parser.parse(logicalItems as any, this.entityName, (options.with || options.include) as Record<string, boolean | object>);
+
+                        if (options.limit) {
+                                results = results.slice(0, options.limit);
+                        }
+                } else {
+                        if (options.limit) {
+                                qb.limit(options.limit);
+                        }
+                        if (condition) {
+                                qb.where(condition);
+                        }
+                        results = await qb;
+                }
+
+                // Recursive relation fetching
+                if (this.schema && this.entityName && (options.with || options.include)) {
+                        const relationsToFetch = (options.with || options.include) as Record<string, IncludeOptions>;
+                        
+                        await Promise.all(results.map(async (result) => {
+                                for (const [relName, relOptions] of Object.entries(relationsToFetch)) {
+                                        const entityConfig = this.schema!.entities[this.entityName!];
+                                        if (!entityConfig) continue;
+
+                                        const relation = entityConfig.relations[relName];
+                                        if (!relation) continue;
+
+                                        // If already populated AND no nested relations requested, skip.
+                                        // This preserves items from ItemCollectionParser (Single-Table optimization).
+                                        const isAlreadyPopulated = result[relName] !== undefined;
+                                        const hasNestedRelations = typeof relOptions === 'object' && (relOptions.with || relOptions.include);
+                                        
+                                        if (isAlreadyPopulated && !hasNestedRelations) continue;
+
+                                        const targetEntity = relation.config.to;
+                                        const targetEntityName = Object.entries(this.schema!.entities).find(([_, m]) => m.entity === targetEntity)?.[0];
+
+                                        // Map result to logical names for target strategy resolution
+                                        const logicalValues = mapToLogical(this.table, result);
+
+                                        let finalLogicalValues = logicalValues;
+                                        if (relation.config.fields && relation.config.references) {
+                                                const mappedValues: Record<string, unknown> = {};
+                                                relation.config.fields.forEach((fieldCol, idx) => {
+                                                        const refCol = relation.config.references![idx];
+                                                        if (!refCol) return;
+
+                                                        const targetLogicalEntry = Object.entries(targetEntity[ENTITY_SYMBOLS.COLUMNS] as Record<string, Column>)
+                                                                .find(([_, c]) => c === refCol || c.name === refCol.name);
+                                                        
+                                                        const targetLogicalName = targetLogicalEntry?.[0];
+                                                        
+                                                        if (targetLogicalName) {
+                                                                const sourceLogicalName = Object.entries(this.table[ENTITY_SYMBOLS.COLUMNS] as Record<string, Column>)
+                                                                        .find(([_, c]) => c === fieldCol || c.name === fieldCol.name)?.[0];
+                                                                
+                                                                const val = sourceLogicalName ? (result[sourceLogicalName] ?? result[fieldCol.name]) : result[fieldCol.name];
+                                                                if (val !== undefined) {
+                                                                        mappedValues[targetLogicalName] = val;
+                                                                }
+                                                        }
+                                                });
+                                                finalLogicalValues = mappedValues;
+                                        }
+
+                                        // Build keys for Query/GetItem based on parent item's data
+                                        const targetRes = resolveStrategies(targetEntity, undefined, finalLogicalValues);
+                                        if (targetRes.hasPartitionKey) {
+                                                const targetQb = new RelationnalQueryBuilder(this.client, targetEntity, this.schema, targetEntityName);
+                                                
+                                                // Construct where clause from resolved keys using physical names directly
+                                                const whereParts: Expression[] = [];
+                                                for (const [physName, value] of Object.entries(targetRes.keys)) {
+                                                        whereParts.push(eq({ name: physName } as Column, value));
+                                                }
+                                                
+                                                if (whereParts.length > 0) {
+                                                        const finalWhere = whereParts.length === 1 ? whereParts[0] : and(...whereParts);
+                                                        const nextOptions = typeof relOptions === 'object' ? relOptions : {};
+
+                                                        if (relation.type === 'one') {
+                                                                result[relName] = await targetQb.findFirst({ ...nextOptions, where: finalWhere });
+                                                        } else {
+                                                                // Overwrite for 'many' to ensure we get nested relations if requested.
+                                                                // Optimization: only overwrite if we really need to (e.g. cross-partition).
+                                                                result[relName] = await targetQb.findMany({ ...nextOptions, where: finalWhere });
+                                                        }
+                                                }
+                                        }
+                                }
+                        }));
+                }
+
+                                return results as InferRelationalModel<T, TOptions>[];
+
+                        }
+
+                }
+
+                

package/src/builders/select.ts

@@ -0,0 +1,196 @@
+import {
+    GetCommand,
+    QueryCommand,
+    ScanCommand,
+} from "@aws-sdk/lib-dynamodb";
+import { ENTITY_SYMBOLS, TABLE_SYMBOLS } from "@mizzle/shared";
+import { Column } from "../core/column";
+import type { SelectedFields as SelectedFieldsBase } from "../core/operations";
+import { 
+    type Expression,
+} from "../expressions/operators";
+import { Entity, type InferSelectModel, type PhysicalTable } from "../core/table";
+import { BaseBuilder } from "./base";
+import type { StrategyResolution } from "../core/strategies";
+import type { IMizzleClient } from "../core/client";
+import { buildExpression } from "../expressions/builder";
+
+export type SelectedFields = SelectedFieldsBase<Column, PhysicalTable>;
+
+export class SelectBuilder<TSelection extends SelectedFields | undefined> {
+    constructor(
+        private client: IMizzleClient,
+        private fields?: TSelection,
+    ) {}
+
+    from<TEntity extends Entity>(entity: TEntity) {
+        return new SelectBase(entity, this.client, this.fields);
+    }
+}
+
+export class SelectBase<
+    TEntity extends Entity,
+    TSelection extends SelectedFields | undefined = undefined,
+    TResult = TSelection extends undefined ? InferSelectModel<TEntity> : Record<string, unknown>,
+> extends BaseBuilder<TEntity, TResult[]> {
+    static readonly [ENTITY_SYMBOLS.ENTITY_KIND]: string = "SelectBase";
+
+    private _whereClause?: Expression;
+    private _limitVal?: number;
+    private _pageSizeVal?: number;
+    private _consistentReadVal?: boolean;
+    private _sortForward: boolean = true;
+    private _forcedIndexName?: string;
+
+    constructor(
+        entity: TEntity,
+        client: IMizzleClient,
+        private fields?: TSelection,
+    ) {
+        super(entity, client);
+    }
+
+    where(expression: Expression): this {
+        this._whereClause = expression;
+        return this;
+    }
+
+    limit(val: number): this {
+        this._limitVal = val;
+        return this;
+    }
+
+    pageSize(val: number): this {
+        this._pageSizeVal = val;
+        return this;
+    }
+
+    consistentRead(enabled: boolean = true): this {
+        this._consistentReadVal = enabled;
+        return this;
+    }
+
+    sort(forward: boolean): this {
+        this._sortForward = forward;
+        return this;
+    }
+
+    index(name: string): this {
+        this._forcedIndexName = name;
+        return this;
+    }
+
+    iterator(): AsyncIterableIterator<TResult> {
+        const self = this;
+        return (async function* () {
+            let count = 0;
+            let lastEvaluatedKey: Record<string, any> | undefined = undefined;
+
+            do {
+                const result = await self.fetchPage(lastEvaluatedKey);
+                
+                for (const item of result.items) {
+                    yield item;
+                    count++;
+                    if (self._limitVal !== undefined && count >= self._limitVal) {
+                        return;
+                    }
+                }
+
+                lastEvaluatedKey = result.lastEvaluatedKey;
+            } while (lastEvaluatedKey);
+        })();
+    }
+
+    private async fetchPage(exclusiveStartKey?: Record<string, any>): Promise<{ items: TResult[], lastEvaluatedKey?: Record<string, any> }> {
+        const resolution = this.resolveKeys(this._whereClause, undefined, this._forcedIndexName);
+
+        if (resolution.hasPartitionKey && resolution.hasSortKey && !resolution.indexName && !exclusiveStartKey) {
+            const items = await this.executeGet(resolution.keys);
+            return { items };
+        } else if (resolution.hasPartitionKey || resolution.indexName) {
+            return await this.executeQuery(resolution, exclusiveStartKey);
+        } else {
+            return await this.executeScan(exclusiveStartKey);
+        }
+    }
+
+    override async execute(): Promise<TResult[]> {
+        const { items } = await this.fetchPage();
+        return items;
+    }
+
+    private async executeGet(keys: Record<string, unknown>): Promise<TResult[]> {
+        const command = new GetCommand({
+            TableName: this.tableName,
+            Key: keys,
+            ConsistentRead: this._consistentReadVal,
+        });
+
+        const result = await this.client.send(command);
+        return result.Item ? ([this.mapToLogical(result.Item)] as TResult[]) : [];
+    }
+
+    private async executeQuery(
+        resolution: StrategyResolution,
+        exclusiveStartKey?: Record<string, any>,
+    ): Promise<{ items: TResult[], lastEvaluatedKey?: Record<string, any> }> {
+        const { expressionAttributeNames, expressionAttributeValues, addName, addValue } = this.createExpressionContext();
+
+        const keyParts: string[] = [];
+        const keyAttrNames = new Set<string>();
+        for (const [key, value] of Object.entries(resolution.keys)) {
+            keyParts.push(`${addName(key)} = ${addValue(value)}`);
+            keyAttrNames.add(key);
+        }
+        const keyConditionExpression = keyParts.join(" AND ");
+        
+        // DynamoDB does NOT allow primary key attributes in FilterExpression
+        const filterExpression = this._whereClause 
+            ? buildExpression(this._whereClause, addName, addValue, keyAttrNames)
+            : undefined;
+
+        const command = new QueryCommand({
+            TableName: this.tableName,
+            IndexName: resolution.indexName,
+            KeyConditionExpression: keyConditionExpression,
+            FilterExpression: filterExpression || undefined,
+            ExpressionAttributeNames: Object.keys(expressionAttributeNames).length > 0 ? expressionAttributeNames : undefined,
+            ExpressionAttributeValues: Object.keys(expressionAttributeValues).length > 0 ? expressionAttributeValues : undefined,
+            Limit: this._pageSizeVal ?? this._limitVal,
+            ScanIndexForward: this._sortForward,
+            ConsistentRead: resolution.indexName ? undefined : this._consistentReadVal,
+            ExclusiveStartKey: exclusiveStartKey,
+        });
+
+        const response = await this.client.send(command);
+        return {
+            items: (response.Items || []).map((item: any) => this.mapToLogical(item)) as TResult[],
+            lastEvaluatedKey: response.LastEvaluatedKey,
+        };
+    }
+
+    private async executeScan(exclusiveStartKey?: Record<string, any>): Promise<{ items: TResult[], lastEvaluatedKey?: Record<string, any> }> {
+        const { expressionAttributeNames, expressionAttributeValues, addName, addValue } = this.createExpressionContext();
+
+        const filterExpression = this._whereClause 
+            ? buildExpression(this._whereClause, addName, addValue)
+            : undefined;
+
+        const command = new ScanCommand({
+            TableName: this.tableName,
+            FilterExpression: filterExpression,
+            ExpressionAttributeNames: Object.keys(expressionAttributeNames).length > 0 ? expressionAttributeNames : undefined,
+            ExpressionAttributeValues: Object.keys(expressionAttributeValues).length > 0 ? expressionAttributeValues : undefined,
+            Limit: this._pageSizeVal ?? this._limitVal,
+            ConsistentRead: this._consistentReadVal,
+            ExclusiveStartKey: exclusiveStartKey,
+        });
+
+        const response = await this.client.send(command);
+        return {
+            items: (response.Items || []).map((item: any) => this.mapToLogical(item)) as TResult[],
+            lastEvaluatedKey: response.LastEvaluatedKey,
+        };
+    }
+}

package/src/builders/transaction.ts

@@ -0,0 +1,170 @@
+import { TransactWriteCommand } from "@aws-sdk/lib-dynamodb";
+import { Entity } from "../core/table";
+import { InsertBuilder, InsertBase } from "./insert";
+import { UpdateBuilder } from "./update";
+import { DeleteBuilder } from "./delete";
+import { Expression } from "../expressions/operators";
+import { BaseBuilder } from "./base";
+import type { IMizzleClient } from "../core/client";
+import { ENTITY_SYMBOLS, TABLE_SYMBOLS } from "@mizzle/shared";
+import { buildExpression } from "../expressions/builder";
+import { buildUpdateExpressionString } from "../expressions/update-builder";
+import { TransactionFailedError } from "../core/errors";
+
+export class ConditionCheckBuilder<TEntity extends Entity> extends BaseBuilder<TEntity, void> {
+    static readonly [ENTITY_SYMBOLS.ENTITY_KIND]: string = "ConditionCheckBuilder";
+
+    private _whereClause?: Expression;
+
+    constructor(entity: TEntity, client: IMizzleClient) {
+        super(entity, client);
+    }
+
+    where(expression: Expression): this {
+        this._whereClause = expression;
+        return this;
+    }
+
+    public override async execute(): Promise<void> {
+        throw new Error("ConditionCheckBuilder cannot be executed directly. Use it within a transaction.");
+    }
+
+    /** @internal */
+    get whereClause() {
+        return this._whereClause;
+    }
+
+    /** @internal */
+    public override createExpressionContext(prefix = "") {
+        return super.createExpressionContext(prefix);
+    }
+
+    /** @internal */
+    public override resolveKeys(
+        whereClause?: Expression,
+        providedValues?: Record<string, unknown>,
+    ) {
+        return super.resolveKeys(whereClause, providedValues);
+    }
+}
+
+export class TransactionProxy {
+    constructor(private client: IMizzleClient) {}
+
+    insert<TEntity extends Entity>(entity: TEntity): InsertBuilder<TEntity> {
+        return new InsertBuilder(entity, this.client);
+    }
+
+    update<TEntity extends Entity>(entity: TEntity): UpdateBuilder<TEntity> {
+        return new UpdateBuilder(entity, this.client);
+    }
+
+    delete<TEntity extends Entity>(entity: TEntity, keys: Record<string, unknown>): DeleteBuilder<TEntity> {
+        return new DeleteBuilder(entity, this.client, keys);
+    }
+
+    conditionCheck<TEntity extends Entity>(entity: TEntity): ConditionCheckBuilder<TEntity> {
+        return new ConditionCheckBuilder(entity, this.client);
+    }
+}
+
+export class TransactionExecutor {
+    constructor(private client: IMizzleClient) {}
+
+    async execute(token: string, operations: any[]): Promise<void> {
+        const transactItems = operations.map(op => this.mapToTransactItem(op));
+
+        const command = new TransactWriteCommand({
+            TransactItems: transactItems,
+            ClientRequestToken: token,
+        });
+
+        try {
+            await this.client.send(command);
+        } catch (error: any) {
+            if (error.name === "TransactionCanceledException" || error.__type?.includes("TransactionCanceledException")) {
+                const reasons = (error.CancellationReasons || []).map((reason: any, index: number) => ({
+                    index,
+                    code: reason.Code,
+                    message: reason.Message,
+                    item: reason.Item
+                })).filter((reason: any) => reason.code !== "None");
+                
+                throw new TransactionFailedError("Transaction canceled by server.", reasons);
+            }
+            throw error;
+        }
+    }
+
+    private mapToTransactItem(builder: any): any {
+        const kind = builder.constructor[ENTITY_SYMBOLS.ENTITY_KIND];
+
+        switch (kind) {
+            case "InsertBase":
+                return { Put: this.mapPut(builder) };
+            case "UpdateBuilder":
+                return { Update: this.mapUpdate(builder) };
+            case "DeleteBuilder":
+                return { Delete: this.mapDelete(builder) };
+            case "ConditionCheckBuilder":
+                return { ConditionCheck: this.mapConditionCheck(builder) };
+            default:
+                throw new Error(`Unsupported transaction operation: ${kind}`);
+        }
+    }
+
+    private mapPut(builder: InsertBase<any, any>): any {
+        const finalItem = builder.buildItem();
+
+        return {
+            TableName: builder.tableName,
+            Item: finalItem,
+        };
+    }
+
+    private mapUpdate(builder: UpdateBuilder<any, any>): any {
+        const { expressionAttributeNames, expressionAttributeValues, addName, addValue } = builder.createExpressionContext("up_");
+        const updateExpression = buildUpdateExpressionString(builder.state, addName, addValue);
+        
+        let conditionExpression: string | undefined;
+        if (builder.whereClause) {
+            conditionExpression = buildExpression(builder.whereClause, addName, addValue);
+        }
+
+        return {
+            TableName: builder.tableName,
+            Key: builder.resolveUpdateKeys(),
+            UpdateExpression: updateExpression,
+            ConditionExpression: conditionExpression,
+            ExpressionAttributeNames: Object.keys(expressionAttributeNames).length > 0 ? expressionAttributeNames : undefined,
+            ExpressionAttributeValues: Object.keys(expressionAttributeValues).length > 0 ? expressionAttributeValues : undefined,
+        };
+    }
+
+    private mapDelete(builder: DeleteBuilder<any, any>): any {
+        const resolution = builder.resolveKeys(undefined, builder.keys);
+        return {
+            TableName: builder.tableName,
+            Key: resolution.keys,
+        };
+    }
+
+    private mapConditionCheck(builder: ConditionCheckBuilder<any>): any {
+        const { expressionAttributeNames, expressionAttributeValues, addName, addValue } = builder.createExpressionContext("cc_");
+        
+        const resolution = builder.resolveKeys(builder.whereClause);
+        
+        let conditionExpression: string | undefined;
+        if (builder.whereClause) {
+            conditionExpression = buildExpression(builder.whereClause, addName, addValue);
+        }
+
+        return {
+            TableName: builder.tableName,
+            Key: resolution.keys,
+            ConditionExpression: conditionExpression,
+            ExpressionAttributeNames: Object.keys(expressionAttributeNames).length > 0 ? expressionAttributeNames : undefined,
+            ExpressionAttributeValues: Object.keys(expressionAttributeValues).length > 0 ? expressionAttributeValues : undefined,
+        };
+    }
+}