@tailor-platform/erp-kit 0.1.1 → 0.2.0

package/src/modules/primitives/query/convertQuantity.ts

@@ -0,0 +1,63 @@
+import type { ReadonlyDB, QueryContext } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+import {
+  InactiveUnitError,
+  IncompatibleUnitsError,
+  UnitNotFoundError,
+} from "../lib/errors.generated";
+import { getUnit } from "./getUnit.generated";
+
+export interface ConvertQuantityInput {
+  quantity: number;
+  sourceUnitSymbol: string;
+  targetUnitSymbol: string;
+}
+
+/**
+ * Converts a quantity from one unit of measure to another within the same category.
+ * Units are identified by their symbol (e.g., "kg", "lb", "g").
+ * The conversion uses each unit's conversion factor relative to the category's reference unit.
+ * Result is rounded to the target unit's precision setting.
+ */
+export async function run(db: ReadonlyDB<DB>, input: ConvertQuantityInput, ctx: QueryContext) {
+  // Validate source unit exists
+  const { unit: sourceUnit } = await getUnit(db, { symbol: input.sourceUnitSymbol }, ctx);
+
+  if (!sourceUnit) {
+    throw new UnitNotFoundError(input.sourceUnitSymbol);
+  }
+
+  // Validate target unit exists
+  const { unit: targetUnit } = await getUnit(db, { symbol: input.targetUnitSymbol }, ctx);
+
+  if (!targetUnit) {
+    throw new UnitNotFoundError(input.targetUnitSymbol);
+  }
+
+  // Validate both units are active
+  if (!sourceUnit.isActive) {
+    throw new InactiveUnitError(input.sourceUnitSymbol);
+  }
+
+  if (!targetUnit.isActive) {
+    throw new InactiveUnitError(input.targetUnitSymbol);
+  }
+
+  // Validate units belong to the same category
+  if (sourceUnit.categoryId !== targetUnit.categoryId) {
+    throw new IncompatibleUnitsError(`${input.sourceUnitSymbol} and ${input.targetUnitSymbol}`);
+  }
+
+  // Perform conversion: result = quantity * sourceConversionFactor / targetConversionFactor
+  const rawResult = (input.quantity * sourceUnit.conversionFactor) / targetUnit.conversionFactor;
+
+  // Apply rounding to target unit's precision
+  const roundingFactor = Math.pow(10, targetUnit.roundingPrecision);
+  const convertedQuantity = Math.round(rawResult * roundingFactor) / roundingFactor;
+
+  return {
+    convertedQuantity,
+    sourceUnit,
+    targetUnit,
+  };
+}

package/src/modules/primitives/query/getBaseCurrency.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { defineQuery } from "../../shared/internal";
+import { run } from "./getBaseCurrency";
+
+export const getBaseCurrency = defineQuery(run);

package/src/modules/primitives/query/getBaseCurrency.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import type { QueryContext } from "../../shared/internal";
+import { baseCurrencyUSD } from "../testing/fixtures";
+import { getBaseCurrency } from "./getBaseCurrency.generated";
+
+describe("getBaseCurrency", () => {
+  const ctx: QueryContext = { actorId: "test-actor" };
+
+  it("returns base currency when set", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(baseCurrencyUSD);
+
+    const result = await getBaseCurrency(db, undefined, ctx);
+
+    expect(result.currency).toEqual(baseCurrencyUSD);
+  });
+
+  it("returns null when no base currency is set", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(undefined);
+
+    const result = await getBaseCurrency(db, undefined, ctx);
+
+    expect(result.currency).toBeNull();
+  });
+});

package/src/modules/primitives/query/getBaseCurrency.ts

@@ -0,0 +1,16 @@
+import type { ReadonlyDB } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+/**
+ * Retrieves the currency designated as the base currency.
+ * Returns null if no base currency has been set.
+ */
+export async function run(db: ReadonlyDB<DB>) {
+  const currency = await db
+    .selectFrom("Currency")
+    .selectAll()
+    .where("isBaseCurrency", "=", true)
+    .executeTakeFirst();
+
+  return { currency: currency ?? null };
+}

package/src/modules/primitives/query/getCurrency.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { defineQuery } from "../../shared/internal";
+import { run } from "./getCurrency";
+
+export const getCurrency = defineQuery(run);

package/src/modules/primitives/query/getCurrency.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseCurrencyUSD } from "../testing/fixtures";
+import { run } from "./getCurrency";
+
+describe("getCurrency", () => {
+  describe("by id", () => {
+    it("returns currency when found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(baseCurrencyUSD);
+
+      const result = await run(db, { id: "currency-usd" });
+
+      expect(result.currency).toEqual(baseCurrencyUSD);
+    });
+
+    it("returns null when currency not found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(undefined);
+
+      const result = await run(db, { id: "nonexistent" });
+
+      expect(result.currency).toBeNull();
+    });
+  });
+
+  describe("by code", () => {
+    it("returns currency when found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(baseCurrencyUSD);
+
+      const result = await run(db, { code: "USD" });
+
+      expect(result.currency).toEqual(baseCurrencyUSD);
+    });
+
+    it("returns null when currency not found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(undefined);
+
+      const result = await run(db, { code: "NONEXISTENT" });
+
+      expect(result.currency).toBeNull();
+    });
+  });
+});

package/src/modules/primitives/query/getCurrency.ts

@@ -0,0 +1,18 @@
+import type { ReadonlyDB } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+export type GetCurrencyInput = { id: string } | { code: string };
+
+export async function run(db: ReadonlyDB<DB>, input: GetCurrencyInput) {
+  let query = db.selectFrom("Currency").selectAll();
+
+  if ("id" in input) {
+    query = query.where("id", "=", input.id);
+  } else {
+    query = query.where("code", "=", input.code);
+  }
+
+  const currency = await query.executeTakeFirst();
+
+  return { currency: currency ?? null };
+}

package/src/modules/primitives/query/getUnit.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { defineQuery } from "../../shared/internal";
+import { run } from "./getUnit";
+
+export const getUnit = defineQuery(run);

package/src/modules/primitives/query/getUnit.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseUnitKg } from "../testing/fixtures";
+import { run } from "./getUnit";
+
+describe("getUnit", () => {
+  describe("by id", () => {
+    it("returns unit when found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(baseUnitKg);
+
+      const result = await run(db, { id: "unit-kg" });
+
+      expect(result.unit).toEqual(baseUnitKg);
+    });
+
+    it("returns null when unit not found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(undefined);
+
+      const result = await run(db, { id: "nonexistent" });
+
+      expect(result.unit).toBeNull();
+    });
+  });
+
+  describe("by symbol", () => {
+    it("returns unit when found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(baseUnitKg);
+
+      const result = await run(db, { symbol: "kg" });
+
+      expect(result.unit).toEqual(baseUnitKg);
+    });
+
+    it("returns null when unit not found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(undefined);
+
+      const result = await run(db, { symbol: "nonexistent" });
+
+      expect(result.unit).toBeNull();
+    });
+  });
+});

package/src/modules/primitives/query/getUnit.ts

@@ -0,0 +1,18 @@
+import type { ReadonlyDB } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+export type GetUnitInput = { id: string } | { symbol: string };
+
+export async function run(db: ReadonlyDB<DB>, input: GetUnitInput) {
+  let query = db.selectFrom("Unit").selectAll();
+
+  if ("id" in input) {
+    query = query.where("id", "=", input.id);
+  } else {
+    query = query.where("symbol", "=", input.symbol);
+  }
+
+  const unit = await query.executeTakeFirst();
+
+  return { unit: unit ?? null };
+}

package/src/modules/primitives/query/getUoMCategory.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { defineQuery } from "../../shared/internal";
+import { run } from "./getUoMCategory";
+
+export const getUoMCategory = defineQuery(run);

package/src/modules/primitives/query/getUoMCategory.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseUoMCategory } from "../testing/fixtures";
+import { run } from "./getUoMCategory";
+
+describe("getUoMCategory", () => {
+  describe("by id", () => {
+    it("returns category when found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(baseUoMCategory);
+
+      const result = await run(db, { id: "category-1" });
+
+      expect(result.uoMCategory).toEqual(baseUoMCategory);
+    });
+
+    it("returns null when category not found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(undefined);
+
+      const result = await run(db, { id: "nonexistent" });
+
+      expect(result.uoMCategory).toBeNull();
+    });
+  });
+
+  describe("by name", () => {
+    it("returns category when found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(baseUoMCategory);
+
+      const result = await run(db, { name: "Weight" });
+
+      expect(result.uoMCategory).toEqual(baseUoMCategory);
+    });
+
+    it("returns null when category not found", async () => {
+      const { db, spies } = createMockDb<DB>();
+      spies.select.mockReturnValue(undefined);
+
+      const result = await run(db, { name: "Nonexistent" });
+
+      expect(result.uoMCategory).toBeNull();
+    });
+  });
+});

package/src/modules/primitives/query/getUoMCategory.ts

@@ -0,0 +1,18 @@
+import type { ReadonlyDB } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+export type GetUoMCategoryInput = { id: string } | { name: string };
+
+export async function run(db: ReadonlyDB<DB>, input: GetUoMCategoryInput) {
+  let query = db.selectFrom("UoMCategory").selectAll();
+
+  if ("id" in input) {
+    query = query.where("id", "=", input.id);
+  } else {
+    query = query.where("name", "=", input.name);
+  }
+
+  const uoMCategory = await query.executeTakeFirst();
+
+  return { uoMCategory: uoMCategory ?? null };
+}

package/src/modules/primitives/query/listUnitsByCategory.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { defineQuery } from "../../shared/internal";
+import { run } from "./listUnitsByCategory";
+
+export const listUnitsByCategory = defineQuery(run);

package/src/modules/primitives/query/listUnitsByCategory.ts

@@ -0,0 +1,16 @@
+import type { ReadonlyDB } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+export interface ListUnitsByCategoryInput {
+  categoryId: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: ListUnitsByCategoryInput) {
+  const units = await db
+    .selectFrom("Unit")
+    .selectAll()
+    .where("categoryId", "=", input.categoryId)
+    .execute();
+
+  return { units };
+}

package/src/modules/primitives/tailor.config.ts

@@ -2,10 +2,10 @@ import { defineConfig, defineGenerators } from "@tailor-platform/sdk";
 
 export default defineConfig({
   name: "primitives",
-  db: { "main-db": { files: [`./src/db/*.ts`] } },
+  db: { "main-db": { files: [`./db/*.ts`] } },
 });
 
 export const generators = defineGenerators(
-  ["@tailor-platform/kysely-type", { distPath: `./src/generated/kysely-tailordb.ts` }],
-  ["@tailor-platform/enum-constants", { distPath: "./src/generated/enums.ts" }],
+  ["@tailor-platform/kysely-type", { distPath: `./generated/kysely-tailordb.ts` }],
+  ["@tailor-platform/enum-constants", { distPath: "./generated/enums.ts" }],
 );

package/src/modules/shared/defineCommand.test.ts

@@ -11,32 +11,45 @@ describe("defineCommand", () => {
 
   it("calls impl with db and input when permission is present", async () => {
     const impl = vi.fn().mockResolvedValue({ result: "ok" });
-    const command = defineCommand("mod:doThing", impl);
+    const command = defineCommand("mod:doThing", impl)();
 
     const result = await command("fake-db", { foo: "bar" }, ctx);
 
     expect(result).toEqual({ result: "ok" });
-    expect(impl).toHaveBeenCalledWith("fake-db", { foo: "bar" });
+    expect(impl).toHaveBeenCalledWith("fake-db", { foo: "bar" }, ctx, undefined);
   });
 
-  it("throws InsufficientPermissionError when permission is missing", async () => {
+  it("returns InsufficientPermissionError when permission is missing", async () => {
     const impl = vi.fn();
-    const command = defineCommand("mod:doThing", impl);
+    const command = defineCommand("mod:doThing", impl)();
     const denied: CommandContext = { actorId: "user-1", permissions: [] };
 
-    await expect(command("fake-db", {}, denied)).rejects.toBeInstanceOf(
-      InsufficientPermissionError,
-    );
+    const result = await command("fake-db", {}, denied);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InsufficientPermissionError);
+    }
     expect(impl).not.toHaveBeenCalled();
   });
 
-  it("does not pass ctx to impl", async () => {
+  it("passes ctx to impl", async () => {
     const impl = vi.fn().mockResolvedValue({});
-    const command = defineCommand("mod:doThing", impl);
+    const command = defineCommand("mod:doThing", impl)();
 
     await command("fake-db", { x: 1 }, ctx);
 
     expect(impl).toHaveBeenCalledTimes(1);
-    expect(impl.mock.calls[0]).toHaveLength(2);
+    expect(impl.mock.calls[0]).toHaveLength(4);
+    expect(impl.mock.calls[0][2]).toEqual(ctx);
+  });
+
+  it("passes deps to impl when provided", async () => {
+    const impl = vi.fn().mockResolvedValue({ result: "ok" });
+    const deps = { maxDepth: 10 };
+    const command = defineCommand("mod:doThing", impl)(deps);
+
+    await command("fake-db", { x: 1 }, ctx);
+
+    expect(impl).toHaveBeenCalledWith("fake-db", { x: 1 }, ctx, deps);
   });
 });

package/src/modules/shared/defineCommand.ts

@@ -1,19 +1,32 @@
+import type { Result } from "./result";
 import type { CommandContext } from "./types";
 import { requirePermission } from "./requirePermission";
+import type { InsufficientPermissionError } from "./errors";
 
-export type Command<TInput, TResult> = (
-  db: unknown,
+export type Command<TInput, TReturn extends Result<unknown, Error>> = (
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  db: any,
   input: TInput,
   ctx: CommandContext,
-) => Promise<TResult>;
+) => Promise<TReturn>;
+
+type CommandResult<TReturn extends Result<unknown, Error>> =
+  | TReturn
+  | Result<never, InstanceType<typeof InsufficientPermissionError>>;
 
-export function defineCommand<TInput, TResult>(
+export function defineCommand<TDeps, TInput, TReturn extends Result<unknown, Error>>(
   permission: string,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  impl: (db: any, input: TInput) => Promise<TResult>,
-): Command<TInput, TResult> {
-  return async (db, input, ctx) => {
-    requirePermission(ctx, permission);
-    return impl(db, input);
+  impl: (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    db: any,
+    input: TInput,
+    ctx: CommandContext,
+    deps?: TDeps,
+  ) => Promise<TReturn>,
+): (deps?: TDeps) => Command<TInput, CommandResult<TReturn>> {
+  return (deps) => async (db, input, ctx) => {
+    const check = requirePermission(ctx, permission);
+    if (!check.ok) return check;
+    return impl(db, input, ctx, deps);
   };
 }

package/src/modules/shared/defineQuery.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it, vi } from "vitest";
+import { defineQuery } from "./defineQuery";
+import type { QueryContext } from "./types";
+
+describe("defineQuery", () => {
+  const ctx: QueryContext = { actorId: "user-1" };
+
+  it("calls impl with db, input, and ctx", async () => {
+    const impl = vi.fn().mockResolvedValue({ result: "ok" });
+    const query = defineQuery(impl);
+
+    const result = await query("fake-db", { foo: "bar" }, ctx);
+
+    expect(result).toEqual({ result: "ok" });
+    expect(impl).toHaveBeenCalledWith("fake-db", { foo: "bar" }, ctx);
+  });
+
+  it("passes ctx with actorId to impl", async () => {
+    const impl = vi.fn().mockResolvedValue({});
+    const query = defineQuery(impl);
+
+    await query("fake-db", { x: 1 }, ctx);
+
+    expect(impl).toHaveBeenCalledTimes(1);
+    expect(impl.mock.calls[0]).toHaveLength(3);
+    expect(impl.mock.calls[0][2]).toEqual({ actorId: "user-1" });
+  });
+});

package/src/modules/shared/defineQuery.ts

@@ -0,0 +1,16 @@
+import type { QueryContext } from "./types";
+
+export type Query<TInput, TResult> = (
+  db: unknown,
+  input: TInput,
+  ctx: QueryContext,
+) => Promise<TResult>;
+
+export function defineQuery<TInput, TResult>(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  impl: (db: any, input: TInput, ctx: QueryContext) => Promise<TResult>,
+): Query<TInput, TResult> {
+  return async (db, input, ctx) => {
+    return impl(db, input, ctx);
+  };
+}

package/src/modules/shared/internal.ts

@@ -1,8 +1,10 @@
 export { defineCommand, type Command } from "./defineCommand";
+export { ok, err, type Result, type ValueOf, type ErrorOf } from "./result";
+export { defineQuery, type Query } from "./defineQuery";
 export { definePermissions } from "./definePermissions";
 export { requirePermission } from "./requirePermission";
 export { createDomainError, InsufficientPermissionError } from "./errors";
-export type { CommandContext } from "./types";
+export type { CommandContext, QueryContext, ReadonlyDB } from "./types";
 export type {
   InferSchema,
   Selectable,

package/src/modules/shared/requirePermission.test.ts

@@ -13,35 +13,36 @@ describe("requirePermission", () => {
     ],
   };
 
-  it("does not throw when permission is present", () => {
-    expect(() => requirePermission(ctx, "primitives:createCategory")).not.toThrow();
-    expect(() => requirePermission(ctx, "inventory:createItem")).not.toThrow();
+  it("returns ok when permission is present", () => {
+    expect(requirePermission(ctx, "primitives:createCategory").ok).toBe(true);
+    expect(requirePermission(ctx, "inventory:createItem").ok).toBe(true);
   });
 
-  it("throws InsufficientPermissionError when permission is missing", () => {
-    expect(() => requirePermission(ctx, "primitives:deleteCategory")).toThrow(
-      InsufficientPermissionError,
-    );
+  it("returns InsufficientPermissionError when permission is missing", () => {
+    const result = requirePermission(ctx, "primitives:deleteCategory");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InsufficientPermissionError);
+    }
   });
 
   it("includes actorId and permission key in error", () => {
-    try {
-      requirePermission(ctx, "orders:createOrder");
-      expect.fail("Should have thrown");
-    } catch (err) {
-      const error = err as InstanceType<typeof InsufficientPermissionError>;
-      expect(error.name).toBe("InsufficientPermissionError");
-      expect(error.code).toBe("INSUFFICIENT_PERMISSION");
-      expect(error.message).toContain("user-1");
-      expect(error.message).toContain("orders:createOrder");
+    const result = requirePermission(ctx, "orders:createOrder");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.name).toBe("InsufficientPermissionError");
+      expect(result.error.code).toBe("INSUFFICIENT_PERMISSION");
+      expect(result.error.message).toContain("user-1");
+      expect(result.error.message).toContain("orders:createOrder");
     }
   });
 
-  it("throws when permissions array is empty", () => {
+  it("returns error when permissions array is empty", () => {
     const emptyCtx: CommandContext = { actorId: "user-2", permissions: [] };
-
-    expect(() => requirePermission(emptyCtx, "primitives:createCategory")).toThrow(
-      InsufficientPermissionError,
-    );
+    const result = requirePermission(emptyCtx, "primitives:createCategory");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InsufficientPermissionError);
+    }
   });
 });

package/src/modules/shared/requirePermission.ts

@@ -1,8 +1,14 @@
 import type { CommandContext } from "./types";
+import type { Result } from "./result";
 import { InsufficientPermissionError } from "./errors";
+import { ok, err } from "./result";
 
-export function requirePermission(ctx: CommandContext, key: string): void {
+export function requirePermission(
+  ctx: CommandContext,
+  key: string,
+): Result<void, InstanceType<typeof InsufficientPermissionError>> {
   if (!ctx.permissions.includes(key)) {
-    throw new InsufficientPermissionError(ctx.actorId, key);
+    return err(new InsufficientPermissionError(ctx.actorId, key));
   }
+  return ok(undefined);
 }

package/src/modules/shared/result.ts

@@ -0,0 +1,12 @@
+export type Result<T, E extends Error = never> = { ok: true; value: T } | { ok: false; error: E };
+
+export type ValueOf<R> = R extends { ok: true; value: infer T } ? T : never;
+export type ErrorOf<R> = R extends { ok: false; error: infer E } ? E : never;
+
+export function ok<T>(value: T): { ok: true; value: T } {
+  return { ok: true, value };
+}
+
+export function err<E extends Error>(error: E): { ok: false; error: E } {
+  return { ok: false, error };
+}

package/src/modules/shared/types.ts

@@ -1,4 +1,12 @@
+export interface QueryContext {
+  actorId: string;
+}
+
 export interface CommandContext {
   actorId: string;
   permissions: readonly string[];
 }
+
+// Strips write methods (updateTable, insertInto, deleteFrom) from a Kysely DB instance.
+// Query handlers use this instead of the full DB type to get compile-time write prevention.
+export type ReadonlyDB<T extends { selectFrom: unknown }> = Pick<T, "selectFrom">;