@porulle/core 0.64.0 → 0.65.0

package/src/kernel/module/topo-sort.ts

@@ -1,99 +0,0 @@
-import type { AppModule } from "./define.js";
-
-export class ModuleCycleError extends Error {
-  readonly cycle: string[];
-
-  constructor(cycle: string[]) {
-    const label = cycle.join(" → ");
-    super(`Module dependency cycle: ${label}`);
-    this.name = "ModuleCycleError";
-    this.cycle = cycle;
-  }
-}
-
-export function topoSortModules(modules: Record<string, AppModule>): string[] {
-  const keys = Object.keys(modules);
-  const keySet = new Set(keys);
-
-  for (const [id, mod] of Object.entries(modules)) {
-    for (const dep of mod.dependencies ?? []) {
-      const depKey = dep as string;
-      if (!keySet.has(depKey)) {
-        throw new Error(`Module "${id}" declares unknown dependency "${depKey}"`);
-      }
-    }
-  }
-
-  const remaining = new Map<string, Set<string>>();
-  for (const k of keys) {
-    const mod = modules[k]!;
-    remaining.set(k, new Set((mod.dependencies ?? []) as string[]));
-  }
-
-  const waitingOn = new Map<string, string[]>();
-  for (const m of keys) {
-    const mod = modules[m]!;
-    for (const d of (mod.dependencies ?? []) as string[]) {
-      const list = waitingOn.get(d);
-      if (list) list.push(m);
-      else waitingOn.set(d, [m]);
-    }
-  }
-
-  const order: string[] = [];
-  const queue = keys.filter((k) => remaining.get(k)!.size === 0);
-
-  while (queue.length > 0) {
-    const n = queue.shift()!;
-    order.push(n);
-    for (const m of waitingOn.get(n) ?? []) {
-      const set = remaining.get(m)!;
-      if (set.delete(n) && set.size === 0) {
-        queue.push(m);
-      }
-    }
-  }
-
-  if (order.length !== keys.length) {
-    const cycle = findCycleKeys(modules, keys);
-    throw new ModuleCycleError(cycle);
-  }
-
-  return order;
-}
-
-function findCycleKeys(modules: Record<string, AppModule>, keys: string[]): string[] {
-  const WHITE = 0;
-  const GRAY = 1;
-  const BLACK = 2;
-  const mark = new Map<string, number>();
-  const stack: string[] = [];
-
-  function dfs(u: string): string[] | null {
-    mark.set(u, GRAY);
-    stack.push(u);
-    const mod = modules[u]!;
-    for (const v of (mod.dependencies ?? []) as string[]) {
-      const mv = mark.get(v) ?? WHITE;
-      if (mv === WHITE) {
-        const found = dfs(v);
-        if (found) return found;
-      } else if (mv === GRAY) {
-        const idx = stack.indexOf(v);
-        return [...stack.slice(idx), v];
-      }
-    }
-    stack.pop();
-    mark.set(u, BLACK);
-    return null;
-  }
-
-  for (const k of keys) {
-    if ((mark.get(k) ?? WHITE) === WHITE) {
-      const found = dfs(k);
-      if (found) return found;
-    }
-  }
-
-  throw new Error("topoSortModules: expected a cycle but DFS did not find one");
-}

package/src/kernel/query/executor.ts

@@ -1,184 +0,0 @@
-import { CommerceNotFoundError } from "../errors.js";
-import type {
-  QueryRegistry,
-  EntityDefinition,
-  RelationDefinition,
-} from "./registry.js";
-
-export interface QueryInput {
-  entity: string;
-  id?: string;
-  filters?: Record<string, unknown>;
-  include?: string[];
-  pagination?: { limit?: number; offset?: number };
-}
-
-export interface QueryResult<T = Record<string, unknown>> {
-  data: T[];
-  total?: number | undefined;
-}
-
-/**
- * Executes a query against the registry, resolving includes via
- * batched dataloader-style fetches (one WHERE IN per relation).
- */
-export async function executeQuery<T = Record<string, unknown>>(
-  registry: QueryRegistry,
-  services: Record<string, unknown>,
-  input: QueryInput,
-): Promise<QueryResult<T>> {
-  const definition = registry.get(input.entity);
-  if (!definition) {
-    throw new CommerceNotFoundError(
-      `No entity registered with name "${input.entity}".`,
-    );
-  }
-
-  const service = services[definition.service] as Record<
-    string,
-    (...args: unknown[]) => Promise<unknown>
-  >;
-
-  // 1. Fetch primary records
-  let rows: Record<string, unknown>[];
-  let total: number | undefined;
-
-  if (input.id) {
-    const result = (await service[definition.getByIdMethod]!(
-      input.id,
-    )) as { ok?: boolean; value?: unknown };
-    const value = result?.value ?? result;
-    rows = value != null ? [value as Record<string, unknown>] : [];
-  } else {
-    const result = (await service[definition.listMethod]!(
-      input.filters ?? {},
-      input.pagination,
-    )) as {
-      ok?: boolean;
-      value?: { items?: unknown[]; total?: number };
-    };
-    const resolved = result?.value ?? result;
-    if (resolved && typeof resolved === "object" && "items" in resolved) {
-      rows = (resolved.items ?? []) as Record<string, unknown>[];
-      total = resolved.total;
-    } else if (Array.isArray(resolved)) {
-      rows = resolved as Record<string, unknown>[];
-    } else {
-      rows = [];
-    }
-  }
-
-  // 2. Resolve includes
-  if (input.include?.length) {
-    await resolveIncludes(rows, input.include, definition, services, registry);
-  }
-
-  return { data: rows as T[], total };
-}
-
-async function resolveIncludes(
-  rows: Record<string, unknown>[],
-  includes: string[],
-  definition: EntityDefinition,
-  services: Record<string, unknown>,
-  registry: QueryRegistry,
-): Promise<void> {
-  // Group includes by top-level segment
-  const topLevel = new Map<string, string[]>();
-  for (const path of includes) {
-    const dot = path.indexOf(".");
-    if (dot === -1) {
-      if (!topLevel.has(path)) topLevel.set(path, []);
-    } else {
-      const parent = path.substring(0, dot);
-      const child = path.substring(dot + 1);
-      const existing = topLevel.get(parent) ?? [];
-      existing.push(child);
-      topLevel.set(parent, existing);
-    }
-  }
-
-  for (const [relationName, nestedIncludes] of topLevel) {
-    const relation = definition.relations[relationName];
-    if (!relation) continue;
-
-    const targetService = services[relation.targetService] as
-      | Record<string, (...args: unknown[]) => Promise<unknown>>
-      | undefined;
-    if (!targetService) continue;
-
-    // Collect foreign key values (deduplicated)
-    const ids = [
-      ...new Set(
-        rows
-          .map((r) => r[relation.foreignKey])
-          .filter((v): v is string => v != null && typeof v === "string"),
-      ),
-    ];
-    if (ids.length === 0) continue;
-
-    // One batched query
-    const batchFn = targetService[relation.batchMethod];
-    if (!batchFn) continue;
-
-    const relatedResult = await batchFn(ids);
-    const relatedRows = extractRows(relatedResult);
-
-    // Build lookup
-    const map = new Map<string, unknown>();
-    for (const related of relatedRows) {
-      const rec = related as Record<string, unknown>;
-      if (relation.isList) {
-        const key = rec[relation.foreignKey] as string;
-        if (!map.has(key)) map.set(key, []);
-        (map.get(key) as unknown[]).push(rec);
-      } else {
-        map.set(rec["id"] as string, rec);
-      }
-    }
-
-    // Attach to parent rows
-    for (const row of rows) {
-      const fkValue = row[relation.foreignKey] as string | undefined;
-      if (!fkValue) continue;
-      row[relation.attachAs] =
-        map.get(fkValue) ?? (relation.isList ? [] : null);
-    }
-
-    // Resolve nested includes
-    if (nestedIncludes.length > 0) {
-      const targetDef = registry.get(relation.targetService);
-      if (targetDef) {
-        const nestedRows = relation.isList
-          ? rows.flatMap(
-              (r) =>
-                (r[relation.attachAs] as Record<string, unknown>[]) ?? [],
-            )
-          : rows
-              .map((r) => r[relation.attachAs] as Record<string, unknown>)
-              .filter(Boolean);
-        await resolveIncludes(
-          nestedRows,
-          nestedIncludes,
-          targetDef,
-          services,
-          registry,
-        );
-      }
-    }
-  }
-}
-
-function extractRows(result: unknown): unknown[] {
-  if (Array.isArray(result)) return result;
-  if (result && typeof result === "object") {
-    const r = result as { ok?: boolean; value?: unknown };
-    if (r.value != null) {
-      if (Array.isArray(r.value)) return r.value;
-      if (typeof r.value === "object" && "items" in r.value) {
-        return (r.value as { items: unknown[] }).items;
-      }
-    }
-  }
-  return [];
-}

package/src/kernel/query/registry.ts

@@ -1,46 +0,0 @@
-/**
- * Defines a relation from a parent entity to a related entity.
- * Used by the query executor to batch-load related records.
- */
-export interface RelationDefinition {
-  foreignKey: string;
-  targetService: string;
-  batchMethod: string;
-  attachAs: string;
-  isList?: boolean;
-}
-
-/**
- * Defines an entity that can be queried via kernel.query().
- */
-export interface EntityDefinition {
-  service: string;
-  getByIdMethod: string;
-  listMethod: string;
-  relations: Record<string, RelationDefinition>;
-}
-
-/**
- * Registry of queryable entities and their relations.
- * Modules register their entities at kernel boot.
- * Plugins can register additional entities.
- */
-export class QueryRegistry {
-  private entities = new Map<string, EntityDefinition>();
-
-  register(name: string, definition: EntityDefinition): void {
-    this.entities.set(name, definition);
-  }
-
-  get(name: string): EntityDefinition | undefined {
-    return this.entities.get(name);
-  }
-
-  has(name: string): boolean {
-    return this.entities.has(name);
-  }
-
-  listEntities(): string[] {
-    return [...this.entities.keys()];
-  }
-}

package/src/kernel/service-registry.ts

@@ -1,76 +0,0 @@
-/**
- * ServiceRegistry -- typed surface of the kernel service container
- * for plugin-to-plugin communication.
- *
- * Plugin services accept this as an optional constructor parameter
- * to call core services without resorting to raw SQL.
- *
- * Core services are loosely typed here (method signatures use `unknown`)
- * to avoid plugin packages depending on core's internal service types.
- * Plugin authors cast the return values at the call site.
- *
- * Usage in a plugin service:
- *
- *   import type { ServiceRegistry } from "@porulle/core";
- *
- *   class MyService {
- *     constructor(private db: PluginDb, private services?: ServiceRegistry) {}
- *
- *     async doWork() {
- *       const result = await this.services?.inventory.adjust({
- *         entityId: "...", adjustment: -5, reason: "recipe deduction"
- *       }, actor);
- *     }
- *   }
- */
-
-export interface ServiceRegistry {
-  inventory: {
-    adjust(
-      input: {
-        entityId: string;
-        variantId?: string;
-        warehouseId?: string;
-        adjustment: number;
-        reason?: string;
-      },
-      actor?: unknown,
-    ): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
-    createWarehouse(
-      input: { name: string; code: string },
-      actor?: unknown,
-    ): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
-    reserve(input: unknown, actor?: unknown): Promise<unknown>;
-    release(input: unknown, actor?: unknown): Promise<unknown>;
-    getAvailable(input: unknown, actor?: unknown): Promise<unknown>;
-    [method: string]: unknown;
-  };
-  catalog: {
-    create(input: unknown, actor?: unknown): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
-    getById(id: string, options?: unknown): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
-    publish(id: string, actor?: unknown): Promise<unknown>;
-    list(input?: unknown): Promise<unknown>;
-    [method: string]: unknown;
-  };
-  customers: {
-    getByUserId(userId: string, actor?: unknown): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
-    getById(id: string, actor?: unknown): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
-    [method: string]: unknown;
-  };
-  orders: {
-    create(input: unknown, actor?: unknown): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
-    changeStatus(input: unknown, actor?: unknown): Promise<unknown>;
-    [method: string]: unknown;
-  };
-  cart: {
-    create(input: unknown, actor?: unknown): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
-    [method: string]: unknown;
-  };
-  organization: {
-    create(input: unknown): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
-    getById(id: string): Promise<unknown>;
-    [method: string]: unknown;
-  };
-  /** Access plugin-registered services by plugin ID or service name */
-  [key: string]: unknown;
-}

package/src/modules/analytics/hooks.ts

@@ -1,11 +0,0 @@
-/**
- * Analytics hooks — legacy compatibility surface.
- *
- * The in-memory event recording hooks (recordOrderAnalyticsEvent,
- * recordInventoryAnalyticsEvent) have been removed. The source tables
- * (orders, inventory_levels, customers) ARE the source of truth; the
- * DrizzleAnalyticsAdapter queries them directly via SQL.
- *
- * The empty exports below preserve backwards compatibility for code
- * still importing from this module.
- */

package/src/modules/analytics/module.ts

@@ -1,35 +0,0 @@
-import type { CommerceConfig } from "../../config/types.js";
-import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
-import { defineModule } from "../../kernel/module/index.js";
-import type { SettingsService } from "../settings/service.js";
-import { DrizzleAnalyticsAdapter } from "./drizzle-adapter.js";
-import { BUILTIN_ANALYTICS_MODELS } from "./models.js";
-import { RetailReportsEngine } from "./reports.js";
-import { AnalyticsService } from "./service.js";
-
-export const analyticsModule = defineModule<
-  Record<string, never>,
-  AnalyticsService,
-  Record<string, never>
->({
-  id: "analytics",
-  schema: () => ({}),
-  service: (deps) => {
-    const adapter = new DrizzleAnalyticsAdapter(deps.db.db as DrizzleDatabase);
-    for (const model of BUILTIN_ANALYTICS_MODELS) {
-      adapter.registerModel(model);
-    }
-    // Settings is resolved lazily from the shared service container — the
-    // settings module may instantiate after analytics.
-    const services = deps.services as Record<string, unknown>;
-    const reports = new RetailReportsEngine(
-      deps.db.db as DrizzleDatabase,
-      (orgId, group) => (services.settings as SettingsService).read(orgId, group),
-    );
-    return new AnalyticsService({
-      adapter,
-      config: deps.config as CommerceConfig,
-      reports,
-    });
-  },
-});

package/src/modules/analytics/repository/index.ts

@@ -1,5 +0,0 @@
-import type { TxContext } from "../../../kernel/database/tx-context.js";
-
-export interface AnalyticsRepository {
-  ping(ctx: TxContext): Promise<void>;
-}

package/src/modules/audit/index.ts

@@ -1 +0,0 @@
-export { auditModule } from "./module.js";

package/src/modules/audit/module.ts

@@ -1,11 +0,0 @@
-import { defineModule } from "../../kernel/module/index.js";
-import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
-import { auditLog } from "./schema.js";
-import { createAuditService } from "./service.js";
-
-export const auditModule = defineModule({
-  id: "audit",
-  schema: () => ({ auditLog }),
-  service: (deps) =>
-    createAuditService(deps.db.db as DrizzleDatabase),
-});

package/src/modules/cart/access.ts

@@ -1,27 +0,0 @@
-import type { Actor } from "../../auth/types.js";
-import type { Cart } from "./repository/index.js";
-
-/**
- * Determines whether an actor can access a cart.
- *
- * Access is granted if:
- * 1. The actor is authenticated and owns the cart (customerId match)
- * 2. The provided secret matches the cart's secret (guest access)
- */
-export function canAccessCart(
-  actor: Actor | null,
-  cart: Cart,
-  providedSecret?: string,
-): boolean {
-  // Authenticated owner
-  if (actor && cart.customerId && actor.userId === cart.customerId) {
-    return true;
-  }
-
-  // Valid secret (guest access)
-  if (providedSecret && cart.secret && providedSecret === cart.secret) {
-    return true;
-  }
-
-  return false;
-}

package/src/modules/cart/module.ts

@@ -1,32 +0,0 @@
-import type { CommerceConfig } from "../../config/types.js";
-import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
-import { defineModule } from "../../kernel/module/index.js";
-import type { CatalogServiceImpl } from "../catalog/service.js";
-import type { InventoryService } from "../inventory/service.js";
-import { CartRepository } from "./repository/index.js";
-import { cartLineItems, carts } from "./schema.js";
-import { CartService } from "./service.js";
-
-type CartModuleDeps = {
-  catalog: CatalogServiceImpl;
-  inventory: InventoryService;
-};
-
-export const cartModule = defineModule<
-  { carts: typeof carts; cartLineItems: typeof cartLineItems },
-  CartService,
-  CartModuleDeps
->({
-  id: "cart",
-  dependencies: ["catalog", "inventory"],
-  schema: () => ({ carts, cartLineItems }),
-  service: (deps) =>
-    new CartService({
-      repository: new CartRepository(deps.db.db as DrizzleDatabase),
-      catalogRepository: deps.services.catalog.repository,
-      hooks: deps.hooks,
-      config: deps.config as CommerceConfig,
-      services: deps.services,
-      database: deps.db,
-    }),
-});

package/src/modules/catalog/module.ts

@@ -1,80 +0,0 @@
-import type { CommerceConfig } from "../../config/types.js";
-import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
-import { defineModule } from "../../kernel/module/index.js";
-import type { PricingService } from "../pricing/service.js";
-import { CatalogRepository } from "./repository/index.js";
-import {
-  brands,
-  categories,
-  tags,
-  entityTags,
-  entityBrands,
-  entityCategories,
-  optionTypes,
-  optionValues,
-  sellableAttributes,
-  sellableCustomFields,
-  entityFieldDefinitions,
-  sellableEntityRevisions,
-  sellableEntities,
-  variantOptionValues,
-  variants,
-  catalogFieldOwnership,
-} from "./schema.js";
-import { CatalogServiceImpl } from "./service.js";
-
-type CatalogModuleDeps = {
-  pricing: PricingService;
-};
-
-export const catalogModule = defineModule<
-  {
-    sellableEntities: typeof sellableEntities;
-    sellableAttributes: typeof sellableAttributes;
-    sellableCustomFields: typeof sellableCustomFields;
-    entityFieldDefinitions: typeof entityFieldDefinitions;
-    sellableEntityRevisions: typeof sellableEntityRevisions;
-    categories: typeof categories;
-    entityCategories: typeof entityCategories;
-    brands: typeof brands;
-    entityBrands: typeof entityBrands;
-    tags: typeof tags;
-    entityTags: typeof entityTags;
-    optionTypes: typeof optionTypes;
-    optionValues: typeof optionValues;
-    variants: typeof variants;
-    variantOptionValues: typeof variantOptionValues;
-    catalogFieldOwnership: typeof catalogFieldOwnership;
-  },
-  CatalogServiceImpl,
-  CatalogModuleDeps
->({
-  id: "catalog",
-  dependencies: ["pricing"],
-  schema: () => ({
-    sellableEntities,
-    sellableAttributes,
-    sellableCustomFields,
-    entityFieldDefinitions,
-    sellableEntityRevisions,
-    categories,
-    entityCategories,
-    brands,
-    entityBrands,
-    tags,
-    entityTags,
-    optionTypes,
-    optionValues,
-    variants,
-    variantOptionValues,
-    catalogFieldOwnership,
-  }),
-  service: (deps) =>
-    new CatalogServiceImpl({
-      repository: new CatalogRepository(deps.db.db as DrizzleDatabase),
-      hooks: deps.hooks,
-      config: deps.config as CommerceConfig,
-      services: deps.services,
-      database: deps.db,
-    }),
-});

package/src/modules/customers/index.ts

@@ -1 +0,0 @@
-export { customersModule } from "./module.js";

package/src/modules/customers/module.ts

@@ -1,29 +0,0 @@
-import type { CommerceConfig } from "../../config/types.js";
-import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
-import { defineModule } from "../../kernel/module/index.js";
-import { CustomersRepository } from "./repository/index.js";
-import { CustomerService } from "./service.js";
-import {
-  customerAddresses,
-  customerGroupMembers,
-  customerGroups,
-  customers,
-} from "./schema.js";
-
-export const customersModule = defineModule({
-  id: "customers",
-  schema: () => ({
-    customers,
-    customerAddresses,
-    customerGroups,
-    customerGroupMembers,
-  }),
-  service: (deps) =>
-    new CustomerService({
-      repository: new CustomersRepository(deps.db.db as DrizzleDatabase),
-      hooks: deps.hooks,
-      config: deps.config as CommerceConfig,
-      services: deps.services,
-      database: deps.db,
-    }),
-});

package/src/modules/documents/module.ts

@@ -1,21 +0,0 @@
-import type { CommerceConfig } from "../../config/types.js";
-import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
-import { defineModule } from "../../kernel/module/index.js";
-import { DocumentsRepository } from "./repository/index.js";
-import { invoiceSequences, orderDocuments } from "./schema.js";
-import { DocumentsService } from "./service.js";
-
-export const documentsModule = defineModule<
-  { invoiceSequences: typeof invoiceSequences; orderDocuments: typeof orderDocuments },
-  DocumentsService,
-  Record<string, never>
->({
-  id: "documents",
-  schema: () => ({ invoiceSequences, orderDocuments }),
-  service: (deps) =>
-    new DocumentsService({
-      repository: new DocumentsRepository(deps.db.db as DrizzleDatabase),
-      services: deps.services as Record<string, unknown>,
-      config: deps.config as CommerceConfig,
-    }),
-});