@aurios/mizzle 1.0.0

package/src/core/strategies.ts

@@ -0,0 +1,271 @@
+import { ENTITY_SYMBOLS, TABLE_SYMBOLS } from "@mizzle/shared";
+import { Column } from "./column";
+import {
+    BinaryExpression,
+    LogicalExpression,
+    type Expression,
+} from "../expressions/operators";
+import { Entity } from "./table";
+
+export type KeyStrategyType = "static" | "prefix" | "composite";
+
+export interface KeyStrategy {
+    type: KeyStrategyType;
+    segments: (string | Column)[];
+    separator?: string;
+}
+
+/**
+ * SK = "METADATA"
+ */
+export function staticKey(value: string): KeyStrategy {
+    return { type: "static", segments: [value] };
+}
+
+/**
+ * PK = "USER#" + id
+ */
+export function prefixKey(prefix: string, column: Column): KeyStrategy {
+    return { type: "prefix", segments: [prefix, column] };
+}
+
+/**
+ * SK = "ORDER#" + date + "#STATUS#" + status
+ */
+export function compositeKey(
+    separator: string,
+    ...segments: (string | Column)[]
+): KeyStrategy {
+    return { type: "composite", separator, segments };
+}
+
+function extracValuesFromExpression(
+    expression: Expression,
+    acc: Record<string, unknown>
+): void {
+    if (expression instanceof BinaryExpression) {
+        if (expression.operator === "=") {
+            acc[expression.column.name] = expression.value;
+        }
+    } else if (expression instanceof LogicalExpression) {
+        if (expression.operator === "AND") {
+            for (const condition of expression.conditions) {
+                extracValuesFromExpression(condition, acc);
+            }
+        }
+    }
+}
+
+function resolveKeyStrategy(
+    strategy: KeyStrategy,
+    availableValues: Record<string, unknown>,
+): string | undefined {
+    if (strategy.type === "static") {
+        return strategy.segments[0] as string;
+    }
+
+    if (strategy.segments.length === 0) return undefined;
+
+    if (strategy.type === "prefix" && strategy.segments.length === 2 && typeof strategy.segments[0] === "string" && strategy.segments[1] instanceof Column) {
+        const prefix = strategy.segments[0];
+        const col = strategy.segments[1];
+        const val = availableValues[col.name];
+        if (val === undefined || val === null) return undefined;
+        const strVal = String(val);
+        if (strVal.startsWith(prefix)) return strVal;
+        return prefix + strVal;
+    }
+
+    const resolvedParts: string[] = [];
+
+    for (const segment of strategy.segments) {
+        if (typeof segment === "string") {
+            resolvedParts.push(segment);
+        } else if (segment instanceof Column) {
+            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;
+}
+
+export interface StrategyResolution {
+    keys: Record<string, unknown>;
+    hasPartitionKey: boolean;
+    hasSortKey: boolean;
+    indexName?: string;
+}
+
+export function resolveStrategies(
+    entity: Entity,
+    whereClause?: Expression,
+    providedValues?: Record<string, unknown>,
+    forcedIndexName?: string
+): StrategyResolution {
+    const strategies = entity[ENTITY_SYMBOLS.ENTITY_STRATEGY] as unknown as Record<string, any>;
+    const physicalTable = entity[ENTITY_SYMBOLS.PHYSICAL_TABLE] as any;
+
+    const pkCol = physicalTable[TABLE_SYMBOLS.PARTITION_KEY] as Column;
+    const skCol = physicalTable[TABLE_SYMBOLS.SORT_KEY] as Column | undefined;
+
+    const availableValues: Record<string, unknown> = {};
+    const columns = entity[ENTITY_SYMBOLS.COLUMNS] as Record<string, Column>;
+
+    if (providedValues) {
+        for (const [key, val] of Object.entries(providedValues)) {
+            if (columns[key]) {
+                availableValues[key] = val;
+            } else {
+                const logicalEntry = Object.entries(columns).find(([_, c]) => c.name === key);
+                if (logicalEntry) {
+                    availableValues[logicalEntry[0]] = val;
+                } else {
+                    availableValues[key] = val;
+                }
+            }
+        }
+    }
+    
+    if (whereClause) {
+        extracValuesFromExpression(whereClause, availableValues);
+    }
+
+    const result: StrategyResolution = {
+        keys: {},
+        hasPartitionKey: false,
+        hasSortKey: false,
+    };
+
+    if (forcedIndexName) {
+        const indexes = physicalTable[TABLE_SYMBOLS.INDEXES];
+        const indexBuilder = indexes?.[forcedIndexName] as { config: { pk: string; sk?: string } } | undefined;
+        const indexStrategy = strategies[forcedIndexName];
+
+        if (indexBuilder && indexStrategy) {
+            // Check if availableValues already contains the PHYSICAL key
+            if (availableValues[indexBuilder.config.pk] !== undefined) {
+                result.indexName = forcedIndexName;
+                result.keys[indexBuilder.config.pk] = availableValues[indexBuilder.config.pk];
+                result.hasPartitionKey = true;
+                if (indexBuilder.config.sk && availableValues[indexBuilder.config.sk] !== undefined) {
+                    result.keys[indexBuilder.config.sk] = availableValues[indexBuilder.config.sk];
+                    result.hasSortKey = true;
+                }
+                return result;
+            }
+
+            const indexPkValue = resolveKeyStrategy(indexStrategy.pk, availableValues);
+            if (indexPkValue) {
+                result.indexName = forcedIndexName;
+                result.keys[indexBuilder.config.pk] = indexPkValue;
+                result.hasPartitionKey = true;
+
+                const indexSkValue = indexStrategy.sk ? resolveKeyStrategy(indexStrategy.sk, availableValues) : undefined;
+                if (indexSkValue && indexBuilder.config.sk) {
+                    result.keys[indexBuilder.config.sk] = indexSkValue;
+                    result.hasSortKey = true;
+                }
+                return result;
+            }
+        }
+    }
+
+    // Check for PHYSICAL keys directly first
+    if (availableValues[pkCol.name] !== undefined) {
+        result.keys[pkCol.name] = availableValues[pkCol.name];
+        result.hasPartitionKey = true;
+        if (skCol && availableValues[skCol.name] !== undefined) {
+            result.keys[skCol.name] = availableValues[skCol.name];
+            result.hasSortKey = true;
+        } else if (!skCol) {
+            result.hasSortKey = true;
+        }
+        if (result.hasPartitionKey) return result;
+    }
+
+    if (strategies.pk) {
+        const pkValue = resolveKeyStrategy(strategies.pk, availableValues);
+        if (pkValue) {
+            result.keys[pkCol.name] = pkValue;
+            result.hasPartitionKey = true;
+        }
+    }
+
+    if (strategies.sk) {
+        const skValue = resolveKeyStrategy(strategies.sk, availableValues);
+        if (skValue) {
+            if (skCol) {
+                result.keys[skCol.name] = skValue;
+                result.hasSortKey = true;
+            }
+        }
+    } else {
+        result.hasSortKey = skCol ? false : true;
+    }
+
+    if (!result.hasPartitionKey) {
+        const indexes = physicalTable[TABLE_SYMBOLS.INDEXES];
+        if (indexes) {
+            for (const [indexName, indexBuilderBase] of Object.entries(indexes)) {
+                const indexBuilder = indexBuilderBase as { config: { pk: string; sk?: string } };
+                const indexStrategy = strategies[indexName];
+                if (!indexStrategy) continue;
+                
+                if (availableValues[indexBuilder.config.pk] !== undefined) {
+                    result.indexName = indexName;
+                    result.keys = {};
+                    result.keys[indexBuilder.config.pk] = availableValues[indexBuilder.config.pk];
+                    result.hasPartitionKey = true;
+                    if (indexBuilder.config.sk && availableValues[indexBuilder.config.sk] !== undefined) {
+                        result.keys[indexBuilder.config.sk] = availableValues[indexBuilder.config.sk];
+                        result.hasSortKey = true;
+                    }
+                    break;
+                }
+
+                if (indexStrategy.pk && indexBuilder.config.pk) {
+                    const indexPkValue = resolveKeyStrategy(
+                        indexStrategy.pk,
+                        availableValues,
+                    );
+
+                    if (indexPkValue) {
+                        result.indexName = indexName;
+
+                        result.keys = {};
+                        result.keys[indexBuilder.config.pk] = indexPkValue;
+                        result.hasPartitionKey = true;
+
+                        if (indexStrategy.sk && indexBuilder.config.sk) {
+                            const indexSkValue = resolveKeyStrategy(
+                                indexStrategy.sk,
+                                availableValues,
+                            );
+                            if (indexSkValue) {
+                                result.keys[indexBuilder.config.sk] =
+                                    indexSkValue;
+                                result.hasSortKey = true;
+                            }
+                        }
+                        break;
+                    }
+                }
+            }
+        }
+    }
+
+    return result;
+}

package/src/core/table.ts

@@ -0,0 +1,260 @@
+import { ENTITY_SYMBOLS, INFER_MODE, TABLE_SYMBOLS } from "@mizzle/shared";
+import type { Simplify, Update } from "@mizzle/shared";
+import { Column, type GetColumnData } from "./column";
+import type {
+    BuildColumns,
+    ColumnBuider,
+    ColumnBuilderBase,
+} from "./column-builder";
+import { getColumnBuilders, type ColumnsBuilder } from "../columns";
+import type { IndexBuilder } from "../indexes";
+import type { OpitionalKeyOnly, RequiredKeyOnly } from "./operations";
+import type { KeyStrategy } from "./strategies";
+
+type IndexStrategyConfig<TIndex extends IndexBuilder> =
+    TIndex["type"] extends "lsi"
+        ? { sk: KeyStrategy | Column }
+        : {
+              pk: KeyStrategy | Column;
+              sk?: KeyStrategy | Column;
+          };
+
+type IndexesStrategy<
+    TIndexes extends Record<string, IndexBuilder> | undefined,
+> =
+    TIndexes extends Record<string, IndexBuilder>
+        ? { [K in keyof TIndexes]?: IndexStrategyConfig<TIndexes[K]> }
+        : object;
+
+export type StrategyCallback<
+    TColumns extends Record<string, Column>,
+    TPhysicalConfig extends PhysicalTableConfig,
+> = (columns: TColumns) => {
+    [K in keyof TPhysicalConfig as K extends "pk" | "sk"
+        ? K
+        : never]: KeyStrategy | Column;
+} & IndexesStrategy<TPhysicalConfig["indexes"]>;
+
+export interface EntityConfig<TColumn extends Column = Column> {
+    name: string;
+    table: PhysicalTable;
+    columns: Record<string, TColumn>;
+}
+
+export interface PhysicalTableConfig {
+    pk: ColumnBuilderBase;
+    sk?: ColumnBuilderBase;
+    indexes?: Record<string, IndexBuilder>;
+}
+
+export class PhysicalTable<
+    T extends PhysicalTableConfig = PhysicalTableConfig,
+> {
+    declare readonly _: {
+        config: T;
+        name: string;
+        partitionKey: Column;
+        sortKey?: Column;
+        indexes: T["indexes"];
+    };
+
+    /** @internal */
+    [TABLE_SYMBOLS.TABLE_NAME]: string = "";
+
+    /** @internal */
+    [TABLE_SYMBOLS.INDEXES]: T["indexes"] = undefined;
+
+    /** @internal */
+    [TABLE_SYMBOLS.PARTITION_KEY]: Column = {} as Column;
+
+    /** @internal */
+    [TABLE_SYMBOLS.SORT_KEY]?: Column = undefined;
+
+    static readonly Symbol = TABLE_SYMBOLS;
+
+    constructor(name: string, config: T) {
+        this[TABLE_SYMBOLS.TABLE_NAME] = name;
+        this[TABLE_SYMBOLS.PARTITION_KEY] = (config.pk as ColumnBuider).build(
+            this as unknown as AnyTable,
+        );
+        this[TABLE_SYMBOLS.SORT_KEY] = config.sk
+            ? (config.sk as ColumnBuider).build(this as unknown as AnyTable)
+            : undefined;
+        this[TABLE_SYMBOLS.INDEXES] = config.indexes;
+    }
+}
+
+export class Entity<T extends EntityConfig = EntityConfig> {
+    declare readonly _: {
+        readonly config: T;
+        readonly name: T["name"];
+        readonly table: T["table"];
+        readonly columns: T["columns"];
+        readonly strategies: Record<string, KeyStrategy>;
+        readonly inferSelect: InferSelectModel<Entity<T>>;
+        readonly inferInsert: InferInsertModel<Entity<T>>;
+    };
+
+    declare readonly $inferSelect: InferSelectModel<Entity<T>>;
+    declare readonly $inferInsert: InferInsertModel<Entity<T>>;
+
+    /** @internal */
+    [ENTITY_SYMBOLS.ENTITY_NAME]: string = "";
+
+    /** @internal */
+    [ENTITY_SYMBOLS.PHYSICAL_TABLE]: T["table"] = {} as T["table"];
+
+    /** @internal */
+    [ENTITY_SYMBOLS.COLUMNS]: T["columns"] = {} as T["columns"];
+
+    [ENTITY_SYMBOLS.ENTITY_STRATEGY]: Record<string, KeyStrategy> = {};
+
+    static readonly Symbol = ENTITY_SYMBOLS;
+
+    constructor(
+        name: T["name"],
+        table: T["table"],
+        columns: T["columns"],
+        strategies: Record<string, KeyStrategy>,
+    ) {
+        this[ENTITY_SYMBOLS.ENTITY_NAME] = name;
+        this[ENTITY_SYMBOLS.PHYSICAL_TABLE] = table;
+        this[ENTITY_SYMBOLS.COLUMNS] = columns;
+        this[ENTITY_SYMBOLS.ENTITY_STRATEGY] = strategies;
+    }
+}
+
+export type MapColumnName<
+    TName extends string,
+    TColumn extends Column,
+    TDBColumnNames extends boolean,
+> = TDBColumnNames extends true ? TColumn["_"]["name"] : TName;
+
+export type InferModelFromColumns<
+    TColumns extends Record<string, Column>,
+    TInferMode extends "select" | "insert" = "select",
+    TConfig extends { dbColumnNames: boolean; override?: boolean } = {
+        dbColumnNames: false;
+        override: false;
+    },
+> = Simplify<
+    {
+        [Key in keyof TColumns & string as RequiredKeyOnly<
+            MapColumnName<Key, TColumns[Key], TConfig["dbColumnNames"]>,
+            TColumns[Key],
+            TInferMode
+        >]: GetColumnData<TColumns[Key], typeof INFER_MODE.QUERY>;
+    } & {
+        [Key in keyof TColumns & string as OpitionalKeyOnly<
+            MapColumnName<Key, TColumns[Key], TConfig["dbColumnNames"]>,
+            TColumns[Key],
+            TInferMode
+        >]?: GetColumnData<TColumns[Key], typeof INFER_MODE.QUERY> | undefined;
+    }
+>;
+
+export type InferSelectModel<
+    TTable extends Entity,
+    TConfig extends { dbColumnNames: boolean } = { dbColumnNames: false },
+> = InferModelFromColumns<TTable["_"]["columns"], "select", TConfig>;
+
+export type InferInsertModel<
+    TTable extends Entity,
+    TConfig extends { dbColumnNames: boolean; override?: boolean } = {
+        dbColumnNames: false;
+        override: false;
+    },
+> = InferModelFromColumns<TTable["_"]["columns"], "insert", TConfig>;
+
+export type InferSelectedModel<
+    TTable extends Entity,
+    TConfig extends { dbColumnNames: boolean } = { dbColumnNames: false },
+> = InferSelectModel<TTable, TConfig>;
+
+export type TableDefinition<T extends EntityConfig = EntityConfig> = Entity<T> & {
+    columns: T["columns"];
+};
+
+export type AtomicValues<T extends Entity> = Partial<InferInsertModel<T>>;
+
+export type EntityWithColumns<T extends EntityConfig> = Entity<T> & {
+    [Key in keyof T["columns"]]: T["columns"][Key];
+};
+
+export type UpdateTableConfig<
+    T extends PhysicalTableConfig,
+    TUpdate extends Partial<PhysicalTableConfig>,
+> = Required<Update<T, TUpdate>>;
+
+export type AnyTable<TPartial extends Partial<PhysicalTableConfig> = object> =
+    PhysicalTable<UpdateTableConfig<PhysicalTableConfig, TPartial>>;
+
+export function dynamoEntity<
+    TName extends string,
+    TTable extends PhysicalTable,
+    TColumnsMap extends Record<string, ColumnBuilderBase>,
+>(
+    table: TTable,
+    name: TName,
+    columns: TColumnsMap | ((columnsTypes: ColumnsBuilder) => TColumnsMap),
+    strategies?: StrategyCallback<
+        BuildColumns<TName, TColumnsMap>,
+        TTable["_"]["config"]
+    >,
+): EntityWithColumns<{
+    name: TName;
+    table: TTable;
+    columns: BuildColumns<TName, TColumnsMap>;
+}> {
+    const parsedColumns: TColumnsMap =
+        typeof columns === "function" ? columns(getColumnBuilders()) : columns;
+
+    const builtColumns = Object.fromEntries(
+        Object.entries(parsedColumns).map(([name, colBuilderBase]) => {
+            const colBuilder = colBuilderBase as ColumnBuider;
+            colBuilder.setName(name);
+            const column = colBuilder.build({} as unknown as AnyTable);
+            return [name, column];
+        }),
+    ) as BuildColumns<TName, TColumnsMap>;
+
+    const definedStrategies = strategies ? strategies(builtColumns) : {};
+
+    const normalizedStrategies: Record<string, any> = {};
+    for (const [key, val] of Object.entries(definedStrategies)) {
+        if (val instanceof Column) {
+            normalizedStrategies[key] = { type: "prefix", segments: ["", val] };
+        } else if (val && typeof val === "object" && !("type" in val && "segments" in val)) {
+            // It's an index strategy object { pk, sk }
+            const indexStrategy: any = { ...val };
+            if (indexStrategy.pk instanceof Column) {
+                indexStrategy.pk = { type: "prefix", segments: ["", indexStrategy.pk] };
+            }
+            if (indexStrategy.sk instanceof Column) {
+                indexStrategy.sk = { type: "prefix", segments: ["", indexStrategy.sk] };
+            }
+            normalizedStrategies[key] = indexStrategy;
+        } else {
+            normalizedStrategies[key] = val;
+        }
+    }
+
+    const rawEntity = new Entity(name, table, {}, normalizedStrategies);
+
+    rawEntity[ENTITY_SYMBOLS.COLUMNS] = builtColumns;
+
+    const entity = Object.assign(rawEntity, builtColumns);
+
+    return entity as unknown as EntityWithColumns<{
+        name: TName;
+        table: TTable;
+        columns: BuildColumns<TName, TColumnsMap>;
+    }>;
+}
+
+export function dynamoTable<
+    TTableName extends string,
+    TConfig extends PhysicalTableConfig,
+>(name: TTableName, config: TConfig) {
+    return new PhysicalTable(name, config);
+}

package/src/core/validation.ts

@@ -0,0 +1,75 @@
+/**
+ * Estimating the byte size of a DynamoDB item.
+ * Reference: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/CapacityUnitCalculations.html
+ */
+export function calculateItemSize(item: Record<string, unknown>): number {
+    let size = 0;
+
+    for (const [key, value] of Object.entries(item)) {
+        // Attribute name size
+        size += Buffer.byteLength(key, "utf8");
+
+        size += calculateValueSize(value);
+    }
+
+    return size;
+}
+
+function calculateValueSize(value: unknown): number {
+    if (value === null || value === undefined) {
+        return 1; // NULL
+    }
+
+    if (typeof value === "string") {
+        return Buffer.byteLength(value, "utf8");
+    }
+
+    if (typeof value === "number") {
+        // Numbers are up to 38 significant digits. 
+        // In DynamoDB, they are stored as variable length.
+        // Rule of thumb: length of string representation + extra byte.
+        // AWS Doc: "Numbers are stored in a compressed format... up to 21 bytes."
+        // We'll use a conservative estimate.
+        return 21;
+    }
+
+    if (typeof value === "boolean") {
+        return 1;
+    }
+
+    if (value instanceof Buffer || value instanceof Uint8Array) {
+        return value.byteLength;
+    }
+
+    if (Array.isArray(value)) {
+        // List: 3 bytes overhead + sum of elements
+        let listSize = 3;
+        for (const item of value) {
+            listSize += calculateValueSize(item);
+        }
+        return listSize;
+    }
+
+    if (value instanceof Set) {
+        // Set: overhead? usually treated like List or similar.
+        // AWS says: "size of all the elements plus the size of the attribute name."
+        // We'll estimate it like a List for safety.
+        let setSize = 3;
+        for (const item of value) {
+            setSize += calculateValueSize(item);
+        }
+        return setSize;
+    }
+
+    if (typeof value === "object") {
+        // Map: 3 bytes overhead + attribute names + attribute values
+        let mapSize = 3;
+        for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+            mapSize += Buffer.byteLength(k, "utf8");
+            mapSize += calculateValueSize(v);
+        }
+        return mapSize;
+    }
+
+    return 0;
+}