@tailor-platform/erp-kit 0.2.1 → 0.3.0

package/src/{modules/shared → shared}/defineCommand.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
+import { createMockDb } from "../testing/index";
 import { defineCommand } from "./defineCommand";
 import { InsufficientPermissionError } from "./errors";
 import type { CommandContext } from "./types";
@@ -12,19 +13,21 @@ 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 { db } = createMockDb();
 
-    const result = await command("fake-db", { foo: "bar" }, ctx);
+    const result = await command(db, { foo: "bar" }, ctx);
 
     expect(result).toEqual({ result: "ok" });
-    expect(impl).toHaveBeenCalledWith("fake-db", { foo: "bar" }, ctx, undefined);
+    expect(impl).toHaveBeenCalledWith(db, { foo: "bar" }, ctx);
   });
 
   it("returns InsufficientPermissionError when permission is missing", async () => {
     const impl = vi.fn();
     const command = defineCommand("mod:doThing", impl)();
     const denied: CommandContext = { actorId: "user-1", permissions: [] };
+    const { db } = createMockDb();
 
-    const result = await command("fake-db", {}, denied);
+    const result = await command(db, {}, denied);
     expect(result.ok).toBe(false);
     if (!result.ok) {
       expect(result.error).toBeInstanceOf(InsufficientPermissionError);
@@ -35,11 +38,12 @@ describe("defineCommand", () => {
   it("passes ctx to impl", async () => {
     const impl = vi.fn().mockResolvedValue({});
     const command = defineCommand("mod:doThing", impl)();
+    const { db } = createMockDb();
 
-    await command("fake-db", { x: 1 }, ctx);
+    await command(db, { x: 1 }, ctx);
 
     expect(impl).toHaveBeenCalledTimes(1);
-    expect(impl.mock.calls[0]).toHaveLength(4);
+    expect(impl.mock.calls[0]).toHaveLength(3);
     expect(impl.mock.calls[0][2]).toEqual(ctx);
   });
 
@@ -47,9 +51,21 @@ describe("defineCommand", () => {
     const impl = vi.fn().mockResolvedValue({ result: "ok" });
     const deps = { maxDepth: 10 };
     const command = defineCommand("mod:doThing", impl)(deps);
+    const { db } = createMockDb();
 
-    await command("fake-db", { x: 1 }, ctx);
+    await command(db, { x: 1 }, ctx);
 
-    expect(impl).toHaveBeenCalledWith("fake-db", { x: 1 }, ctx, deps);
+    expect(impl).toHaveBeenCalledWith(db, { x: 1 }, ctx, deps);
+  });
+
+  it("throws when db is not a transaction", async () => {
+    const impl = vi.fn().mockResolvedValue({ result: "ok" });
+    const command = defineCommand("mod:doThing", impl)();
+    const nonTransactionDb = { isTransaction: false } as never;
+
+    await expect(command(nonTransactionDb, {}, ctx)).rejects.toThrow(
+      "Commands require a transaction database",
+    );
+    expect(impl).not.toHaveBeenCalled();
   });
 });

package/src/{modules/shared → shared}/defineCommand.ts

@@ -1,3 +1,4 @@
+import type { Transaction } from "kysely";
 import type { Result } from "./result";
 import type { CommandContext } from "./types";
 import { requirePermission } from "./requirePermission";
@@ -5,7 +6,7 @@ import type { InsufficientPermissionError } from "./errors";
 
 export type Command<TInput, TReturn extends Result<unknown, Error>> = (
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  db: any,
+  db: Transaction<any>,
   input: TInput,
   ctx: CommandContext,
 ) => Promise<TReturn>;
@@ -14,19 +15,27 @@ type CommandResult<TReturn extends Result<unknown, Error>> =
   | TReturn
   | Result<never, InstanceType<typeof InsufficientPermissionError>>;
 
-export function defineCommand<TDeps, TInput, TReturn extends Result<unknown, Error>>(
+export function defineCommand<
+  TDeps extends unknown[],
+  TInput,
+  TReturn extends Result<unknown, Error>,
+>(
   permission: string,
   impl: (
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    db: any,
+    db: Transaction<any>,
     input: TInput,
     ctx: CommandContext,
-    deps?: TDeps,
+    ...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);
-  };
+): (...deps: TDeps) => Command<TInput, CommandResult<TReturn>> {
+  return (...deps) =>
+    async (db, input, ctx) => {
+      if (!db.isTransaction) {
+        throw new Error("Commands require a transaction database");
+      }
+      const check = requirePermission(ctx, permission);
+      if (!check.ok) return check;
+      return impl(db, input, ctx, ...deps);
+    };
 }

package/src/{modules/shared/internal.ts → shared/index.ts}

@@ -1,10 +1,18 @@
+export { createContext } from "./createContext";
 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, QueryContext, ReadonlyDB } from "./types";
+export type {
+  CommandContext,
+  QueryContext,
+  ReadonlyDB,
+  PaginationInput,
+  PaginatedResult,
+} from "./types";
+export { buildPaginatedResult, DEFAULT_PAGE_SIZE } from "./pagination";
 export type {
   InferSchema,
   Selectable,

package/src/shared/pagination.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { buildPaginatedResult, DEFAULT_PAGE_SIZE } from "./pagination";
+
+describe("buildPaginatedResult", () => {
+  it("returns empty result when no rows", () => {
+    const result = buildPaginatedResult([], DEFAULT_PAGE_SIZE);
+    expect(result).toEqual({ items: [], hasNextPage: false });
+  });
+
+  it("returns items without hasNextPage when rows < limit", () => {
+    const rows = [{ id: "1" }, { id: "2" }];
+    const result = buildPaginatedResult(rows, 10);
+    expect(result).toEqual({ items: rows, hasNextPage: false });
+  });
+
+  it("returns items with hasNextPage when rows = limit + 1", () => {
+    const rows = [{ id: "1" }, { id: "2" }, { id: "3" }];
+    const result = buildPaginatedResult(rows, 2);
+    expect(result).toEqual({
+      items: [{ id: "1" }, { id: "2" }],
+      hasNextPage: true,
+    });
+  });
+
+  it("returns items without hasNextPage when rows = limit exactly", () => {
+    const rows = [{ id: "1" }, { id: "2" }, { id: "3" }];
+    const result = buildPaginatedResult(rows, 3);
+    expect(result).toEqual({
+      items: rows,
+      hasNextPage: false,
+    });
+  });
+
+  it("includes total when provided", () => {
+    const rows = [{ id: "1" }];
+    const result = buildPaginatedResult(rows, 10, 42);
+    expect(result).toEqual({ items: rows, hasNextPage: false, total: 42 });
+  });
+
+  it("uses DEFAULT_PAGE_SIZE of 20", () => {
+    expect(DEFAULT_PAGE_SIZE).toBe(20);
+  });
+});

package/src/shared/pagination.ts

@@ -0,0 +1,22 @@
+import type { PaginatedResult } from "./types";
+
+export const DEFAULT_PAGE_SIZE = 20;
+
+/**
+ * Builds a PaginatedResult from rows fetched with limit+1 strategy.
+ * Caller should fetch `limit + 1` rows — the extra row determines hasNextPage.
+ */
+export function buildPaginatedResult<T>(
+  rows: T[],
+  limit: number,
+  total?: number,
+): PaginatedResult<T> {
+  const hasNextPage = rows.length > limit;
+  const items = hasNextPage ? rows.slice(0, limit) : rows;
+
+  const result: PaginatedResult<T> = { items, hasNextPage };
+  if (total !== undefined) {
+    result.total = total;
+  }
+  return result;
+}

package/src/{modules/shared → shared}/types.ts

@@ -10,3 +10,16 @@ export interface CommandContext {
 // 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">;
+
+export interface PaginationInput<TOrderBy extends string = never> {
+  limit?: number;
+  offset?: number;
+  orderBy?: "id" | TOrderBy;
+  orderDirection?: "asc" | "desc";
+}
+
+export interface PaginatedResult<T> {
+  items: T[];
+  total?: number;
+  hasNextPage: boolean;
+}

package/src/{modules/testing → testing}/index.ts

@@ -1,5 +1,5 @@
-import { vi, expect } from "vitest";
-import type { Kysely } from "kysely";
+import { vi, expect, type Mock } from "vitest";
+import type { Transaction } from "kysely";
 import {
   InsufficientPermissionError,
   type CommandContext,
@@ -7,9 +7,9 @@ import {
   type Result,
   type ErrorOf,
   type ValueOf,
-} from "../shared/internal";
+} from "../shared";
 
-export type Spy = ReturnType<typeof vi.fn>;
+export type Spy = Mock;
 
 export interface QueryBuilder {
   where(...args: unknown[]): QueryBuilder;
@@ -20,6 +20,9 @@ export interface QueryBuilder {
   returningAll(...args: unknown[]): QueryBuilder;
   set(...args: unknown[]): QueryBuilder;
   orderBy(...args: unknown[]): QueryBuilder;
+  limit(...args: unknown[]): QueryBuilder;
+  offset(...args: unknown[]): QueryBuilder;
+  forUpdate(): QueryBuilder;
   executeTakeFirst(): unknown;
   executeTakeFirstOrThrow(): unknown;
   execute(): unknown;
@@ -50,13 +53,16 @@ function makeBuilder(executeSpy: Spy, valuesSpy: Spy, setSpy: Spy): QueryBuilder
     return builder;
   };
   builder.orderBy = () => builder;
+  builder.limit = () => builder;
+  builder.offset = () => builder;
+  builder.forUpdate = () => builder;
   builder.executeTakeFirst = () => executeSpy();
   builder.executeTakeFirstOrThrow = () => executeSpy();
   builder.execute = () => executeSpy();
   return builder;
 }
 
-export function createMockDb<T = Kysely<Record<string, unknown>>>(): {
+export function createMockDb<T = Transaction<Record<string, unknown>>>(): {
   db: T;
   spies: MockDbSpies;
   reset: () => void;
@@ -69,6 +75,7 @@ export function createMockDb<T = Kysely<Record<string, unknown>>>(): {
   const set = vi.fn();
 
   const db = {
+    isTransaction: true as const,
     selectFrom: () => makeBuilder(select, values, set),
     updateTable: () => makeBuilder(update, values, set),
     insertInto: () => makeBuilder(insert, values, set),
@@ -92,12 +99,12 @@ export function createMockDb<T = Kysely<Record<string, unknown>>>(): {
 export function testNotFound<TInput, TReturn extends Result<unknown, Error>>(
   command: Command<TInput, TReturn>,
   input: TInput,
-  ctx: CommandContext,
   expectedError: abstract new (...args: never[]) => ErrorOf<TReturn>,
 ) {
   return async () => {
     const { db, spies } = createMockDb();
     spies.select.mockReturnValue(undefined);
+    const ctx: CommandContext = { actorId: "test-actor", permissions: [] };
     const result = await command(db, input, ctx);
     expect(result.ok).toBe(false);
     if (!result.ok) {
@@ -128,13 +135,13 @@ export function testIdempotent<
 >(
   command: Command<TInput, TReturn>,
   input: TInput,
-  ctx: CommandContext,
   existingEntity: Record<string, unknown>,
   entityKey: TKey,
 ) {
   return async () => {
     const { db, spies } = createMockDb();
     spies.select.mockReturnValue(existingEntity);
+    const ctx: CommandContext = { actorId: "test-actor", permissions: [] };
     const result = await command(db, input, ctx);
     expect(result.ok).toBe(true);
     if (result.ok) {

package/src/testing.ts

@@ -6,5 +6,5 @@ export {
   type Spy,
   type QueryBuilder,
   type MockDbSpies,
-} from "./modules/testing/index";
+} from "./testing/index";
 export { createMockServer, type MockServer } from "./mockServer";

package/src/util.ts

@@ -1,3 +1,11 @@
+import fs from "node:fs";
 import path from "node:path";
 
 export const PACKAGE_ROOT = path.resolve(import.meta.dirname, "..");
+
+export function readErpKitVersion(): string {
+  const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf-8")) as {
+    version: string;
+  };
+  return pkg.version;
+}

package/templates/config/license.config.json

@@ -0,0 +1,4 @@
+{
+  "groups": ["reciprocal", "notice", "unencumbered"],
+  "allow": ["BlueOak-1.0.0", "WTFPL", "Unknown"]
+}

package/templates/scaffold/app/backend/.env.example

@@ -0,0 +1 @@
+TAILOR_PLATFORM_WORKSPACE_ID=

package/templates/scaffold/app/backend/__dot__gitignore

@@ -0,0 +1,4 @@
+.env
+.tailor-sdk/
+node_modules/
+.eslintcache

package/templates/scaffold/app/backend/eslint.config.js

@@ -0,0 +1,32 @@
+import eslint from "@eslint/js";
+import { defineConfig, globalIgnores } from "eslint/config";
+import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
+import importX from "eslint-plugin-import-x";
+import tseslint from "typescript-eslint";
+
+export default defineConfig([
+  globalIgnores([".tailor-sdk/", "seed/", "src/generated/", "tailor.d.ts"]),
+  {
+    files: ["**/*.ts"],
+    extends: [
+      eslint.configs.recommended,
+      tseslint.configs.recommendedTypeChecked,
+      tseslint.configs.stylisticTypeChecked,
+      importX.flatConfigs.recommended,
+      importX.flatConfigs.typescript,
+    ],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    settings: {
+      "import-x/resolver-next": [createTypeScriptImportResolver()],
+    },
+    rules: {
+      "import-x/order": "error",
+      "import-x/no-unresolved": ["error", { ignore: ["^@tailor-platform/"] }],
+    },
+  },
+]);

package/templates/scaffold/app/backend/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "template-app-backend",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "generate": "tailor-sdk generate",
+    "deploy": "tailor-sdk apply --env-file-if-exists .env",
+    "deploy:frontend": "tailor-sdk staticwebsite deploy --dir ../frontend/dist --name default-web --env-file-if-exists .env",
+    "lint": "eslint --cache .",
+    "lint:fix": "eslint --cache --fix .",
+    "seed": "node --env-file-if-exists=.env seed/exec.mjs",
+    "seed:reset": "node --env-file-if-exists=.env seed/exec.mjs --truncate --yes",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tailor-platform/erp-kit": "workspace:*",
+    "@tailor-platform/function-kysely-tailordb": "0.1.3",
+    "@tailor-platform/sdk": "1.25.1",
+    "kysely": "0.28.11"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.4",
+    "@tailor-platform/function-types": "0.8.2",
+    "@types/node": "24.12.0",
+    "eslint": "9.39.4",
+    "eslint-import-resolver-typescript": "4.4.4",
+    "eslint-plugin-import-x": "4.16.2",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.57.0"
+  }
+}

package/templates/scaffold/app/backend/seed/data/Permission.schema.ts

@@ -0,0 +1,20 @@
+import { t } from "@tailor-platform/sdk";
+import { defineSchema } from "@tailor-platform/sdk/seed";
+import { createTailorDBHook, createStandardSchema } from "@tailor-platform/sdk/test";
+import { permission } from "../../src/modules";
+
+const schemaType = t.object({
+  ...permission.pickFields(["id","createdAt"], { optional: true }),
+  ...permission.omitFields(["id","createdAt"]),
+});
+
+const hook = createTailorDBHook(permission);
+
+export const schema = defineSchema(
+  createStandardSchema(schemaType, hook),
+  {
+    indexes: [
+      {"name":"permission_key_unique_idx","columns":["key"],"unique":true},
+    ],
+  }
+);

package/templates/scaffold/app/backend/seed/data/Role.schema.ts

@@ -0,0 +1,20 @@
+import { t } from "@tailor-platform/sdk";
+import { defineSchema } from "@tailor-platform/sdk/seed";
+import { createTailorDBHook, createStandardSchema } from "@tailor-platform/sdk/test";
+import { role } from "../../src/modules";
+
+const schemaType = t.object({
+  ...role.pickFields(["id","createdAt"], { optional: true }),
+  ...role.omitFields(["id","createdAt"]),
+});
+
+const hook = createTailorDBHook(role);
+
+export const schema = defineSchema(
+  createStandardSchema(schemaType, hook),
+  {
+    indexes: [
+      {"name":"role_name_unique_idx","columns":["name"],"unique":true},
+    ],
+  }
+);

package/templates/scaffold/app/backend/seed/data/RolePermission.schema.ts

@@ -0,0 +1,24 @@
+import { t } from "@tailor-platform/sdk";
+import { defineSchema } from "@tailor-platform/sdk/seed";
+import { createTailorDBHook, createStandardSchema } from "@tailor-platform/sdk/test";
+import { rolePermission } from "../../src/modules";
+
+const schemaType = t.object({
+  ...rolePermission.pickFields(["id","createdAt"], { optional: true }),
+  ...rolePermission.omitFields(["id","createdAt"]),
+});
+
+const hook = createTailorDBHook(rolePermission);
+
+export const schema = defineSchema(
+  createStandardSchema(schemaType, hook),
+  {
+    foreignKeys: [
+      {"column":"roleId","references":{"table":"Role","column":"id"}},
+      {"column":"permissionId","references":{"table":"Permission","column":"id"}},
+    ],
+    indexes: [
+      {"name":"role_permission_unique_idx","columns":["roleId","permissionId"],"unique":true},
+    ],
+  }
+);

package/templates/scaffold/app/backend/seed/data/User.jsonl

@@ -0,0 +1 @@
+{"email":"test@example.com","name":"Demo User","status":"ACTIVE","permissions":["user-management:createUser"]}

package/templates/scaffold/app/backend/seed/data/User.schema.ts

@@ -0,0 +1,20 @@
+import { t } from "@tailor-platform/sdk";
+import { defineSchema } from "@tailor-platform/sdk/seed";
+import { createTailorDBHook, createStandardSchema } from "@tailor-platform/sdk/test";
+import { user } from "../../src/modules";
+
+const schemaType = t.object({
+  ...user.pickFields(["id","createdAt"], { optional: true }),
+  ...user.omitFields(["id","createdAt"]),
+});
+
+const hook = createTailorDBHook(user);
+
+export const schema = defineSchema(
+  createStandardSchema(schemaType, hook),
+  {
+    indexes: [
+      {"name":"user_email_unique_idx","columns":["email"],"unique":true},
+    ],
+  }
+);

package/templates/scaffold/app/backend/seed/data/UserRole.schema.ts

@@ -0,0 +1,24 @@
+import { t } from "@tailor-platform/sdk";
+import { defineSchema } from "@tailor-platform/sdk/seed";
+import { createTailorDBHook, createStandardSchema } from "@tailor-platform/sdk/test";
+import { userRole } from "../../src/modules";
+
+const schemaType = t.object({
+  ...userRole.pickFields(["id","createdAt"], { optional: true }),
+  ...userRole.omitFields(["id","createdAt"]),
+});
+
+const hook = createTailorDBHook(userRole);
+
+export const schema = defineSchema(
+  createStandardSchema(schemaType, hook),
+  {
+    foreignKeys: [
+      {"column":"userId","references":{"table":"User","column":"id"}},
+      {"column":"roleId","references":{"table":"Role","column":"id"}},
+    ],
+    indexes: [
+      {"name":"user_role_unique_idx","columns":["userId","roleId"],"unique":true},
+    ],
+  }
+);

package/templates/scaffold/app/backend/seed/data/_User.jsonl

@@ -0,0 +1 @@
+{"name":"test@example.com","password":"password"}

package/templates/scaffold/app/backend/seed/data/_User.schema.ts

@@ -0,0 +1,30 @@
+import { t } from "@tailor-platform/sdk";
+import { defineSchema } from "@tailor-platform/sdk/seed";
+import { createStandardSchema } from "@tailor-platform/sdk/test";
+
+const schemaType = t.object({
+  name: t.string(),
+  password: t.string(),
+});
+
+// Simple identity hook for _User (no TailorDB backing type)
+const hook = <T>(data: unknown) => data as T;
+
+export const schema = defineSchema(
+  createStandardSchema(schemaType, hook),
+  {
+    primaryKey: "name",
+    indexes: [
+      { name: "_user_name_unique_idx", columns: ["name"], unique: true },
+    ],
+    foreignKeys: [
+      {
+        column: "name",
+        references: {
+          table: "User",
+          column: "email",
+        },
+      },
+    ],
+  }
+);