@aurios/mizzle 1.0.0

package/src/core/errors.ts

@@ -0,0 +1,34 @@
+/**
+ * Error thrown when a DynamoDB item exceeds the 400KB limit.
+ */
+export class ItemSizeExceededError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "ItemSizeExceededError";
+        
+        // This is necessary for some environments to correctly maintain the prototype chain
+        Object.setPrototypeOf(this, ItemSizeExceededError.prototype);
+    }
+}
+
+/**
+ * Detailed reason for a transaction cancellation.
+ */
+export interface CancellationReason {
+    index: number;
+    code: string;
+    message?: string;
+    item?: Record<string, any>;
+}
+
+/**
+ * Error thrown when a DynamoDB transaction is canceled.
+ */
+export class TransactionFailedError extends Error {
+    constructor(message: string, public readonly reasons: CancellationReason[]) {
+        super(message);
+        this.name = "TransactionFailedError";
+        
+        Object.setPrototypeOf(this, TransactionFailedError.prototype);
+    }
+}

package/src/core/introspection.ts

@@ -0,0 +1,73 @@
+import { DynamoDBClient, ListTablesCommand, DescribeTableCommand } from "@aws-sdk/client-dynamodb";
+import type { TableDescription } from "@aws-sdk/client-dynamodb";
+import type { MizzleSnapshot, TableSnapshot } from "./snapshot";
+
+export async function getRemoteSnapshot(client: DynamoDBClient): Promise<MizzleSnapshot> {
+    const tables: Record<string, TableSnapshot> = {};
+    
+    // List Tables
+    let lastEvaluatedTableName: string | undefined;
+    const tableNames: string[] = [];
+    do {
+        const response = await client.send(new ListTablesCommand({ ExclusiveStartTableName: lastEvaluatedTableName }));
+        if (response.TableNames) tableNames.push(...response.TableNames);
+        lastEvaluatedTableName = response.LastEvaluatedTableName;
+    } while (lastEvaluatedTableName);
+
+    // Describe each table
+    for (const tableName of tableNames) {
+        try {
+            const response = await client.send(new DescribeTableCommand({ TableName: tableName }));
+            if (response.Table) {
+                const snap = convertDescriptionToSnapshot(response.Table);
+                tables[tableName] = snap;
+            }
+        } catch (e) {
+            console.warn(`Failed to describe table ${tableName}:`, e);
+        }
+    }
+
+    return {
+        version: "remote",
+        tables
+    };
+}
+
+function convertDescriptionToSnapshot(desc: TableDescription): TableSnapshot {
+    // Map DescribeTableOutput to TableSnapshot
+    const result: TableSnapshot = {
+        TableName: desc.TableName!,
+        AttributeDefinitions: desc.AttributeDefinitions?.map(ad => ({
+            AttributeName: ad.AttributeName!,
+            AttributeType: ad.AttributeType!
+        })).sort((a, b) => a.AttributeName.localeCompare(b.AttributeName)) || [],
+        KeySchema: desc.KeySchema?.map(ks => ({
+            AttributeName: ks.AttributeName!,
+            KeyType: ks.KeyType as "HASH" | "RANGE"
+        })) || []
+    };
+
+    if (desc.GlobalSecondaryIndexes && desc.GlobalSecondaryIndexes.length > 0) {
+        result.GlobalSecondaryIndexes = desc.GlobalSecondaryIndexes.map(gsi => ({
+            IndexName: gsi.IndexName!,
+            KeySchema: gsi.KeySchema?.map(ks => ({
+                AttributeName: ks.AttributeName!,
+                KeyType: ks.KeyType as "HASH" | "RANGE"
+            })),
+            Projection: gsi.Projection ? { ProjectionType: gsi.Projection.ProjectionType } : undefined
+        })).sort((a, b) => a.IndexName.localeCompare(b.IndexName));
+    }
+
+    if (desc.LocalSecondaryIndexes && desc.LocalSecondaryIndexes.length > 0) {
+        result.LocalSecondaryIndexes = desc.LocalSecondaryIndexes.map(lsi => ({
+            IndexName: lsi.IndexName!,
+            KeySchema: lsi.KeySchema?.map(ks => ({
+                AttributeName: ks.AttributeName!,
+                KeyType: ks.KeyType as "HASH" | "RANGE"
+            })),
+            Projection: lsi.Projection ? { ProjectionType: lsi.Projection.ProjectionType } : undefined
+        })).sort((a, b) => a.IndexName.localeCompare(b.IndexName));
+    }
+
+    return result;
+}

package/src/core/operations.ts

@@ -0,0 +1,34 @@
+import type { Column, AnyColumn } from "./column";
+import type { PhysicalTable } from "./table";
+
+export type RequiredKeyOnly<
+    TKey extends string,
+    T extends Column,
+    TInferMode extends "select" | "insert" = "select",
+> = TInferMode extends "select"
+    ? never
+    : T extends AnyColumn<{
+            hasDefault: false;
+            notNull: true;
+        }>
+      ? TKey
+      : never;
+
+export type OpitionalKeyOnly<
+    TKey extends string,
+    T extends Column,
+    TInferMode extends "select" | "insert" = "select",
+> = TKey extends RequiredKeyOnly<TKey, T, TInferMode> ? never : TKey;
+
+export type SelectedFieldsFlat<TColumn extends Column> = Record<
+    string,
+    TColumn
+>;
+
+export type SelectedFields<
+    TColumn extends Column,
+    TTable extends PhysicalTable,
+> = Record<
+    string,
+    SelectedFieldsFlat<TColumn>[string] | TTable | SelectedFieldsFlat<TColumn>
+>;

package/src/core/parser.ts

@@ -0,0 +1,109 @@
+import { ENTITY_SYMBOLS, TABLE_SYMBOLS } from "@mizzle/shared";
+import type { InternalRelationalSchema } from "./relations";
+import { type KeyStrategy } from "./strategies";
+import { Entity } from "./table";
+import { Column } from "./column";
+
+/**
+ * Parser for DynamoDB item collections (Single-Table Design).
+ */
+export class ItemCollectionParser {
+    constructor(private schema: InternalRelationalSchema) {}
+
+    /**
+     * Parse a flat list of items into structured, nested objects.
+     */
+    parse(
+        items: Record<string, unknown>[],
+        rootEntityName: string,
+        relations: Record<string, boolean | object> = {},
+    ): Record<string, unknown>[] {
+        const rootEntityMeta = this.schema.entities[rootEntityName];
+        if (!rootEntityMeta) {
+            throw new Error(`Root entity ${rootEntityName} not found in schema`);
+        }
+
+        const primaryItems: Record<string, unknown>[] = [];
+        const otherItems: Record<string, unknown>[] = [];
+
+        // 1. Identify primary items vs related items
+        for (const item of items) {
+            if (this.isEntity(item, rootEntityMeta.entity)) {
+                primaryItems.push({ ...item });
+            } else {
+                otherItems.push(item);
+            }
+        }
+
+        // 2. For each primary item, find its relations
+        for (const primaryItem of primaryItems) {
+            for (const [relName, relOption] of Object.entries(relations)) {
+                if (!relOption) continue;
+
+                const relConfig = rootEntityMeta.relations[relName];
+                if (!relConfig) continue;
+
+                const targetEntity = relConfig.config.to;
+
+                // Find items that match the target entity type
+                // In Single-Table Design Query, these items usually share the same PK
+                const relatedItems = otherItems.filter((item) =>
+                    this.isEntity(item, targetEntity),
+                );
+
+                if (relatedItems.length > 0) {
+                    if (relConfig.type === "many") {
+                        primaryItem[relName] = relatedItems;
+                    } else if (relConfig.type === "one") {
+                        primaryItem[relName] = relatedItems[0] || null;
+                    }
+                }
+            }
+        }
+
+        return primaryItems;
+    }
+
+    /**
+     * Check if an item matches an entity definition based on its key strategies.
+     */
+    private isEntity(item: Record<string, unknown>, entity: Entity): boolean {
+        const strategies = entity[ENTITY_SYMBOLS.ENTITY_STRATEGY] as Record<
+            string,
+            KeyStrategy
+        >;
+        const physicalTable = entity[ENTITY_SYMBOLS.PHYSICAL_TABLE] as any;
+
+        const pkName = (physicalTable[TABLE_SYMBOLS.PARTITION_KEY] as Column).name;
+        const skName = (physicalTable[TABLE_SYMBOLS.SORT_KEY] as Column | undefined)
+            ?.name;
+
+        const pkMatch = this.matchStrategy(item[pkName], strategies.pk);
+        const skMatch = skName
+            ? this.matchStrategy(item[skName], strategies.sk)
+            : true;
+
+        return pkMatch && skMatch;
+    }
+
+    /**
+     * Check if a value matches a key strategy.
+     */
+    private matchStrategy(value: unknown, strategy?: KeyStrategy): boolean {
+        if (!strategy) return true;
+        if (value === undefined || value === null) return false;
+
+        const strValue = String(value);
+
+        if (strategy.type === "static") {
+            return strValue === strategy.segments[0];
+        }
+
+        if (strategy.type === "prefix" || strategy.type === "composite") {
+            const prefix = strategy.segments[0];
+            return typeof prefix === "string" && strValue.startsWith(prefix);
+        }
+
+        return false;
+    }
+}

package/src/core/relations.ts

@@ -0,0 +1,149 @@
+import { RELATION_SYMBOLS } from "@mizzle/shared";
+import { Entity } from "./table";
+import { Column } from "./column";
+
+/**
+ * Type of relationship.
+ */
+export type RelationType = "one" | "many";
+
+/**
+ * Configuration for a relationship.
+ */
+export interface RelationConfig {
+    /**
+     * The target entity of the relationship.
+     */
+    to: Entity;
+    /**
+     * Local columns that link to the target entity.
+     */
+    fields?: Column[];
+    /**
+     * Target columns that the local columns link to.
+     */
+    references?: Column[];
+    /**
+     * Optional name for the relation.
+     */
+    relationName?: string;
+}
+
+/**
+ * Represents a relationship between entities.
+ */
+export class Relation<TType extends RelationType = RelationType> {
+    constructor(
+        public type: TType,
+        public config: RelationConfig
+    ) {}
+}
+
+/**
+ * Definition of all relations for a single entity.
+ */
+export interface RelationsDefinition<TEntity extends Entity = Entity> {
+    /**
+     * The source entity.
+     */
+    entity: TEntity;
+    /**
+     * Map of relation names to their configurations.
+     */
+    config: Record<string, Relation>;
+}
+
+/**
+ * Callback function to define relations.
+ */
+export type RelationsCallback = (helpers: {
+    /**
+     * Define a one-to-one relationship.
+     */
+    one: (to: Entity, config?: Omit<RelationConfig, "to">) => Relation<"one">;
+    /**
+     * Define a one-to-many relationship.
+     */
+    many: (to: Entity, config?: Omit<RelationConfig, "to">) => Relation<"many">;
+}) => Record<string, Relation>;
+
+/**
+ * Define relations for an entity.
+ * 
+ * @example
+ * ```ts
+ * export const usersRelations = defineRelations(users, ({ many }) => ({
+ *   posts: many(posts),
+ * }));
+ * ```
+ */
+export function defineRelations<TEntity extends Entity>(
+    entity: TEntity,
+    relations: RelationsCallback
+): RelationsDefinition<TEntity> {
+    const config = relations({
+        one: (to, config) => new Relation("one", { to, ...config }),
+        many: (to, config) => new Relation("many", { to, ...config }),
+    });
+
+    return {
+        entity,
+        config,
+        [RELATION_SYMBOLS.RELATION_CONFIG]: true
+    } as unknown as RelationsDefinition<TEntity>;
+}
+
+/**
+ * Metadata for an entity and its relationships.
+ */
+export interface EntityMetadata {
+    entity: Entity;
+    relations: Record<string, Relation>;
+}
+
+/**
+ * Internal relational schema mapping entity names to their metadata.
+ */
+export interface InternalRelationalSchema {
+    entities: Record<string, EntityMetadata>;
+}
+
+/**
+ * Extract metadata from a flat schema definition.
+ */
+export function extractMetadata(schema: Record<string, unknown>): InternalRelationalSchema {
+    const metadata: InternalRelationalSchema = {
+        entities: {},
+    };
+
+    // First pass: identify entities
+    for (const [key, value] of Object.entries(schema)) {
+        if (value instanceof Entity) {
+            metadata.entities[key] = {
+                entity: value,
+                relations: {},
+            };
+        }
+    }
+
+    // Second pass: identify relations
+    for (const [, value] of Object.entries(schema)) {
+        if (value && (value as any)[RELATION_SYMBOLS.RELATION_CONFIG]) {
+            const definition = value as RelationsDefinition;
+            // Find the key for this entity in the metadata
+            const entityEntry = Object.entries(metadata.entities).find(
+                ([_, meta]) => meta.entity === definition.entity
+            );
+
+            if (entityEntry) {
+                const [, meta] = entityEntry;
+                meta.relations = {
+                    ...meta.relations,
+                    ...definition.config,
+                };
+            }
+        }
+    }
+
+    return metadata;
+}

package/src/core/retry.ts

@@ -0,0 +1,70 @@
+export interface RetryConfig {
+    /**
+     * Maximum number of attempts (including the initial one).
+     * @default 3
+     */
+    maxAttempts: number;
+    /**
+     * Base delay in milliseconds for exponential backoff.
+     * @default 100
+     */
+    baseDelay: number;
+}
+
+const RETRYABLE_ERRORS = new Set([
+    "ProvisionedThroughputExceededException",
+    "RequestLimitExceeded",
+    "InternalServerError",
+    "ServiceUnavailable",
+    "ThrottlingException",
+]);
+
+const RETRYABLE_STATUS_CODES = new Set([500, 503]);
+
+export class RetryHandler {
+    constructor(private config: RetryConfig) {}
+
+    async execute<T>(operation: () => Promise<T>): Promise<T> {
+        let lastError: unknown;
+        
+        for (let attempt = 1; attempt <= this.config.maxAttempts; attempt++) {
+            try {
+                return await operation();
+            } catch (error) {
+                lastError = error;
+                
+                if (attempt >= this.config.maxAttempts || !this.isRetryable(error)) {
+                    throw error;
+                }
+                
+                await this.delay(attempt - 1);
+            }
+        }
+        
+        throw lastError;
+    }
+
+    private isRetryable(error: any): boolean {
+        if (!error) return false;
+        
+        if (RETRYABLE_ERRORS.has(error.name)) {
+            return true;
+        }
+
+        if (error.$metadata?.httpStatusCode && RETRYABLE_STATUS_CODES.has(error.$metadata.httpStatusCode)) {
+            return true;
+        }
+
+        // AWS SDK v3 specific error structure sometimes wraps things
+        return false;
+    }
+
+    private async delay(retryCount: number): Promise<void> {
+        const base = this.config.baseDelay * Math.pow(2, retryCount);
+        const jitter = Math.random() * base; // Full jitter or equal jitter? Standard is random between 0 and base.
+        // Cap at some reasonable max if needed, but for now standard exponential + jitter
+        const delayTime = base + jitter;
+        
+        return new Promise(resolve => setTimeout(resolve, delayTime));
+    }
+}

package/src/core/snapshot.ts

@@ -0,0 +1,192 @@
+import { join } from "path";
+import { writeFile, readFile, mkdir, readdir } from "fs/promises";
+import { existsSync } from "fs";
+import { PhysicalTable, Entity } from "./table";
+import { TABLE_SYMBOLS, ENTITY_SYMBOLS } from "@mizzle/shared";
+import { Column } from "./column";
+import type {
+    AttributeDefinition,
+    KeySchemaElement,
+    GlobalSecondaryIndex,
+    LocalSecondaryIndex,
+} from "@aws-sdk/client-dynamodb";
+
+export interface TableSnapshot {
+    TableName: string;
+    AttributeDefinitions: AttributeDefinition[];
+    KeySchema: KeySchemaElement[];
+    GlobalSecondaryIndexes?: GlobalSecondaryIndex[];
+    LocalSecondaryIndexes?: LocalSecondaryIndex[];
+}
+
+export interface MizzleSnapshot {
+  version: string;
+  tables: Record<string, TableSnapshot>;
+}
+
+export interface SchemaCurrent {
+    tables: PhysicalTable[];
+    entities: Entity[];
+}
+
+const SNAPSHOT_FILENAME = "snapshot.json";
+
+export async function saveSnapshot(dir: string, snapshot: MizzleSnapshot): Promise<void> {
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true });
+  }
+  const filePath = join(dir, SNAPSHOT_FILENAME);
+  await writeFile(filePath, JSON.stringify(snapshot, null, 2), "utf-8");
+}
+
+export async function loadSnapshot(dir: string): Promise<MizzleSnapshot | null> {
+  const filePath = join(dir, SNAPSHOT_FILENAME);
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  const content = await readFile(filePath, "utf-8");
+  return JSON.parse(content) as MizzleSnapshot;
+}
+
+export function generateSnapshot(schema: SchemaCurrent): MizzleSnapshot {
+    const tables: Record<string, TableSnapshot> = {};
+    
+    for (const table of schema.tables) {
+        const associatedEntities = schema.entities.filter(e => e[ENTITY_SYMBOLS.PHYSICAL_TABLE] === table);
+        const tableSnapshot = physicalTableToSnapshot(table, associatedEntities);
+        tables[tableSnapshot.TableName] = tableSnapshot;
+    }
+    
+    return {
+        version: "1",
+        tables
+    };
+}
+
+export async function getNextMigrationVersion(migrationsDir: string): Promise<string> {
+    if (!existsSync(migrationsDir)) return "0000";
+    
+    const files = await readdir(migrationsDir);
+    let maxVersion = -1;
+    
+    for (const file of files) {
+        if (!file.endsWith(".ts")) continue;
+        const match = file.match(/^(\d{4})_/);
+        if (match) {
+            const version = parseInt(match[1]!, 10);
+            if (version > maxVersion) maxVersion = version;
+        }
+    }
+    
+    if (maxVersion === -1) return "0000";
+    return (maxVersion + 1).toString().padStart(4, "0");
+}
+
+function physicalTableToSnapshot(table: PhysicalTable, entities: Entity[]): TableSnapshot {
+    const tableName = table[TABLE_SYMBOLS.TABLE_NAME];
+    const attributeDefinitionsMap = new Map<string, string>(); // Name -> Type
+
+    // PK
+    const pk = table[TABLE_SYMBOLS.PARTITION_KEY] as Column;
+    attributeDefinitionsMap.set(pk.name, pk.getDynamoType());
+
+    // SK
+    const sk = table[TABLE_SYMBOLS.SORT_KEY] as Column | undefined;
+    if (sk) {
+        attributeDefinitionsMap.set(sk.name, sk.getDynamoType());
+    }
+
+    const keySchema: KeySchemaElement[] = [
+        { AttributeName: pk.name, KeyType: "HASH" }
+    ];
+    if (sk) {
+        keySchema.push({ AttributeName: sk.name, KeyType: "RANGE" });
+    }
+
+    const gsis: GlobalSecondaryIndex[] = [];
+    const lsis: LocalSecondaryIndex[] = [];
+
+    const indexes = table[TABLE_SYMBOLS.INDEXES] || {};
+    for (const [indexName, indexBuilder] of Object.entries(indexes)) {
+        const type = (indexBuilder as { type: string }).type;
+        const config = (indexBuilder as { config: { pk?: string; sk?: string } }).config;
+
+        if (type === 'gsi') {
+            if (config.pk) {
+                const pkType = resolveColumnType(config.pk, table, entities);
+                attributeDefinitionsMap.set(config.pk, pkType);
+            }
+            if (config.sk) {
+                const skType = resolveColumnType(config.sk, table, entities);
+                attributeDefinitionsMap.set(config.sk, skType);
+            }
+
+            const gsiDef: GlobalSecondaryIndex = {
+                IndexName: indexName,
+                KeySchema: [
+                    { AttributeName: config.pk!, KeyType: "HASH" }
+                ],
+                Projection: { ProjectionType: "ALL" }
+            };
+            if (config.sk) {
+                gsiDef.KeySchema!.push({ AttributeName: config.sk, KeyType: "RANGE" });
+            }
+            gsis.push(gsiDef);
+
+        } else if (type === 'lsi') {
+             if (config.sk) {
+                const skType = resolveColumnType(config.sk, table, entities);
+                attributeDefinitionsMap.set(config.sk, skType);
+            }
+
+             const lsiDef: LocalSecondaryIndex = {
+                IndexName: indexName,
+                KeySchema: [
+                    { AttributeName: pk.name, KeyType: "HASH" },
+                    { AttributeName: config.sk!, KeyType: "RANGE" }
+                ],
+                Projection: { ProjectionType: "ALL" }
+             };
+             lsis.push(lsiDef);
+        }
+    }
+
+    const attributeDefinitions = Array.from(attributeDefinitionsMap.entries()).map(([name, type]) => ({
+        AttributeName: name,
+        AttributeType: type as any
+    })).sort((a, b) => a.AttributeName.localeCompare(b.AttributeName));
+
+    gsis.sort((a, b) => (a.IndexName || "").localeCompare(b.IndexName || ""));
+    lsis.sort((a, b) => (a.IndexName || "").localeCompare(b.IndexName || ""));
+
+    const result: TableSnapshot = {
+        TableName: tableName as string,
+        AttributeDefinitions: attributeDefinitions,
+        KeySchema: keySchema,
+    };
+
+    if (gsis.length > 0) result.GlobalSecondaryIndexes = gsis;
+    if (lsis.length > 0) result.LocalSecondaryIndexes = lsis;
+
+    return result;
+}
+
+function resolveColumnType(columnName: string, table: PhysicalTable, entities: Entity[]): string {
+    const pk = table[TABLE_SYMBOLS.PARTITION_KEY] as Column;
+    if (pk.name === columnName) return pk.getDynamoType();
+    
+    const sk = table[TABLE_SYMBOLS.SORT_KEY] as Column | undefined;
+    if (sk && sk.name === columnName) return sk.getDynamoType();
+
+    for (const entity of entities) {
+        const columns = entity[ENTITY_SYMBOLS.COLUMNS] as Record<string, Column> | undefined;
+        if (columns) {
+            const col = columns[columnName];
+            if (col) {
+                return col.getDynamoType();
+            }
+        }
+    }
+
+    throw new Error(`Could not resolve type for column '${columnName}' in table '${table[TABLE_SYMBOLS.TABLE_NAME]}'. Ensure it is defined in an Entity.`);
+}