@aurios/mizzle 1.1.2 → 1.1.4

package/test/item-size-error.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from "vitest";
+import { ItemSizeExceededError } from "@aurios/mizzle";
+
+describe("ItemSizeExceededError", () => {
+  it("should be an instance of Error", () => {
+    const error = new ItemSizeExceededError("Item too large");
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(ItemSizeExceededError);
+  });
+
+  it("should have correct name and message", () => {
+    const error = new ItemSizeExceededError("Size 500KB exceeds 400KB limit");
+    expect(error.name).toBe("ItemSizeExceededError");
+    expect(error.message).toBe("Size 500KB exceeds 400KB limit");
+  });
+});

package/test/item-size-validation.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mizzle, ItemSizeExceededError } from "@aurios/mizzle";
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+import { ENTITY_SYMBOLS, TABLE_SYMBOLS } from "@repo/shared";
+
+// Mock send method
+const mockSend = vi.fn();
+const mockDocClient = {
+  send: mockSend,
+  middlewareStack: {
+    add: vi.fn(),
+    remove: vi.fn(),
+  },
+};
+
+describe("Item Size Validation Integration", () => {
+  const mockTable = {
+    [ENTITY_SYMBOLS.PHYSICAL_TABLE]: {
+      [TABLE_SYMBOLS.TABLE_NAME]: "test-table",
+      [TABLE_SYMBOLS.PARTITION_KEY]: { name: "pk" },
+      [TABLE_SYMBOLS.SORT_KEY]: undefined,
+      [TABLE_SYMBOLS.INDEXES]: {},
+    },
+    [ENTITY_SYMBOLS.ENTITY_STRATEGY]: { pk: { type: "static", segments: ["test"] } },
+    [ENTITY_SYMBOLS.COLUMNS]: {
+      pk: { name: "pk" },
+      data: { name: "data" },
+    },
+  } as any;
+
+  beforeEach(() => {
+    vi.spyOn(DynamoDBDocumentClient, "from").mockReturnValue(mockDocClient as any);
+    mockSend.mockReset();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should throw ItemSizeExceededError on insert if item is too large", async () => {
+    const client = new DynamoDBClient({});
+    const db = mizzle(client);
+
+    const largeItem = {
+      pk: "test",
+      data: "x".repeat(401 * 1024),
+    };
+
+    await expect(db.insert(mockTable).values(largeItem).execute()).rejects.toThrow(
+      ItemSizeExceededError,
+    );
+    expect(mockSend).not.toHaveBeenCalled();
+  });
+
+  it("should throw ItemSizeExceededError on update if update payload is too large", async () => {
+    const client = new DynamoDBClient({});
+    const db = mizzle(client);
+
+    const largeData = "x".repeat(401 * 1024);
+
+    await expect(
+      db.update(mockTable).key({ pk: "test" }).set({ data: largeData }).execute(),
+    ).rejects.toThrow(ItemSizeExceededError);
+    expect(mockSend).not.toHaveBeenCalled();
+  });
+
+  it("should throw ItemSizeExceededError on batchWrite if any item is too large", async () => {
+    const client = new DynamoDBClient({});
+    const db = mizzle(client);
+
+    const largeItem = {
+      pk: "test",
+      data: "x".repeat(401 * 1024),
+    };
+
+    await expect(
+      db.batchWrite(mockTable, [{ type: "put", item: largeItem }]).execute(),
+    ).rejects.toThrow(ItemSizeExceededError);
+    expect(mockSend).not.toHaveBeenCalled();
+  });
+});

package/test/item-size.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest";
+import { calculateItemSize } from "@aurios/mizzle/core/validation";
+
+describe("calculateItemSize", () => {
+  it("should calculate size of a simple item", () => {
+    const item = {
+      pk: "USER#1",
+      name: "John Doe",
+    };
+    // pk (2) + USER#1 (6) + name (4) + John Doe (8) = 20
+    expect(calculateItemSize(item)).toBe(20);
+  });
+
+  it("should handle numbers and booleans", () => {
+    const item = {
+      age: 30,
+      active: true,
+    };
+    // age (3) + 21 (number max) + active (6) + 1 (bool) = 31
+    expect(calculateItemSize(item)).toBe(31);
+  });
+
+  it("should handle lists", () => {
+    const item = {
+      tags: ["a", "b"],
+    };
+    // tags (4) + [3 overhead + a(1) + b(1)] = 4 + 5 = 9
+    expect(calculateItemSize(item)).toBe(9);
+  });
+
+  it("should handle maps", () => {
+    const item = {
+      meta: { key: "val" },
+    };
+    // meta (4) + [3 overhead + key(3) + val(3)] = 4 + 9 = 13
+    expect(calculateItemSize(item)).toBe(13);
+  });
+
+  it("should accurately estimate large items", () => {
+    const largeString = "x".repeat(100 * 1024); // 100KB
+    const item = {
+      data: largeString,
+    };
+    // data (4) + 102400 = 102404
+    expect(calculateItemSize(item)).toBe(102404);
+  });
+});

package/test/iterator-pagination.integration.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { dynamoTable, dynamoEntity } from "@aurios/mizzle/table";
+import { string, uuid } from "@aurios/mizzle/columns";
+import { prefixKey, staticKey } from "@aurios/mizzle";
+import { DynamoDBClient, CreateTableCommand, DeleteTableCommand, DescribeTableCommand, DescribeTableCommand } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
+import { mizzle } from "@aurios/mizzle/db";
+
+const client = new DynamoDBClient({
+  endpoint: "http://localhost:8000",
+  region: "us-east-1",
+  credentials: {
+    accessKeyId: "local",
+    secretAccessKey: "local",
+  },
+});
+
+const docClient = DynamoDBDocumentClient.from(client);
+
+describe("Iterator Pagination Integration", () => {
+  const tableName = "TestTable_Pagination";
+  const table = dynamoTable(tableName, {
+    pk: string("pk"),
+    sk: string("sk"),
+  });
+
+  const user = dynamoEntity(
+    table,
+    "User",
+    {
+      id: uuid(),
+      data: string(),
+    },
+    (cols) => ({
+      pk: prefixKey("USER#", cols.id),
+      sk: staticKey("METADATA"),
+    }),
+  );
+
+  // 1MB is the limit. Each item is ~10KB. 120 items = 1.2MB
+  const itemCount = 120;
+  const largeData = "x".repeat(1024 * 10); // 10KB
+
+  beforeAll(async () => {
+    try {
+      await client.send(
+        new CreateTableCommand({
+          TableName: tableName,
+          KeySchema: [
+            { AttributeName: "pk", KeyType: "HASH" },
+            { AttributeName: "sk", KeyType: "RANGE" },
+          ],
+          AttributeDefinitions: [
+            { AttributeName: "pk", AttributeType: "S" },
+            { AttributeName: "sk", AttributeType: "S" },
+          ],
+          ProvisionedThroughput: { ReadCapacityUnits: 25, WriteCapacityUnits: 25 },
+        }),
+      );
+
+      // Wait for table to be active
+      let active = false;
+      while (!active) {
+        const { Table } = await client.send(new DescribeTableCommand({ TableName: tableName }));
+        if (Table?.TableStatus === "ACTIVE") active = true;
+        else await new Promise((r) => setTimeout(r, 500));
+      }
+
+      // Parallel insert to speed up
+      const puts = [];
+      for (let i = 0; i < itemCount; i++) {
+        puts.push(
+          docClient.send(
+            new PutCommand({
+              TableName: tableName,
+              Item: {
+                pk: `USER#${i}`,
+                sk: "METADATA",
+                id: `${i}`,
+                data: largeData,
+              },
+            }),
+          ),
+        );
+      }
+      const results = await Promise.allSettled(puts);
+      const failed = results.filter((r) => r.status === "rejected");
+      if (failed.length > 0) {
+        console.error(`${failed.length} puts failed:`, failed[0]);
+      }
+    } catch (e) {
+      console.error("Setup failed:", e);
+    }
+  }, 60000);
+
+  afterAll(async () => {
+    try {
+      await client.send(new DeleteTableCommand({ TableName: tableName }));
+    } catch {
+      /* ignore */
+    }
+  });
+
+  it("should iterate through all items across multiple pages", async () => {
+    const iterator = mizzle(client).select().from(user).iterator();
+    let count = 0;
+    for await (const _ of iterator) {
+      count++;
+    }
+    expect(count).toBe(itemCount);
+  }, 20000);
+
+  it("should respect limit across multiple pages", async () => {
+    const limit = 15;
+    const iterator = mizzle(client).select().from(user).limit(limit).iterator();
+    let count = 0;
+    for await (const _ of iterator) {
+      count++;
+    }
+    expect(count).toBe(limit);
+  });
+
+  it("should respect pageSize hint and still fetch all", async () => {
+    // Small page size to force many requests
+    const iterator = mizzle(client).select().from(user).pageSize(10).iterator();
+    let count = 0;
+    for await (const _ of iterator) {
+      count++;
+    }
+    expect(count).toBe(itemCount);
+  }, 20000);
+});

package/test/jsdoc-builders.test.ts

@@ -0,0 +1,55 @@
+import { readFileSync } from "fs";
+import { describe, it, expect } from "vitest";
+import path from "path";
+
+function checkJSDoc(filePath: string, methods: string[]) {
+  const content = readFileSync(filePath, "utf-8");
+  methods.forEach((method) => {
+    it(`should have JSDoc for method: ${method} in ${path.basename(filePath)}`, () => {
+      // Simpler escaping for common method names
+      const escapedMethod = method.replace(/[.*+?^${}()|[\\]/g, "\\$&");
+      // Match JSDoc optionally followed by modifiers and the method name
+      const regex = new RegExp(
+        `\\/\\*[\\s\\S]*?\\*\\/\\s*(?:override\\s+|async\\s+|public\\s+|private\\s+|static\\s+)*${escapedMethod}\\b`,
+      );
+      const hasMatch = regex.test(content);
+      expect(hasMatch, `Method ${method} is missing JSDoc in ${filePath}`).toBe(true);
+    });
+  });
+}
+
+describe("JSDoc Presence for Builders", () => {
+  describe("SelectBuilder", () => {
+    const filePath = path.resolve(__dirname, "../src/builders/select.ts");
+    const methods = [
+      "from",
+      "where",
+      "limit",
+      "pageSize",
+      "consistentRead",
+      "sort",
+      "index",
+      "iterator",
+      "execute",
+    ];
+    checkJSDoc(filePath, methods);
+  });
+
+  describe("InsertBuilder", () => {
+    const filePath = path.resolve(__dirname, "../src/builders/insert.ts");
+    const methods = ["values", "returning", "execute"];
+    checkJSDoc(filePath, methods);
+  });
+
+  describe("UpdateBuilder", () => {
+    const filePath = path.resolve(__dirname, "../src/builders/update.ts");
+    const methods = ["key", "set", "add", "remove", "delete", "where", "returning", "execute"];
+    checkJSDoc(filePath, methods);
+  });
+
+  describe("DeleteBuilder", () => {
+    const filePath = path.resolve(__dirname, "../src/builders/delete.ts");
+    const methods = ["returning", "execute"];
+    checkJSDoc(filePath, methods);
+  });
+});

package/test/jsdoc-schema.test.ts

@@ -0,0 +1,107 @@
+import { readFileSync } from "fs";
+import { describe, it, expect } from "vitest";
+import path from "path";
+
+describe("JSDoc Presence for Schema Definition", () => {
+  describe("Core Schema Functions", () => {
+    const filePath = path.resolve(__dirname, "../src/core/table.ts");
+    const content = readFileSync(filePath, "utf-8");
+    const methods = ["dynamoTable", "dynamoEntity"];
+
+    methods.forEach((method) => {
+      it(`should have JSDoc for export: ${method}`, () => {
+        const escapedMethod = method.replace(/[.*+?^${}()|[\\]/g, "\\$&");
+        const regex = new RegExp(
+          `\\/\\*\\*[\\s\\S]*?\\*\\/\\s*(?:export\\s+)?(?:function\\s+)?${escapedMethod}\\b`,
+        );
+        const hasMatch = regex.test(content);
+        expect(hasMatch, `Export ${method} is missing JSDoc in ${filePath}`).toBe(true);
+      });
+    });
+  });
+
+  describe("Initialization", () => {
+    const filePath = path.resolve(__dirname, "../src/db.ts");
+    const content = readFileSync(filePath, "utf-8");
+    const methods = ["mizzle"];
+
+    methods.forEach((method) => {
+      it(`should have JSDoc for export: ${method}`, () => {
+        const escapedMethod = method.replace(/[.*+?^${}()|[\\]/g, "\\$&");
+        const regex = new RegExp(
+          `\\/\\*\\*[\\s\\S]*?\\*\\/\\s*(?:export\\s+)?(?:function\\s+)?${escapedMethod}\\b`,
+        );
+        const hasMatch = regex.test(content);
+        expect(hasMatch, `Export ${method} is missing JSDoc in ${filePath}`).toBe(true);
+      });
+    });
+  });
+
+  describe("CLI Config", () => {
+    const filePath = path.resolve(__dirname, "../../mizzling/src/config.ts");
+    const content = readFileSync(filePath, "utf-8");
+    const methods = ["defineConfig"];
+
+    methods.forEach((method) => {
+      it(`should have JSDoc for export: ${method}`, () => {
+        const escapedMethod = method.replace(/[.*+?^${}()|[\\]/g, "\\$&");
+        const regex = new RegExp(
+          `\\/\\*\\*[\\s\\S]*?\\*\\/\\s*(?:export\\s+)?(?:function\\s+)?${escapedMethod}\\b`,
+        );
+        const hasMatch = regex.test(content);
+        expect(hasMatch, `Export ${method} is missing JSDoc in ${filePath}`).toBe(true);
+      });
+    });
+  });
+
+  describe("Relations", () => {
+    const filePath = path.resolve(__dirname, "../src/core/relations.ts");
+    const content = readFileSync(filePath, "utf-8");
+    const methods = ["defineRelations"];
+
+    methods.forEach((method) => {
+      it(`should have JSDoc for export: ${method}`, () => {
+        const escapedMethod = method.replace(/[.*+?^${}()|[\\]/g, "\\$&");
+        const regex = new RegExp(
+          `\\/\\*\\*[\\s\\S]*?\\*\\/\\s*(?:export\\s+)?(?:function\\s+)?${escapedMethod}\\b`,
+        );
+        const hasMatch = regex.test(content);
+        expect(hasMatch, `Export ${method} is missing JSDoc in ${filePath}`).toBe(true);
+      });
+    });
+  });
+
+  describe("Column Builders", () => {
+    const columnFiles = [
+      "string.ts",
+      "number.ts",
+      "boolean.ts",
+      "date.ts",
+      "uuid.ts",
+      "json.ts",
+      "binary.ts",
+      "list.ts",
+      "map.ts",
+      "string-set.ts",
+      "number-set.ts",
+      "binary-set.ts",
+    ];
+
+    columnFiles.forEach((file) => {
+      const builderName = file
+        .replace(".ts", "")
+        .replace(/-([a-z])/g, (_, letter) => letter.toUpperCase()); // camelCase
+
+      it(`should have JSDoc for column builder: ${builderName} in ${file}`, () => {
+        const filePath = path.resolve(__dirname, `../src/columns/${file}`);
+        const content = readFileSync(filePath, "utf-8");
+        const escapedMethod = builderName.replace(/[.*+?^${}()|[\\]/g, "\\$&");
+        const regex = new RegExp(
+          `\\/\\*\\*[\\s\\S]*?\\*\\/\\s*(?:export\\s+)?(?:function\\s+)?${escapedMethod}\\b`,
+        );
+        const hasMatch = regex.test(content);
+        expect(hasMatch, `Export ${builderName} is missing JSDoc in ${filePath}`).toBe(true);
+      });
+    });
+  });
+});

package/test/json-column.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { json } from "@aurios/mizzle/columns";
+import { dynamoTable, dynamoEntity } from "@aurios/mizzle/table";
+
+describe("json column", () => {
+  it("should define a json column", () => {
+    const col = json("data");
+    expect(col.config.name).toBe("data");
+    expect(col.config.dataType).toBe("json");
+  });
+
+  it("should serialize objects to strings for DynamoDB", () => {
+    const table = dynamoTable("test", {
+      pk: json("pk").partitionKey(),
+    });
+    const entity = dynamoEntity(table, "test", {
+      pk: json("pk"),
+    });
+    const col = entity.pk;
+    const data = { hello: "world", numbers: [1, 2, 3] };
+
+    expect(col.mapToDynamoValue(data)).toBe(JSON.stringify(data));
+  });
+
+  it("should deserialize strings from DynamoDB back to objects", () => {
+    const table = dynamoTable("test", {
+      pk: json("pk").partitionKey(),
+    });
+    const entity = dynamoEntity(table, "test", {
+      pk: json("pk"),
+    });
+    const col = entity.pk;
+    const data = { hello: "world" };
+    const serialized = JSON.stringify(data);
+
+    expect(col.mapFromDynamoValue(serialized)).toEqual(data);
+  });
+
+  it("should return raw value if parsing fails", () => {
+    const table = dynamoTable("test", {
+      pk: json("pk").partitionKey(),
+    });
+    const entity = dynamoEntity(table, "test", {
+      pk: json("pk"),
+    });
+    const col = entity.pk;
+    const invalidJson = "{ invalid }";
+
+    expect(col.mapFromDynamoValue(invalidJson as unknown)).toBe(invalidJson);
+  });
+});

package/test/metadata.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest";
+import { dynamoTable, dynamoEntity } from "@aurios/mizzle/table";
+import { defineRelations, extractMetadata } from "@aurios/mizzle";
+import { string, uuid } from "@aurios/mizzle/columns";
+
+const table = dynamoTable("mizzle-test", {
+  pk: string("pk"),
+  sk: string("sk"),
+});
+
+const users = dynamoEntity(table, "users", {
+  id: uuid("id"),
+  name: string("name"),
+});
+
+const posts = dynamoEntity(table, "posts", {
+  id: uuid("id"),
+  userId: uuid("userId"),
+  content: string("content"),
+});
+
+const usersRelations = defineRelations(users, ({ many }) => ({
+  posts: many(posts),
+}));
+
+const postsRelations = defineRelations(posts, ({ one }) => ({
+  author: one(users, {
+    fields: [posts.userId],
+    references: [users.id],
+  }),
+}));
+
+describe("extractMetadata", () => {
+  it("should correctly extract metadata from relations definition", () => {
+    const schema = {
+      users,
+      posts,
+      usersRelations,
+      postsRelations,
+    };
+
+    const metadata = extractMetadata(schema);
+
+    expect(metadata.entities.users).toBeDefined();
+    expect(metadata.entities.users!.entity).toBe(users);
+    expect(metadata.entities.users!.relations.posts).toBeDefined();
+    expect(metadata.entities.users!.relations.posts!.type).toBe("many");
+
+    expect(metadata.entities.posts).toBeDefined();
+    expect(metadata.entities.posts!.entity).toBe(posts);
+    expect(metadata.entities.posts!.relations.author).toBeDefined();
+    expect(metadata.entities.posts!.relations.author!.type).toBe("one");
+  });
+});

package/test/mizzle-package.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+describe("Mizzle Core Package", () => {
+  const mizzlePath = process.cwd().includes("packages/mizzle") 
+    ? process.cwd() 
+    : join(process.cwd(), "packages", "mizzle");
+
+  it("should have a package.json", () => {
+    expect(existsSync(join(mizzlePath, "package.json"))).toBe(true);
+  });
+
+  it("should have migrated core directories", () => {
+    expect(existsSync(join(mizzlePath, "src", "builders"))).toBe(true);
+    expect(existsSync(join(mizzlePath, "src", "columns"))).toBe(true);
+    expect(existsSync(join(mizzlePath, "src", "expressions"))).toBe(true);
+    expect(existsSync(join(mizzlePath, "src", "core"))).toBe(true);
+  });
+});

package/test/relational-centralized.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from "vitest";
+import { dynamoTable, dynamoEntity } from "@aurios/mizzle/core/table";
+import { defineRelations, extractMetadata } from "@aurios/mizzle/core/relations";
+import { string, uuid } from "@aurios/mizzle/columns";
+
+describe("Centralized defineRelations", () => {
+  const table = dynamoTable("mizzle-test", {
+    pk: string("pk"),
+    sk: string("sk"),
+  });
+
+  const users = dynamoEntity(table, "users", {
+    id: uuid("id"),
+    name: string("name"),
+  });
+
+  const posts = dynamoEntity(table, "posts", {
+    id: uuid("id"),
+    authorId: uuid("authorId"),
+    content: string("content"),
+  });
+
+  it("should allow defining relations for multiple entities at once", () => {
+    const relations = defineRelations({ users, posts }, (r) => ({
+      users: {
+        posts: r.many.posts(),
+      },
+      posts: {
+        author: r.one.users({
+          fields: [r.posts.authorId],
+          references: [r.users.id],
+        }),
+      },
+    }));
+
+    expect(relations).toBeDefined();
+    const defs = (relations as any).definitions;
+    expect(defs.users.posts.type).toBe("many");
+    expect(defs.posts.author.type).toBe("one");
+  });
+
+  it("should correctly extract metadata from centralized relations", () => {
+    const relations = defineRelations({ users, posts }, (r) => ({
+      users: {
+        posts: r.many.posts(),
+      },
+      posts: {
+        author: r.one.users({
+          fields: [r.posts.authorId],
+          references: [r.users.id],
+        }),
+      },
+    }));
+
+    const schema = { users, posts, relations };
+    const metadata = extractMetadata(schema);
+
+    expect(metadata.entities.users).toBeDefined();
+    expect(metadata.entities.users!.relations.posts).toBeDefined();
+    expect(metadata.entities.users!.relations.posts!.type).toBe("many");
+    expect(metadata.entities.posts).toBeDefined();
+    expect(metadata.entities.posts!.relations.author).toBeDefined();
+    expect(metadata.entities.posts!.relations.author!.type).toBe("one");
+
+    // Check column references
+    const authorRelation = metadata.entities.posts!.relations.author;
+    expect(authorRelation!.config.fields?.[0]).toBe(posts.authorId);
+    expect(authorRelation!.config.references?.[0]).toBe(users.id);
+  });
+
+  it("should maintain backward compatibility with single-entity defineRelations", () => {
+    const usersRelations = defineRelations(users, ({ many }) => ({
+      posts: many(posts),
+    }));
+
+    const schema = { users, posts, usersRelations };
+    const metadata = extractMetadata(schema);
+
+    expect(metadata.entities.users).toBeDefined();
+    expect(metadata.entities.users!.relations.posts).toBeDefined();
+    expect(metadata.entities.users!.relations.posts!.type).toBe("many");
+  });
+});