@aurios/mizzle 1.0.0

package/src/db.ts

@@ -0,0 +1,199 @@
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+import { InsertBuilder } from "./builders/insert";
+import { RelationnalQueryBuilder } from "./builders/relational-builder";
+import { SelectBuilder, type SelectedFields } from "./builders/select";
+import type { Entity, InferInsertModel, InferSelectModel } from "./core/table";
+import { UpdateBuilder } from "./builders/update";
+import { DeleteBuilder } from "./builders/delete";
+import { BatchGetBuilder } from "./builders/batch-get";
+import { BatchWriteBuilder, type BatchWriteOperation } from "./builders/batch-write";
+import { TransactionProxy } from "./builders/transaction";
+import { extractMetadata, type InternalRelationalSchema } from "./core/relations";
+import { RetryHandler, type RetryConfig } from "./core/retry";
+import { MizzleClient, type IMizzleClient } from "./core/client";
+
+export type QuerySchema<TSchema extends Record<string, unknown>> = {
+    [K in keyof TSchema as TSchema[K] extends Entity ? K : never]: RelationnalQueryBuilder<TSchema[K] extends Entity ? TSchema[K] : never>;
+};
+
+/**
+ * DynamoDB database instance.
+ */
+export class DynamoDB<TSchema extends Record<string, unknown> = Record<string, unknown>> {
+    private docClient: IMizzleClient;
+    private schema?: InternalRelationalSchema;
+    private retryConfig: RetryConfig;
+
+    /**
+     * Access relational queries for entities defined in the schema.
+     * 
+     * @example
+     * ```ts
+     * const users = await db.query.users.findMany();
+     * ```
+     */
+    public readonly query: QuerySchema<TSchema>;
+
+    constructor(client: DynamoDBClient, relations?: TSchema, retry?: Partial<RetryConfig>) {
+        this.retryConfig = {
+            maxAttempts: retry?.maxAttempts ?? 3,
+            baseDelay: retry?.baseDelay ?? 100,
+        };
+        this.docClient = new MizzleClient(
+            DynamoDBDocumentClient.from(client),
+            new RetryHandler(this.retryConfig)
+        );
+        
+        if (relations) {
+            this.schema = extractMetadata(relations);
+        }
+
+        this.query = new Proxy({} as QuerySchema<TSchema>, {
+            get: (_, prop) => {
+                if (typeof prop !== 'string') return undefined;
+
+                if (!this.schema) {
+                    throw new Error("No relations defined. Initialize mizzle with a relations object to use db.query.");
+                }
+
+                const entityMetadata = this.schema.entities[prop];
+                if (!entityMetadata) {
+                    throw new Error(`Entity ${prop} not found in relations schema.`);
+                }
+
+                return new RelationnalQueryBuilder(this.docClient, entityMetadata.entity, this.schema, prop);
+            }
+        });
+    }
+
+    /**
+     * Insert a new record into the database.
+     */
+    insert<T extends Entity>(table: T): InsertBuilder<T> {
+        return new InsertBuilder(table, this.docClient);
+    }
+
+    /**
+     * Select records from the database.
+     */
+    select<TSelection extends SelectedFields>(
+        fields?: TSelection,
+    ): SelectBuilder<TSelection | undefined> {
+        return new SelectBuilder(this.docClient, fields);
+    }
+
+    /**
+     * Batch get items from the database.
+     */
+    batchGet<T extends Entity>(
+        entity: T,
+        keys: Partial<InferSelectModel<T>>[],
+    ) {
+        return new BatchGetBuilder(this.docClient).items(entity, keys);
+    }
+
+    /**
+     * Batch write items to the database.
+     */
+    batchWrite<T extends Entity>(
+        entity: T,
+        operations: BatchWriteOperation<T>[],
+    ) {
+        return new BatchWriteBuilder(this.docClient).operations(entity, operations);
+    }
+
+    /**
+     * Start a relational query manually for a specific entity.
+     * @internal
+     */
+    _query<T extends Entity>(table: T) {
+        return new RelationnalQueryBuilder<T>(this.docClient, table);
+    }
+
+    /**
+     * Update existing records in the database.
+     */
+    update<T extends Entity>(table: T): UpdateBuilder<T> {
+        return new UpdateBuilder(table, this.docClient);
+    }
+
+    /**
+     * Delete records from the database.
+     */
+    delete<T extends Entity>(
+        table: T,
+        keys: Partial<InferInsertModel<T>>,
+    ): DeleteBuilder<T> {
+        return new DeleteBuilder(table, this.docClient, keys as Record<string, unknown>);
+    }
+
+    /**
+     * Execute multiple operations atomically in a transaction.
+     * 
+     * @param token ClientRequestToken for idempotency.
+     * @param callback Callback that returns an array of operations.
+     */
+    async transaction(
+        token: string,
+        callback: (tx: TransactionProxy) => any[] | Promise<any[]>
+    ): Promise<void> {
+        const proxy = new TransactionProxy(this.docClient);
+        const operations = await callback(proxy);
+        
+        if (operations.length === 0) return;
+        if (operations.length > 100) {
+            throw new Error("DynamoDB transactions are limited to 100 items.");
+        }
+
+        // Executor will be implemented in transaction.ts
+        const { TransactionExecutor } = await import("./builders/transaction");
+        const executor = new TransactionExecutor(this.docClient);
+        await executor.execute(token, operations);
+    }
+}
+
+/**
+ * Configuration for initializing Mizzle.
+ */
+export interface MizzleConfig<TSchema extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * AWS DynamoDB Client.
+     */
+    client: DynamoDBClient;
+    /**
+     * Relational schema definition.
+     */
+    relations?: TSchema;
+    /**
+     * Retry configuration for transient errors.
+     */
+    retry?: Partial<RetryConfig>;
+}
+
+/**
+ * Initialize Mizzle with a DynamoDB client or a configuration object.
+ * 
+ * @example
+ * ```ts
+ * const db = mizzle(client);
+ * // or
+ * const db = mizzle({ client, relations });
+ * ```
+ */
+export function mizzle<TSchema extends Record<string, unknown> = Record<string, unknown>>(
+    config: DynamoDBClient | MizzleConfig<TSchema>
+): DynamoDB<TSchema> {
+    if (config instanceof DynamoDBClient) {
+        return new DynamoDB(config);
+    }
+    
+    if ("client" in config && config.client instanceof DynamoDBClient) {
+        return new DynamoDB(config.client, config.relations, config.retry);
+    }
+    // Fallback for cases where instanceof might fail due to multiple SDK versions
+    if ("client" in config && config.client) {
+        return new DynamoDB(config.client as DynamoDBClient, config.relations, config.retry);
+    }
+    return new DynamoDB(config as unknown as DynamoDBClient);
+}

package/src/expressions/actions.ts

@@ -0,0 +1,66 @@
+export type ActionType = "SET" | "ADD" | "REMOVE" | "DELETE";
+
+export abstract class UpdateAction {
+    abstract readonly action: ActionType;
+}
+
+export class SetAction extends UpdateAction {
+    readonly action = "SET";
+    constructor(
+        readonly value: unknown,
+        readonly functionName?: "list_append" | "if_not_exists",
+        readonly usePathAsFirstArg: boolean = false
+    ) {
+        super();
+    }
+}
+
+export class AddAction extends UpdateAction {
+    readonly action = "ADD";
+    constructor(readonly value: unknown) {
+        super();
+    }
+}
+
+export class RemoveAction extends UpdateAction {
+    readonly action = "REMOVE";
+}
+
+export class DeleteAction extends UpdateAction {
+    readonly action = "DELETE";
+    constructor(readonly value: unknown) {
+        super();
+    }
+}
+
+export function add(value: number | Set<unknown>) {
+    return new AddAction(value);
+}
+
+/**
+ * Maps to list_append(path, :value)
+ */
+export function append(value: unknown[]) {
+    return new SetAction(value, "list_append", true);
+}
+
+/**
+ * Maps to if_not_exists(path, :value)
+ */
+export function ifNotExists(value: unknown) {
+    return new SetAction(value, "if_not_exists", true);
+}
+
+export function remove() {
+    return new RemoveAction();
+}
+
+export function addToSet(values: Set<unknown> | unknown[]) {
+    const value = Array.isArray(values) ? new Set(values) : values;
+    return new AddAction(value);
+}
+
+export function deleteFromSet(values: Set<unknown> | unknown[]) {
+    const value = Array.isArray(values) ? new Set(values) : values;
+    return new DeleteAction(value);
+}

package/src/expressions/builder.ts

@@ -0,0 +1,77 @@
+import {
+    type Expression,
+    BinaryExpression,
+    LogicalExpression,
+    FunctionExpression,
+} from "./operators";
+
+/**
+ * Recursively builds a DynamoDB expression string from an Expression object.
+ * 
+ * @param cond The expression object to build.
+ * @param addName A callback to add an attribute name and return its placeholder.
+ * @param addValue A callback to add an attribute value and return its placeholder.
+ * @param excludeColumns Optional set of physical column names to exclude from the expression.
+ * @returns A string suitable for use in ConditionExpression or FilterExpression.
+ */
+export function buildExpression(
+    cond: Expression,
+    addName: (name: string) => string,
+    addValue: (value: unknown) => string,
+    excludeColumns?: Set<string>,
+): string | undefined {
+    if (cond instanceof LogicalExpression) {
+        const parts = cond.conditions
+            .map((c) => buildExpression(c, addName, addValue, excludeColumns))
+            .filter((p): p is string => p !== undefined && p !== "");
+        
+        if (parts.length === 0) return undefined;
+        if (parts.length === 1) return parts[0];
+        return `(${parts.join(` ${cond.operator} `)})`;
+    }
+
+    if (cond instanceof BinaryExpression) {
+        if (excludeColumns?.has(cond.column.name)) {
+            return undefined;
+        }
+        const colName = addName(cond.column.name);
+        const mapValue = (v: unknown) => typeof (cond.column as any).mapToDynamoValue === "function" 
+            ? (cond.column as any).mapToDynamoValue(v) 
+            : v;
+
+        if (cond.operator === "between") {
+            const valArray = cond.value as unknown[];
+            const valKey1 = addValue(mapValue(valArray[0]));
+            const valKey2 = addValue(mapValue(valArray[1]));
+            return `${colName} BETWEEN ${valKey1} AND ${valKey2}`;
+        }
+
+        if (cond.operator === "in") {
+            const valArray = cond.value as unknown[];
+            const valKeys = valArray.map((val) => addValue(mapValue(val)));
+            return `${colName} IN (${valKeys.join(", ")})`;
+        }
+
+        const valKey = addValue(mapValue(cond.value));
+        return `${colName} ${cond.operator} ${valKey}`;
+    }
+
+    if (cond instanceof FunctionExpression) {
+        if (excludeColumns?.has(cond.column.name)) {
+            return undefined;
+        }
+        const colName = addName(cond.column.name);
+        const mapValue = (v: unknown) => typeof (cond.column as any).mapToDynamoValue === "function" 
+            ? (cond.column as any).mapToDynamoValue(v) 
+            : v;
+
+        if (cond.operator === "attribute_exists") {
+            return `attribute_exists(${colName})`;
+        }
+
+        const valKey = addValue(mapValue(cond.value));
+        return `${cond.operator}(${colName}, ${valKey})`;
+    }
+
+    return undefined;
+}

package/src/expressions/operators.ts

@@ -0,0 +1,108 @@
+import { Column } from "../core/column";
+
+type BinaryOperators = "=" | "<" | "<=" | ">=" | ">" | "between" | "in";
+type LogicalOperators = "AND" | "OR";
+type FunctionOperators = "begins_with" | "contains" | "attribute_exists";
+
+export abstract class Expression {
+    abstract readonly type: "binary" | "logical" | "function";
+}
+
+export class BinaryExpression extends Expression {
+    readonly type = "binary";
+    constructor(
+        readonly column: Column,
+        readonly operator: BinaryOperators,
+        readonly value: unknown,
+    ) {
+        super();
+    }
+}
+
+export class LogicalExpression extends Expression {
+    readonly type = "logical";
+    constructor(
+        readonly conditions: Expression[],
+        readonly operator: LogicalOperators,
+    ) {
+        super();
+    }
+}
+
+export class FunctionExpression extends Expression {
+    readonly type = "function";
+    constructor(
+        readonly column: Column,
+        readonly operator: FunctionOperators,
+        readonly value: unknown,
+    ) {
+        super();
+    }
+}
+
+export function eq(column: Column, value: unknown) {
+    return new BinaryExpression(column, "=", value);
+}
+
+export function gt(column: Column, value: unknown) {
+    return new BinaryExpression(column, ">", value);
+}
+
+export function gte(column: Column, value: unknown) {
+    return new BinaryExpression(column, ">=", value);
+}
+
+export function lt(column: Column, value: unknown) {
+    return new BinaryExpression(column, "<", value);
+}
+
+export function lte(column: Column, value: unknown) {
+    return new BinaryExpression(column, "<=", value);
+}
+
+export function between(column: Column, values: [unknown, unknown]) {
+    return new BinaryExpression(column, "between", values);
+}
+
+export function inList(column: Column, values: unknown[]) {
+    return new BinaryExpression(column, "in", values);
+}
+
+export function beginsWith(column: Column, value: string) {
+    return new FunctionExpression(column, "begins_with", value);
+}
+
+export function contains(column: Column, value: unknown) {
+    return new FunctionExpression(column, "contains", value);
+}
+
+export function attributeExists(column: Column) {
+    return new FunctionExpression(column, "attribute_exists", undefined);
+}
+
+export function or(...conditions: Expression[]) {
+    return new LogicalExpression(conditions, "OR");
+}
+
+export function and(...conditions: Expression[]) {
+    return new LogicalExpression(conditions, "AND");
+}
+
+export const operators = {
+    eq,
+    gt,
+    gte,
+    lt,
+    lte,
+    between,
+    in: inList,
+    and,
+    or,
+    contains,
+    beginsWith,
+    attributeExists,
+};
+
+export type Operators = typeof operators;
+
+export type Condition = Expression;

package/src/expressions/update-builder.ts

@@ -0,0 +1,98 @@
+import { type Column } from "../core/column";
+import { UpdateAction } from "./actions";
+
+export interface UpdateState {
+    set: Record<string, { value: unknown; functionName?: string; usePathAsFirstArg?: boolean }>;
+    add: Record<string, unknown>;
+    remove: string[];
+    delete: Record<string, unknown>;
+}
+
+export function createUpdateState(): UpdateState {
+    return {
+        set: {},
+        add: {},
+        remove: [],
+        delete: {},
+    };
+}
+
+export function partitionUpdateValues(
+    values: Record<string, unknown | UpdateAction>,
+    state: UpdateState,
+    columns?: Record<string, Column>
+): void {
+    for (const [key, val] of Object.entries(values)) {
+        const col = columns?.[key];
+        const mapValue = (v: unknown) => (col && typeof (col as any).mapToDynamoValue === "function")
+            ? (col as any).mapToDynamoValue(v) 
+            : v;
+
+        if (val instanceof UpdateAction) {
+            switch (val.action) {
+                case "SET":
+                    state.set[key] = {
+                        value: mapValue((val as any).value),
+                        functionName: (val as any).functionName,
+                        usePathAsFirstArg: (val as any).usePathAsFirstArg,
+                    };
+                    break;
+                case "ADD":
+                    state.add[key] = mapValue((val as any).value);
+                    break;
+                case "REMOVE":
+                    state.remove.push(key);
+                    break;
+                case "DELETE":
+                    state.delete[key] = mapValue((val as any).value);
+                    break;
+            }
+        } else if (val !== undefined) {
+            state.set[key] = { value: mapValue(val) };
+        }
+    }
+}
+
+export function buildUpdateExpressionString(
+    state: UpdateState,
+    addName: (name: string) => string,
+    addValue: (value: unknown) => string
+): string {
+    const sections: string[] = [];
+
+    if (Object.keys(state.set).length > 0) {
+        const parts = Object.entries(state.set).map(([key, config]) => {
+            const name = addName(key);
+            const value = addValue(config.value);
+            if (config.functionName) {
+                if (config.usePathAsFirstArg) {
+                    return `${name} = ${config.functionName}(${name}, ${value})`;
+                }
+                return `${name} = ${config.functionName}(${value})`;
+            }
+            return `${name} = ${value}`;
+        });
+        sections.push(`SET ${parts.join(", ")}`);
+    }
+
+    if (Object.keys(state.add).length > 0) {
+        const parts = Object.entries(state.add).map(([key, val]) => {
+            return `${addName(key)} ${addValue(val)}`;
+        });
+        sections.push(`ADD ${parts.join(", ")}`);
+    }
+
+    if (state.remove.length > 0) {
+        const parts = state.remove.map((key) => addName(key));
+        sections.push(`REMOVE ${parts.join(", ")}`);
+    }
+
+    if (Object.keys(state.delete).length > 0) {
+        const parts = Object.entries(state.delete).map(([key, val]) => {
+            return `${addName(key)} ${addValue(val)}`;
+        });
+        sections.push(`DELETE ${parts.join(", ")}`);
+    }
+
+    return sections.join(" ");
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export * from "@mizzle/shared";
+export * from "./expressions/operators";
+export * from "./expressions/builder";
+export * from "./expressions/actions";
+export * from "./builders/insert";
+export * from "./builders/select";
+export * from "./builders/update";
+export * from "./builders/delete";
+export * from "./builders/transaction";
+export * from "./builders/batch-get";
+export * from "./builders/batch-write";
+export * from "./builders/relational-builder";
+export * from "./core/table";
+export * from "./core/strategies";
+export * from "./core/relations";
+export * from "./core/retry";
+export * from "./core/errors";
+export * from "./columns";
+export * from "./db";
+export * from "./indexes";

package/src/indexes.ts

@@ -0,0 +1,19 @@
+export interface IndexColumnConfig {
+    pk?: string;
+    sk?: string;
+}
+
+export class IndexBuilder {
+    constructor(
+        public type: "gsi" | "lsi",
+        public config: IndexColumnConfig,
+    ) {}
+}
+
+export function gsi(pkColumn: string, skColumn?: string) {
+    return new IndexBuilder("gsi", { pk: pkColumn, sk: skColumn });
+}
+
+export function lsi(skColumn: string) {
+    return new IndexBuilder("lsi", { sk: skColumn });
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@mizzle/tsconfig/base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "baseUrl": ".",
+    "paths": {
+      "@mizzle/shared": ["../shared/src/index.ts"]
+    }
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+    columns: 'src/columns/index.ts',
+    table: 'src/core/table.ts',
+    snapshot: 'src/core/snapshot.ts',
+    diff: 'src/core/diff.ts',
+    introspection: 'src/core/introspection.ts',
+    db: 'src/db.ts',
+  },
+  format: 'esm',
+  dts: true,
+  clean: true,
+  noExternal: ['@mizzle/shared'],
+  external: [/^@aws-sdk\//, 'uuid'],
+  minify: true,
+  splitting: true,
+});