@aurios/mizzle 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# mizzle
+
+## 1.0.1
+
+### Patch Changes
+
+- fix: resolve schema discovery issues in monorepos and stabilize test suite.
+
+## 1.0.0
+
+### Major Changes
+
+- Initial production release of Mizzle ORM and Mizzling CLI.
+  Includes:
+  - Fluent Query Builder (Select, Insert, Update, Delete)
+  - Native Date Support with ISO 8601 storage
+  - Relational Queries with Single-Table optimization
+  - Atomic Transactions support
+  - Migration CLI with schema discovery and push/pull
+  - High-performance tsup-based bundling

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@aurios/mizzle",
+  "version": "1.0.0",
+  "private": false,
+  "description": "a drizzle-like orm for dynamoDB",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./columns": {
+      "types": "./dist/columns.d.ts",
+      "import": "./dist/columns.js"
+    },
+    "./table": {
+      "types": "./dist/table.d.ts",
+      "import": "./dist/table.js"
+    },
+    "./snapshot": {
+      "types": "./dist/snapshot.d.ts",
+      "import": "./dist/snapshot.js"
+    },
+    "./diff": {
+      "types": "./dist/diff.d.ts",
+      "import": "./dist/diff.js"
+    },
+    "./introspection": {
+      "types": "./dist/introspection.d.ts",
+      "import": "./dist/introspection.js"
+    },
+    "./db": {
+      "types": "./dist/db.d.ts",
+      "import": "./dist/db.js"
+    }
+  },
+  "author": {
+    "name": "Lucas",
+    "url": "https://github.com/realfakenerd"
+  },
+  "repository": {
+    "url": "https://github.com/realfakenerd/mizzle"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "tsup",
+    "lint": "eslint \"src/**/*.ts\""
+  },
+  "dependencies": {
+    "@aws-sdk/client-dynamodb": "3.962.0",
+    "@aws-sdk/lib-dynamodb": "3.962.0"
+  },
+  "devDependencies": {
+    "@mizzle/eslint-config": "workspace:*",
+    "@mizzle/shared": "workspace:*",
+    "@mizzle/tsconfig": "workspace:*",
+    "tsup": "^8.5.1"
+  }
+}

package/src/builders/base.ts

@@ -0,0 +1,71 @@
+import { type IMizzleClient } from "../core/client";
+import { Entity } from "../core/table";
+import { QueryPromise } from "./query-promise";
+import { resolveTableName, mapToLogical } from "@mizzle/shared";
+import { resolveStrategies, type StrategyResolution } from "../core/strategies";
+import { type Expression } from "../expressions/operators";
+import { ENTITY_SYMBOLS } from "@mizzle/shared";
+
+export abstract class BaseBuilder<
+    TEntity extends Entity,
+    TResult,
+> extends QueryPromise<TResult> {
+    constructor(
+        protected readonly entity: TEntity,
+        protected readonly client: IMizzleClient,
+    ) {
+        super();
+    }
+
+    public get tableName(): string {
+        return resolveTableName(this.entity as any);
+    }
+
+    protected get physicalTable() {
+        return this.entity[ENTITY_SYMBOLS.PHYSICAL_TABLE];
+    }
+
+    protected resolveKeys(
+        whereClause?: Expression,
+        providedValues?: Record<string, unknown>,
+        indexName?: string,
+    ): StrategyResolution {
+        return resolveStrategies(this.entity, whereClause, providedValues, indexName);
+    }
+
+    protected createExpressionContext(prefix = "") {
+        const expressionAttributeNames: Record<string, string> = {};
+        const expressionAttributeValues: Record<string, unknown> = {};
+        let nameCount = 0;
+        let valueCount = 0;
+
+        const addName = (name: string) => {
+            const segments = name.split(".");
+            const placeholders = segments.map(segment => {
+                // Check if we already mapped this name segment to avoid redundancy?
+                // Actually, simple counter is fine for now and safer against collisions.
+                const placeholder = `#${prefix}n${nameCount++}`;
+                expressionAttributeNames[placeholder] = segment;
+                return placeholder;
+            });
+            return placeholders.join(".");
+        };
+
+        const addValue = (value: unknown) => {
+            const placeholder = `:${prefix}v${valueCount++}`;
+            expressionAttributeValues[placeholder] = value;
+            return placeholder;
+        };
+
+        return {
+            expressionAttributeNames,
+            expressionAttributeValues,
+            addName,
+            addValue,
+        };
+    }
+
+    protected mapToLogical(item: Record<string, unknown>): Record<string, unknown> {
+        return mapToLogical(this.entity, item);
+    }
+}

package/src/builders/batch-get.ts

@@ -0,0 +1,76 @@
+import { BatchGetCommand } from "@aws-sdk/lib-dynamodb";
+import { ENTITY_SYMBOLS, TABLE_SYMBOLS } from "@mizzle/shared";
+import { Entity, type InferSelectModel } from "../core/table";
+import { BaseBuilder } from "./base";
+import type { IMizzleClient } from "../core/client";
+
+export class BatchGetBuilder {
+    constructor(private client: IMizzleClient) {}
+
+    items<TEntity extends Entity>(entity: TEntity, keys: Partial<InferSelectModel<TEntity>>[]) {
+        return new BatchGetBase(entity, this.client, keys);
+    }
+}
+
+export interface BatchGetResult<T> {
+    succeeded: T[];
+    failed: Partial<T>[];
+}
+
+export class BatchGetBase<
+    TEntity extends Entity,
+    TResult = InferSelectModel<TEntity>,
+> extends BaseBuilder<TEntity, BatchGetResult<TResult>> {
+    static readonly [ENTITY_SYMBOLS.ENTITY_KIND]: string = "BatchGetBase";
+
+    constructor(
+        entity: TEntity,
+        client: IMizzleClient,
+        private keysData: Partial<InferSelectModel<TEntity>>[],
+    ) {
+        super(entity, client);
+    }
+
+    public override async execute(): Promise<BatchGetResult<TResult>> {
+        const succeeded: TResult[] = [];
+        const failed: Record<string, unknown>[] = [];
+
+        // Group keys by resolved DynamoDB keys
+        let currentKeys = this.keysData.map(k => this.resolveKeys(undefined, k as Record<string, unknown>).keys);
+        
+        let attempts = 0;
+        const maxBatchAttempts = 5; // Internal limit for unprocessed retries
+
+        while (currentKeys.length > 0 && attempts < maxBatchAttempts) {
+            attempts++;
+            
+            const command = new BatchGetCommand({
+                RequestItems: {
+                    [this.tableName]: {
+                        Keys: currentKeys
+                    }
+                }
+            });
+
+            const response = await this.client.send(command);
+            
+            if (response.Responses?.[this.tableName]) {
+                succeeded.push(...(response.Responses[this.tableName] as TResult[]));
+            }
+
+            const unprocessed = response.UnprocessedKeys?.[this.tableName]?.Keys;
+            
+            if (unprocessed && unprocessed.length > 0) {
+                currentKeys = unprocessed as Record<string, unknown>[];
+            } else {
+                currentKeys = [];
+            }
+        }
+
+        if (currentKeys.length > 0) {
+            failed.push(...currentKeys);
+        }
+
+        return { succeeded, failed: failed as any[] };
+    }
+}

package/src/builders/batch-write.ts

@@ -0,0 +1,98 @@
+import { BatchWriteCommand } from "@aws-sdk/lib-dynamodb";
+import { ENTITY_SYMBOLS, TABLE_SYMBOLS } from "@mizzle/shared";
+import { Entity, type InferInsertModel } from "../core/table";
+import { BaseBuilder } from "./base";
+import type { IMizzleClient } from "../core/client";
+import { calculateItemSize } from "../core/validation";
+import { ItemSizeExceededError } from "../core/errors";
+
+export type BatchWriteOperation<TEntity extends Entity> = 
+    | { type: "put", item: InferInsertModel<TEntity> }
+    | { type: "delete", keys: Partial<InferInsertModel<TEntity>> };
+
+export interface BatchWriteResult<T> {
+    succeededCount: number;
+    failed: any[]; // Operations that failed after all retries
+}
+
+export class BatchWriteBuilder {
+    constructor(private client: IMizzleClient) {}
+
+    operations<TEntity extends Entity>(entity: TEntity, ops: BatchWriteOperation<TEntity>[]) {
+        return new BatchWriteBase(entity, this.client, ops);
+    }
+}
+
+export class BatchWriteBase<
+    TEntity extends Entity,
+> extends BaseBuilder<TEntity, BatchWriteResult<InferInsertModel<TEntity>>> {
+    static readonly [ENTITY_SYMBOLS.ENTITY_KIND]: string = "BatchWriteBase";
+
+    constructor(
+        entity: TEntity,
+        client: IMizzleClient,
+        private ops: BatchWriteOperation<TEntity>[],
+    ) {
+        super(entity, client);
+    }
+
+    public override async execute(): Promise<BatchWriteResult<InferInsertModel<TEntity>>> {
+        let succeededCount = 0;
+        let failed: any[] = [];
+
+        const requests = this.ops.map(op => {
+            if (op.type === "put") {
+                const item = op.item as Record<string, unknown>;
+                
+                // Size validation
+                const size = calculateItemSize(item);
+                if (size > 400 * 1024) {
+                    throw new ItemSizeExceededError(`Item in batch exceeds the 400KB limit.`);
+                }
+
+                return {
+                    PutRequest: {
+                        Item: item
+                    }
+                };
+            } else {
+                return {
+                    DeleteRequest: {
+                        Key: op.keys as Record<string, unknown>
+                    }
+                };
+            }
+        });
+
+        let currentRequests = [...requests];
+        let attempts = 0;
+        const maxBatchAttempts = 5;
+
+        while (currentRequests.length > 0 && attempts < maxBatchAttempts) {
+            attempts++;
+            
+            const command = new BatchWriteCommand({
+                RequestItems: {
+                    [this.tableName]: currentRequests
+                }
+            });
+
+            const response = await this.client.send(command);
+            
+            const unprocessed = response.UnprocessedItems?.[this.tableName] || [];
+            succeededCount += (currentRequests.length - unprocessed.length);
+
+            if (unprocessed.length > 0) {
+                currentRequests = unprocessed;
+            } else {
+                currentRequests = [];
+            }
+        }
+
+        if (currentRequests.length > 0) {
+            failed = currentRequests;
+        }
+
+        return { succeededCount, failed };
+    }
+}

package/src/builders/delete.ts

@@ -0,0 +1,61 @@
+import { DeleteCommand } from "@aws-sdk/lib-dynamodb";
+import { ENTITY_SYMBOLS } from "@mizzle/shared";
+import { Entity, type InferSelectModel } from "../core/table";
+import { BaseBuilder } from "./base";
+import { type IMizzleClient } from "../core/client";
+import { type Expression } from "../expressions/operators";
+
+export class DeleteBuilder<
+    TEntity extends Entity,
+    TResult = InferSelectModel<TEntity>,
+> extends BaseBuilder<TEntity, TResult> {
+    static readonly [ENTITY_SYMBOLS.ENTITY_KIND]: string = "DeleteBuilder";
+
+    private _returnValues?: "NONE" | "ALL_OLD";
+    private _keys: Record<string, unknown>;
+
+    constructor(
+        entity: TEntity,
+        client: IMizzleClient,
+        keys: Record<string, unknown>,
+    ) {
+        super(entity, client);
+        this._keys = keys;
+    }
+
+    returning(): this {
+        this._returnValues = "ALL_OLD";
+        return this;
+    }
+
+    /** @internal */
+    get keys() {
+        return this._keys;
+    }
+
+    /** @internal */
+    public override resolveKeys(
+        whereClause?: Expression,
+        providedValues?: Record<string, unknown>,
+    ) {
+        return super.resolveKeys(whereClause, providedValues);
+    }
+
+    /** @internal */
+    public override createExpressionContext(prefix = "") {
+        return super.createExpressionContext(prefix);
+    }
+
+    public override async execute(): Promise<TResult> {
+        const resolution = this.resolveKeys(undefined, this._keys);
+
+        const command = new DeleteCommand({
+            TableName: this.tableName,
+            Key: resolution.keys,
+            ReturnValues: this._returnValues,
+        });
+
+        const response = await this.client.send(command);
+        return response.Attributes as TResult;
+    }
+}

package/src/builders/insert.ts

@@ -0,0 +1,156 @@
+import { PutCommand } from "@aws-sdk/lib-dynamodb";
+import { ENTITY_SYMBOLS, TABLE_SYMBOLS } from "@mizzle/shared";
+import { Entity, type InferInsertModel } from "../core/table";
+import { BaseBuilder } from "./base";
+import { Column } from "../core/column";
+import type { KeyStrategy } from "../core/strategies";
+import { type IMizzleClient } from "../core/client";
+import { calculateItemSize } from "../core/validation";
+import { ItemSizeExceededError } from "../core/errors";
+
+export class InsertBuilder<TEntity extends Entity> {
+    static readonly [ENTITY_SYMBOLS.ENTITY_KIND]: string = "InsertBuilder";
+
+    constructor(
+        private entity: TEntity,
+        private client: IMizzleClient,
+    ) {}
+
+    values(values: InferInsertModel<TEntity>): InsertBase<TEntity> {
+        return new InsertBase(this.entity, this.client, values);
+    }
+}
+
+export class InsertBase<
+    TEntity extends Entity,
+    TResult = undefined,
+> extends BaseBuilder<TEntity, TResult> {
+    static readonly [ENTITY_SYMBOLS.ENTITY_KIND]: string = "InsertBase";
+
+    private shouldReturnValues = false;
+
+    constructor(
+        entity: TEntity,
+        client: IMizzleClient,
+        private valuesData: InferInsertModel<TEntity>,
+    ) {
+        super(entity, client);
+    }
+
+    /** @internal */
+    get values() {
+        return this.valuesData;
+    }
+
+    returning(): InsertBase<TEntity, InferInsertModel<TEntity>> {
+        this.shouldReturnValues = true;
+        return this as unknown as InsertBase<TEntity, InferInsertModel<TEntity>>;
+    }
+
+    /** @internal */
+    buildItem(): Record<string, unknown> {
+        const itemToSave = this.processValues(this.valuesData);
+        const resolution = this.resolveKeys(undefined, itemToSave);
+        
+        const finalItem: Record<string, unknown> = { ...itemToSave, ...resolution.keys };
+
+        // Also resolve GSI keys if they are defined in strategies but not in resolution.keys
+        const strategies = this.entity[ENTITY_SYMBOLS.ENTITY_STRATEGY] as unknown as Record<string, { pk: KeyStrategy, sk?: KeyStrategy }>;
+        const physicalTable = this.entity[ENTITY_SYMBOLS.PHYSICAL_TABLE];
+        const indexes = (physicalTable as any)?.[TABLE_SYMBOLS.INDEXES] || {};
+
+        for (const [indexName, strategy] of Object.entries(strategies)) {
+            if (indexName === "pk" || indexName === "sk") continue;
+
+            const indexBuilder = indexes[indexName] as { config: { pk: string; sk?: string } } | undefined;
+            if (indexBuilder) {
+                if (strategy.pk && indexBuilder.config.pk) {
+                    const pkValue = this.resolveStrategyValue(strategy.pk, itemToSave);
+                    if (pkValue) finalItem[indexBuilder.config.pk] = pkValue;
+                }
+                if (strategy.sk && indexBuilder.config.sk) {
+                    const skValue = this.resolveStrategyValue(strategy.sk, itemToSave);
+                    if (skValue) finalItem[indexBuilder.config.sk] = skValue;
+                }
+            }
+        }
+
+        return finalItem;
+    }
+
+    override async execute(): Promise<TResult> {
+        const finalItem = this.buildItem();
+
+        // Size validation
+        const size = calculateItemSize(finalItem);
+        if (size > 400 * 1024) {
+            throw new ItemSizeExceededError(`Item size of ${Math.round(size / 1024)}KB exceeds the 400KB limit.`);
+        }
+
+        const command = new PutCommand({
+            TableName: this.tableName,
+            Item: finalItem,
+        });
+
+        await this.client.send(command);
+        if (this.shouldReturnValues) return finalItem as unknown as TResult;
+
+        return undefined as unknown as TResult;
+    }
+
+    private resolveStrategyValue(strategy: KeyStrategy, availableValues: Record<string, unknown>): string | undefined {
+        if (strategy.type === "static") {
+            return strategy.segments[0] as string;
+        }
+
+        const resolvedParts: string[] = [];
+
+        for (const segment of strategy.segments) {
+            if (typeof segment === "string") {
+                resolvedParts.push(segment);
+            } else {
+                const val = availableValues[segment.name];
+                if (val === undefined || val === null) return undefined;
+                resolvedParts.push(String(val));
+            }
+        }
+
+        if (strategy.type === "prefix") return resolvedParts.join("");
+        if (strategy.type === "composite") return resolvedParts.join(strategy.separator || "#");
+        return undefined;
+    }
+
+    private processValues(
+        values: InferInsertModel<TEntity>,
+    ): Record<string, unknown> {
+        const item: Record<string, unknown> = { ...(values as Record<string, unknown>) };
+        const columns = this.entity[ENTITY_SYMBOLS.COLUMNS] as Record<string, Column>;
+
+        for (const key in columns) {
+            const col = columns[key];
+            if (!col) continue;
+
+            const value = item[key];
+
+            if (value === undefined) {
+                if (col.default !== undefined) item[key] = col.default;
+                else if (col.defaultFn) item[key] = col.defaultFn();
+            }
+
+            const finalValue = item[key];
+            item[key] = typeof (col as any).mapToDynamoValue === "function" 
+                ? (col as any).mapToDynamoValue(finalValue) 
+                : finalValue;
+
+            if (["SS", "NS", "BS"].includes(col.columnType)) {
+                if (Array.isArray(finalValue)) {
+                    const setVal = new Set(finalValue);
+                    item[key] = setVal;
+                    if (setVal.size === 0) delete item[key];
+                }
+            }
+        }
+
+        return item;
+    }
+}

package/src/builders/query-promise.ts

@@ -0,0 +1,41 @@
+export abstract class QueryPromise<T> implements Promise<T> {
+    [Symbol.toStringTag] = "QueryPromise";
+
+    catch<TResult = never>(
+        onrejected?:
+            | ((reason: unknown) => TResult | PromiseLike<TResult>)
+            | null
+            | undefined,
+    ): Promise<T | TResult> {
+        return this.then(undefined, onrejected);
+    }
+
+    finally(onfinally?: (() => void) | null | undefined): Promise<T> {
+        return this.then(
+            (value) => {
+                onfinally?.();
+                return value;
+            },
+            (reason) => {
+                onfinally?.();
+                throw reason;
+            },
+        );
+    }
+
+    // oxlint-disable
+    then<TResult1 = T, TResult2 = never>(
+        onfulfilled?:
+            | ((value: T) => TResult1 | PromiseLike<TResult1>)
+            | null
+            | undefined,
+        onrejected?:
+            | ((reason: unknown) => TResult2 | PromiseLike<TResult2>)
+            | null
+            | undefined,
+    ): Promise<TResult1 | TResult2> {
+        return this.execute().then(onfulfilled, onrejected);
+    }
+
+    abstract execute(): Promise<T>;
+}