@aurios/mizzle 1.1.1 → 1.1.3

package/src/core/parser.ts

@@ -1,113 +1,107 @@
-import { ENTITY_SYMBOLS, TABLE_SYMBOLS } from "@mizzle/shared";
+import { ENTITY_SYMBOLS, TABLE_SYMBOLS } from "@repo/shared";
 import type { InternalRelationalSchema } from "./relations";
 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;
+  [TABLE_SYMBOLS.PARTITION_KEY]: Column | undefined;
+  [TABLE_SYMBOLS.SORT_KEY]?: 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`);
-        }
+  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>[] = [];
+    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);
-            }
-        }
+    // 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;
-                    }
-                }
-            }
-        }
+    // 2. For each primary item, find its relations
+    for (const primaryItem of primaryItems) {
+      for (const [relName, relOption] of Object.entries(relations)) {
+        if (!relOption) continue;
 
-        return primaryItems;
-    }
+        const relConfig = rootEntityMeta.relations[relName];
+        if (!relConfig) continue;
+
+        const targetEntity = relConfig.config.to;
 
-    /**
-     * 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 unknown as MinimalPhysicalTable;
-
-        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
-            ? this.matchStrategy(item[skName], strategies.sk)
-            : true;
-
-        return pkMatch && skMatch;
+        // 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;
+          }
+        }
+      }
     }
 
-    /**
-     * 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;
+    return primaryItems;
+  }
 
-        const strValue = String(value);
+  /**
+   * 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 unknown as MinimalPhysicalTable;
+    if (!physicalTable || !physicalTable[TABLE_SYMBOLS.PARTITION_KEY]) return false;
 
-        if (strategy.type === "static") {
-            return strValue === strategy.segments[0];
-        }
+    const pkName = physicalTable[TABLE_SYMBOLS.PARTITION_KEY]!.name;
+    const skName = physicalTable[TABLE_SYMBOLS.SORT_KEY]?.name;
 
-        if (strategy.type === "prefix" || strategy.type === "composite") {
-            const prefix = strategy.segments[0];
-            return typeof prefix === "string" && strValue.startsWith(prefix);
-        }
+    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;
 
-        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

@@ -1,4 +1,4 @@
-import { RELATION_SYMBOLS } from "@mizzle/shared";
+import { RELATION_SYMBOLS } from "@repo/shared";
 import { Entity } from "./table";
 import { Column } from "./column";
 
@@ -11,133 +11,135 @@ 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;
+  /**
+   * 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
-    ) {}
+  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>;
+  /**
+   * The source entity.
+   */
+  entity: TEntity;
+  /**
+   * Map of relation names to their configurations.
+   */
+  config: Record<string, Relation>;
 }
 
 /**
  * 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>;
-    };
+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">;
-    };
+  /**
+   * 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];
+  /**
+   * 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: {
-    /**
-     * 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">;
+  /**
+   * 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>;
 
 /**
  * Callback function to define relations for multiple entities.
  */
 export type MultiRelationsCallback<TSchema extends Record<string, Entity>> = (
-    helpers: RelationsHelpers<TSchema>
+  helpers: RelationsHelpers<TSchema>,
 ) => {
-    [K in keyof TSchema]?: Record<string, Relation>;
+  [K in keyof TSchema]?: Record<string, Relation>;
 };
 
 /**
  * Defines relationships for a single entity.
- * 
+ *
  * @example
  * ```ts
  * export const usersRelations = defineRelations(users, ({ many }) => ({
  *   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
+  entity: TEntity,
+  relations: RelationsCallback,
 ): 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) => ({
@@ -152,126 +154,137 @@ export function defineRelations<TEntity extends Entity>(
  *   },
  * }));
  * ```
- * 
+ *
  * @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>
+  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: {},
-        };
+  first: Entity | Record<string, Entity>,
+  callback: RelationsCallback | MultiRelationsCallback<any>,
+): RelationsDefinition | MultiRelationsDefinition {
+  if (first instanceof Entity) {
+    // Single entity mode
+    const cb = callback as RelationsCallback;
+    const config = cb({
+      one: (to: Entity, config?: Omit<RelationConfig, "to">) =>
+        new Relation("one", { to, ...config }),
+      many: (to: Entity, config?: Omit<RelationConfig, "to">) =>
+        new Relation("many", { to, ...config }),
+    });
 
-        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;
-        }
+    return {
+      entity: first,
+      config,
+      [RELATION_SYMBOLS.RELATION_CONFIG]: true,
+    };
+  } else {
+    // Multi-entity mode
+    const schema = first as Record<string, Entity>;
+    const cb = callback as MultiRelationsCallback<typeof schema>;
 
-        const definitions = callback(helpers);
+    // Build helpers
+    const helpers: Record<string, unknown> = {
+      one: {},
+      many: {},
+    };
 
-        return {
-            schema,
-            definitions,
-            [RELATION_SYMBOLS.RELATION_CONFIG]: true
-        };
+    for (const [key, entity] of Object.entries(schema)) {
+      (helpers.one as Record<string, unknown>)[key] = (config?: Omit<RelationConfig, "to">) =>
+        new Relation("one", { to: entity, ...config });
+      (helpers.many as Record<string, unknown>)[key] = (config?: Omit<RelationConfig, "to">) =>
+        new Relation("many", { to: entity, ...config });
+      helpers[key] = entity;
     }
+
+    const definitions = cb(helpers as unknown as RelationsHelpers<typeof schema>);
+
+    return {
+      schema,
+      definitions: definitions as Record<string, Record<string, Relation>>,
+      [RELATION_SYMBOLS.RELATION_CONFIG]: true,
+    };
+  }
 }
 
 /**
  * Metadata for an entity and its relationships.
  */
 export interface EntityMetadata {
-    entity: Entity;
-    relations: Record<string, Relation>;
+  entity: Entity;
+  relations: Record<string, Relation>;
 }
 
 /**
  * Internal relational schema mapping entity names to their metadata.
  */
 export interface InternalRelationalSchema {
-    entities: Record<string, EntityMetadata>;
+  entities: Record<string, EntityMetadata>;
 }
 
 /**
  * Extract metadata from a flat schema definition.
  */
 export function extractMetadata(schema: Record<string, unknown>): InternalRelationalSchema {
-    const metadata: InternalRelationalSchema = {
-        entities: {},
-    };
+  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: {},
-            };
-        }
+  // 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]) {
-            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
-                );
+  // Second pass: identify relations
+  for (const [, value] of Object.entries(schema)) {
+    if (
+      value &&
+      typeof value === "object" &&
+      (value as Record<string | symbol, unknown>)[RELATION_SYMBOLS.RELATION_CONFIG]
+    ) {
+      const relationConfig = value as Record<string | symbol, unknown>;
+      if (relationConfig.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 (entityEntry) {
+          const [, meta] = entityEntry;
+          meta.relations = { ...meta.relations, ...definition.config };
+        }
+      } else if (relationConfig.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 };
-                    }
-                }
-            }
+          if (metaEntry && relations) {
+            const [, meta] = metaEntry;
+            meta.relations = { ...meta.relations, ...relations };
+          }
         }
+      }
     }
+  }
 
-    return metadata;
+  return metadata;
 }