@aurios/mizzle 1.0.0 → 1.1.0

package/src/columns/list.ts

@@ -1,7 +1,6 @@
 import {
     Column,
     type ColumnBaseConfig,
-    type ColumnRuntimeConfig,
 } from "../core/column";
 import {
     ColumnBuider,
@@ -28,6 +27,7 @@ export class ListColumnBuilder<
     ): ListColumn<MakeColumnConfig<T, TTableName>> {
         return new ListColumn<MakeColumnConfig<T, TTableName>>(
             table,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             this.config as any,
         );
     }
@@ -42,6 +42,22 @@ export function list(): ListColumnInitial<"">;
 export function list<TName extends string>(
     name: TName,
 ): ListColumnInitial<TName>;
+/**
+ * Defines a List column ("L") in DynamoDB.
+ * 
+ * A list is an ordered collection of values. It can store mixed types, 
+ * but you can enforce a specific type using `.$type<T[]>()`.
+ * 
+ * @example
+ * ```ts
+ * const posts = defineTable("posts", {
+ *   tags: list("tags").$type<string[]>(),
+ * });
+ * ```
+ * 
+ * @param name The name of the attribute in DynamoDB. If omitted, it will use the property name in the definition object.
+ * @returns A ListColumnBuilder instance.
+ */
 export function list(name?: string) {
     return new ListColumnBuilder(name ?? "");
 }

package/src/columns/map.ts

@@ -1,7 +1,6 @@
 import {
     Column,
     type ColumnBaseConfig,
-    type ColumnRuntimeConfig,
 } from "../core/column";
 import {
     ColumnBuider,
@@ -29,6 +28,7 @@ export class MapColumnBuilder<
     ): MapColumn<MakeColumnConfig<T, TTableName>> {
         return new MapColumn<MakeColumnConfig<T, TTableName>>(
             table,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             this.config as any,
         );
     }
@@ -41,6 +41,23 @@ export class MapColumn<
 
 export function map(): MapColumnInitial<"">;
 export function map<TName extends string>(name: TName): MapColumnInitial<TName>;
+/**
+ * Defines a Map column ("M") in DynamoDB.
+ * 
+ * A map is a set of key-value pairs (like a JSON object). 
+ * Unlike `json()`, this is stored as a native DynamoDB Map, allowing you to filter/query nested properties 
+ * more easily in some contexts, though `json()` is often preferred for simple object storage.
+ * 
+ * @example
+ * ```ts
+ * const users = defineTable("users", {
+ *   metadata: map("metadata").$type<{ verified: boolean, loginCount: number }>(),
+ * });
+ * ```
+ * 
+ * @param name The name of the attribute in DynamoDB. If omitted, it will use the property name in the definition object.
+ * @returns A MapColumnBuilder instance.
+ */
 export function map(name?: string) {
     return new MapColumnBuilder(name ?? "");
 }

package/src/columns/number-set.ts

@@ -1,7 +1,6 @@
 import {
     Column,
     type ColumnBaseConfig,
-    type ColumnRuntimeConfig,
 } from "../core/column";
 import {
     ColumnBuider,
@@ -30,6 +29,7 @@ export class NumberSetColumnBuilder<
     ): NumberSetColumn<MakeColumnConfig<T, TTableName>> {
         return new NumberSetColumn<MakeColumnConfig<T, TTableName>>(
             table,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             this.config as any,
         );
     }
@@ -44,6 +44,21 @@ export function numberSet(): NumberSetColumnInitial<"">;
 export function numberSet<TName extends string>(
     name: TName,
 ): NumberSetColumnInitial<TName>;
+/**
+ * Defines a Number Set column ("NS") in DynamoDB.
+ * 
+ * Represents a set of unique numbers. Mizzle handles conversion between JavaScript `Set<number>` (or arrays) and DynamoDB Sets.
+ * 
+ * @example
+ * ```ts
+ * const metrics = defineTable("metrics", {
+ *   counts: numberSet("counts"),
+ * });
+ * ```
+ * 
+ * @param name The name of the attribute in DynamoDB. If omitted, it will use the property name in the definition object.
+ * @returns A NumberSetColumnBuilder instance.
+ */
 export function numberSet(name?: string) {
     return new NumberSetColumnBuilder(name ?? "");
 }

package/src/columns/number.ts

@@ -3,7 +3,6 @@ import {
     ColumnBuider,
     type MakeColumnConfig,
     type ColumnBuilderBaseConfig,
-    type ColumnBuilderRuntimeConfig,
 } from "../core/column-builder";
 import type { AnyTable } from "../core/table";
 
@@ -38,6 +37,7 @@ export class NumberColumnBuilder<
     ): NumberColumn<MakeColumnConfig<T, TTableName>> {
         return new NumberColumn<MakeColumnConfig<T, TTableName>>(
             table,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             this.config as any,
         );
     }
@@ -52,6 +52,20 @@ export function number(): NumberColumnInitial<"">;
 export function number<TName extends string>(
     name: TName,
 ): NumberColumnInitial<TName>;
+/**
+ * Defines a Number column ("N") in DynamoDB.
+ * 
+ * @example
+ * ```ts
+ * const products = defineTable("products", {
+ *   price: number("price"),
+ *   quantity: number("quantity").default(0),
+ * });
+ * ```
+ * 
+ * @param name The name of the attribute in DynamoDB. If omitted, it will use the property name in the definition object.
+ * @returns A NumberColumnBuilder instance.
+ */
 export function number(name?: string) {
     return new NumberColumnBuilder(name ?? "");
 }

package/src/columns/string-set.ts

@@ -1,7 +1,6 @@
 import {
     Column,
     type ColumnBaseConfig,
-    type ColumnRuntimeConfig,
 } from "../core/column";
 import {
     ColumnBuider,
@@ -40,6 +39,7 @@ export class StringSetColumnBuilder<
     ): StringSetColumn<MakeColumnConfig<T, TTableName>> {
         return new StringSetColumn<MakeColumnConfig<T, TTableName>>(
             table,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             this.config as any,
         );
     }
@@ -54,6 +54,21 @@ export function stringSet(): StringSetColumnInitial<"">;
 export function stringSet<TName extends string>(
     name: TName,
 ): StringSetColumnInitial<TName>;
+/**
+ * Defines a String Set column ("SS") in DynamoDB.
+ * 
+ * Represents a set of unique strings. Mizzle handles conversion between JavaScript `Set<string>` (or arrays) and DynamoDB Sets.
+ * 
+ * @example
+ * ```ts
+ * const users = defineTable("users", {
+ *   roles: stringSet("roles"),
+ * });
+ * ```
+ * 
+ * @param name The name of the attribute in DynamoDB. If omitted, it will use the property name in the definition object.
+ * @returns A StringSetColumnBuilder instance.
+ */
 export function stringSet(name?: string) {
     return new StringSetColumnBuilder(name ?? "");
 }

package/src/columns/string.ts

@@ -1,7 +1,6 @@
 import {
     Column,
     type ColumnBaseConfig,
-    type ColumnRuntimeConfig,
 } from "../core/column";
 import {
     ColumnBuider,
@@ -45,6 +44,7 @@ class StringColumnBuilder<
     ): StringColumn<MakeColumnConfig<T, TTableName>> {
         return new StringColumn<MakeColumnConfig<T, TTableName>>(
             table,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             this.config as any,
         );
     }
@@ -59,6 +59,21 @@ export function string(): StringColumnInitial<"">;
 export function string<TName extends string>(
     name: TName,
 ): StringColumnInitial<TName>;
+/**
+ * Defines a String column ("S") in DynamoDB.
+ * 
+ * @example
+ * ```ts
+ * const users = defineTable("users", {
+ *   name: string("name"),
+ *   email: string("email").notNull(),
+ *   status: string("status").default("active"),
+ * });
+ * ```
+ * 
+ * @param name The name of the attribute in DynamoDB. If omitted, it will use the property name in the definition object.
+ * @returns A StringColumnBuilder instance.
+ */
 export function string(name?: string) {
     return new StringColumnBuilder(name ?? "");
 }

package/src/columns/uuid.ts

@@ -3,7 +3,6 @@ import { v7 as uuidV7 } from "uuid";
 import {
     ColumnBuider,
     type ColumnBuilderBaseConfig,
-    type ColumnBuilderRuntimeConfig,
     type MakeColumnConfig,
 } from "../core/column-builder";
 import type { AnyTable } from "../core/table";
@@ -32,6 +31,7 @@ export class UUIDColumnBuilder<
     ): UUIDColumn<MakeColumnConfig<T, TTableName>> {
         return new UUIDColumn<MakeColumnConfig<T, TTableName>>(
             table,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             this.config as any,
         );
     }
@@ -46,6 +46,22 @@ export function uuid(): UUIDColumnInitial<"">;
 export function uuid<TName extends string>(
     name: TName,
 ): UUIDColumnInitial<TName>;
+/**
+ * Defines a UUID column.
+ * 
+ * In DynamoDB, this is stored as a string ("S"). It includes a `.defaultRandom()` helper
+ * to automatically generate UUID v7 values on insert.
+ * 
+ * @example
+ * ```ts
+ * const users = defineTable("users", {
+ *   id: uuid("id").partitionKey().defaultRandom(),
+ * });
+ * ```
+ * 
+ * @param name The name of the attribute in DynamoDB. If omitted, it will use the property name in the definition object.
+ * @returns A UUIDColumnBuilder instance.
+ */
 export function uuid(name?: string) {
     return new UUIDColumnBuilder(name ?? "");
 }

package/src/core/client.ts

@@ -3,7 +3,7 @@ import { RetryHandler } from "./retry";
 
 // We define a simplified interface for what we need from the client to avoid complex generic matching
 export interface IMizzleClient {
-    send(command: any, options?: any): Promise<any>;
+    send(command: unknown, options?: unknown): Promise<unknown>;
 }
 
 export class MizzleClient implements IMizzleClient {
@@ -12,7 +12,8 @@ export class MizzleClient implements IMizzleClient {
         private retryHandler: RetryHandler
     ) {}
 
-    send(command: any, options?: any): Promise<any> {
-        return this.retryHandler.execute(() => this.client.send(command, options));
+    send(command: unknown, options?: unknown): Promise<unknown> {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return this.retryHandler.execute(() => this.client.send(command as any, options as any));
     }
 }

package/src/core/errors.ts

@@ -18,7 +18,7 @@ export interface CancellationReason {
     index: number;
     code: string;
     message?: string;
-    item?: Record<string, any>;
+    item?: Record<string, unknown>;
 }
 
 /**

package/src/core/parser.ts

@@ -4,6 +4,11 @@ import { type KeyStrategy } from "./strategies";
 import { Entity } from "./table";
 import { Column } from "./column";
 
+interface MinimalPhysicalTable {
+    [TABLE_SYMBOLS.PARTITION_KEY]: Column;
+    [TABLE_SYMBOLS.SORT_KEY]?: Column;
+}
+
 /**
  * Parser for DynamoDB item collections (Single-Table Design).
  */
@@ -72,11 +77,10 @@ export class ItemCollectionParser {
             string,
             KeyStrategy
         >;
-        const physicalTable = entity[ENTITY_SYMBOLS.PHYSICAL_TABLE] as any;
+        const physicalTable = entity[ENTITY_SYMBOLS.PHYSICAL_TABLE] as unknown as MinimalPhysicalTable;
 
-        const pkName = (physicalTable[TABLE_SYMBOLS.PARTITION_KEY] as Column).name;
-        const skName = (physicalTable[TABLE_SYMBOLS.SORT_KEY] as Column | undefined)
-            ?.name;
+        const pkName = physicalTable[TABLE_SYMBOLS.PARTITION_KEY].name;
+        const skName = physicalTable[TABLE_SYMBOLS.SORT_KEY]?.name;
 
         const pkMatch = this.matchStrategy(item[pkName], strategies.pk);
         const skMatch = skName

package/src/core/relations.ts

@@ -54,7 +54,46 @@ export interface RelationsDefinition<TEntity extends Entity = Entity> {
 }
 
 /**
- * Callback function to define relations.
+ * Definition of relations for multiple entities in a schema.
+ */
+export interface MultiRelationsDefinition<TSchema extends Record<string, Entity> = Record<string, Entity>> {
+    /**
+     * The schema containing all entities.
+     */
+    schema: TSchema;
+    /**
+     * Map of entity names to their relation configurations.
+     */
+    definitions: {
+        [K in keyof TSchema]?: Record<string, Relation>;
+    };
+}
+
+/**
+ * Helpers provided to the defineRelations callback.
+ */
+export type RelationsHelpers<TSchema extends Record<string, Entity>> = {
+    /**
+     * Define a one-to-one relationship.
+     */
+    one: {
+        [K in keyof TSchema]: (config?: Omit<RelationConfig, "to">) => Relation<"one">;
+    };
+    /**
+     * Define a one-to-many relationship.
+     */
+    many: {
+        [K in keyof TSchema]: (config?: Omit<RelationConfig, "to">) => Relation<"many">;
+    };
+} & {
+    /**
+     * Access an entity in the schema to get its columns.
+     */
+    [K in keyof TSchema]: TSchema[K];
+};
+
+/**
+ * Callback function to define relations for a single entity.
  */
 export type RelationsCallback = (helpers: {
     /**
@@ -68,7 +107,16 @@ export type RelationsCallback = (helpers: {
 }) => Record<string, Relation>;
 
 /**
- * Define relations for an entity.
+ * Callback function to define relations for multiple entities.
+ */
+export type MultiRelationsCallback<TSchema extends Record<string, Entity>> = (
+    helpers: RelationsHelpers<TSchema>
+) => {
+    [K in keyof TSchema]?: Record<string, Relation>;
+};
+
+/**
+ * Defines relationships for a single entity.
  * 
  * @example
  * ```ts
@@ -76,21 +124,87 @@ export type RelationsCallback = (helpers: {
  *   posts: many(posts),
  * }));
  * ```
+ * 
+ * @param entity The source entity.
+ * @param relations A callback function to define relations using provided helpers.
+ * @returns A relations definition for the entity.
  */
 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>;
+): RelationsDefinition<TEntity>;
+
+/**
+ * Defines relationships for multiple entities in a centralized schema-aware way.
+ * This approach helps resolve circular dependencies between entities.
+ * 
+ * @example
+ * ```ts
+ * export const relations = defineRelations({ users, posts }, (r) => ({
+ *   users: {
+ *     posts: r.many.posts(),
+ *   },
+ *   posts: {
+ *     author: r.one.users({
+ *       fields: [r.posts.authorId],
+ *       references: [r.users.id],
+ *     }),
+ *   },
+ * }));
+ * ```
+ * 
+ * @param schema An object mapping names to entity definitions.
+ * @param relations A callback function to define relations for all entities in the schema.
+ * @returns A multi-entity relations definition.
+ */
+export function defineRelations<TSchema extends Record<string, Entity>>(
+    schema: TSchema,
+    relations: MultiRelationsCallback<TSchema>
+): MultiRelationsDefinition<TSchema>;
+
+/**
+ * Implementation of defineRelations.
+ */
+export function defineRelations(
+    first: Entity | Record<string, Entity>,
+    callback: Function
+): any {
+    if (first instanceof Entity) {
+        // Single entity mode
+        const config = callback({
+            one: (to: Entity, config: any) => new Relation("one", { to, ...config }),
+            many: (to: Entity, config: any) => new Relation("many", { to, ...config }),
+        });
+
+        return {
+            entity: first,
+            config,
+            [RELATION_SYMBOLS.RELATION_CONFIG]: true
+        };
+    } else {
+        // Multi-entity mode
+        const schema = first as Record<string, Entity>;
+        
+        // Build helpers
+        const helpers: any = {
+            one: {},
+            many: {},
+        };
+
+        for (const [key, entity] of Object.entries(schema)) {
+            helpers.one[key] = (config: any) => new Relation("one", { to: entity, ...config });
+            helpers.many[key] = (config: any) => new Relation("many", { to: entity, ...config });
+            helpers[key] = entity;
+        }
+
+        const definitions = callback(helpers);
+
+        return {
+            schema,
+            definitions,
+            [RELATION_SYMBOLS.RELATION_CONFIG]: true
+        };
+    }
 }
 
 /**
@@ -129,18 +243,32 @@ export function extractMetadata(schema: Record<string, unknown>): InternalRelati
     // 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,
-                };
+            if ((value as any).entity) {
+                // Single entity definition
+                const definition = value as RelationsDefinition;
+                const entityEntry = Object.entries(metadata.entities).find(
+                    ([_, meta]) => meta.entity === definition.entity
+                );
+
+                if (entityEntry) {
+                    const [, meta] = entityEntry;
+                    meta.relations = { ...meta.relations, ...definition.config };
+                }
+            } else if ((value as any).definitions) {
+                // Multi-entity definition
+                const multiDef = value as MultiRelationsDefinition;
+                for (const [entityName, relations] of Object.entries(multiDef.definitions)) {
+                    // Try to find the entity in our metadata by matching the entity from the schema
+                    const entityInSchema = multiDef.schema[entityName];
+                    const metaEntry = Object.entries(metadata.entities).find(
+                        ([_, meta]) => meta.entity === entityInSchema
+                    );
+
+                    if (metaEntry && relations) {
+                        const [, meta] = metaEntry;
+                        meta.relations = { ...meta.relations, ...relations };
+                    }
+                }
             }
         }
     }

package/src/core/retry.ts

@@ -44,14 +44,15 @@ export class RetryHandler {
         throw lastError;
     }
 
-    private isRetryable(error: any): boolean {
-        if (!error) return false;
+    private isRetryable(error: unknown): boolean {
+        if (!error || typeof error !== 'object') return false;
         
-        if (RETRYABLE_ERRORS.has(error.name)) {
+        const err = error as { name?: string; $metadata?: { httpStatusCode?: number } };
+        if (err.name && RETRYABLE_ERRORS.has(err.name)) {
             return true;
         }
 
-        if (error.$metadata?.httpStatusCode && RETRYABLE_STATUS_CODES.has(error.$metadata.httpStatusCode)) {
+        if (err.$metadata?.httpStatusCode && RETRYABLE_STATUS_CODES.has(err.$metadata.httpStatusCode)) {
             return true;
         }
 

package/src/core/snapshot.ts

@@ -153,7 +153,7 @@ function physicalTableToSnapshot(table: PhysicalTable, entities: Entity[]): Tabl
 
     const attributeDefinitions = Array.from(attributeDefinitionsMap.entries()).map(([name, type]) => ({
         AttributeName: name,
-        AttributeType: type as any
+        AttributeType: type as "S" | "N" | "B"
     })).sort((a, b) => a.AttributeName.localeCompare(b.AttributeName));
 
     gsis.sort((a, b) => (a.IndexName || "").localeCompare(b.IndexName || ""));

package/src/core/table.ts

@@ -189,6 +189,24 @@ export type UpdateTableConfig<
 export type AnyTable<TPartial extends Partial<PhysicalTableConfig> = object> =
     PhysicalTable<UpdateTableConfig<PhysicalTableConfig, TPartial>>;
 
+/**
+ * Defines a logical entity that maps to items within a DynamoDB table.
+ * 
+ * @example
+ * ```ts
+ * const users = dynamoEntity(table, "users", {
+ *   id: string("id"),
+ *   name: string("name"),
+ *   email: string("email"),
+ * });
+ * ```
+ * 
+ * @param table The physical table definition this entity belongs to.
+ * @param name The unique name of the entity (used for typing and potentially in single-table design discriminators).
+ * @param columns A map of column definitions or a callback to define columns.
+ * @param strategies Optional configuration for key generation strategies (PK/SK construction).
+ * @returns The entity definition with strict typing.
+ */
 export function dynamoEntity<
     TName extends string,
     TTable extends PhysicalTable,
@@ -252,6 +270,21 @@ export function dynamoEntity<
     }>;
 }
 
+/**
+ * Defines a physical DynamoDB table schema.
+ * 
+ * @example
+ * ```ts
+ * const table = dynamoTable("my-app-table", {
+ *   pk: string("pk"),
+ *   sk: string("sk"),
+ * });
+ * ```
+ * 
+ * @param name The actual name of the table in DynamoDB (or a reference name).
+ * @param config The table configuration, including primary key (pk) and sort key (sk) definitions.
+ * @returns A PhysicalTable instance representing the table schema.
+ */
 export function dynamoTable<
     TTableName extends string,
     TConfig extends PhysicalTableConfig,