@porulle/core 0.1.0

package/src/kernel/query/executor.ts

@@ -0,0 +1,184 @@
+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

@@ -0,0 +1,46 @@
+/**
+ * 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/result.ts

@@ -0,0 +1,33 @@
+import type { CommerceError } from "./errors.js";
+
+export type Result<T, E = CommerceError> =
+  | { ok: true; value: T; meta?: Record<string, unknown> }
+  | { ok: false; error: E };
+
+/**
+ * Simplified Result types for plugin services.
+ * Plugin services return `PluginResult<T>` instead of `Result<T, CommerceError>`.
+ * This matches the `{ ok: true; value: T } | { ok: false; error: string }` pattern
+ * that every plugin has been copy-pasting.
+ */
+export type PluginResult<T> = { ok: true; value: T } | { ok: false; error: string; code?: string };
+export type PluginResultErr = { ok: false; error: string; code?: string };
+
+export function Ok<T>(value: T, meta?: Record<string, unknown>): Result<T, never> {
+  if (meta !== undefined) {
+    return { ok: true, value, meta };
+  }
+  return { ok: true, value };
+}
+
+export function Err<E>(error: E): Result<never, E> {
+  return { ok: false, error };
+}
+
+/**
+ * String-based Err for plugin services.
+ * Usage: `return PluginErr("Not found", "NOT_FOUND")`
+ */
+export function PluginErr(error: string, code?: string): PluginResultErr {
+  return code ? { ok: false, error, code } : { ok: false, error };
+}

package/src/kernel/service-registry.ts

@@ -0,0 +1,76 @@
+/**
+ * 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/kernel/service-timing.ts

@@ -0,0 +1,89 @@
+/**
+ * Service method observability via ES Proxy.
+ *
+ * Wraps a service object so that every async method call is timed.
+ * Slow calls (above threshold) are logged with service name, method name,
+ * and duration. Failed calls always log with the error.
+ *
+ * Usage at kernel boot:
+ *   services.inventory = withTiming(inventoryService, "inventory", logger);
+ *   services.catalog = withTiming(catalogService, "catalog", logger);
+ *
+ * Produces log entries like:
+ *   { service: "inventory", method: "adjust", durationMs: 245 } "slow service call"
+ *   { service: "catalog", method: "create", durationMs: 12, err: ... } "service call failed"
+ *
+ * Only wraps own methods (not inherited). Synchronous property access
+ * (e.g., reading a field) passes through unchanged with zero overhead.
+ */
+
+interface TimingLogger {
+  info(obj: Record<string, unknown>, msg: string): void;
+  error(obj: Record<string, unknown>, msg: string): void;
+}
+
+export function withTiming<T extends object>(
+  service: T,
+  serviceName: string,
+  logger: TimingLogger,
+  slowThresholdMs = 100,
+): T {
+  return new Proxy(service, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+
+      // Only wrap functions, skip symbols and non-function props
+      if (typeof value !== "function" || typeof prop === "symbol") {
+        return value;
+      }
+
+      // Skip internal/private-looking methods
+      const methodName = String(prop);
+      if (methodName.startsWith("_")) return value;
+
+      return function proxiedMethod(this: unknown, ...args: unknown[]) {
+        const start = performance.now();
+
+        // Call the original method
+        let result: unknown;
+        try {
+          result = value.apply(target, args);
+        } catch (err) {
+          // Synchronous throw
+          const durationMs = Math.round(performance.now() - start);
+          logger.error(
+            { service: serviceName, method: methodName, durationMs, err },
+            `${serviceName}.${methodName} failed (${durationMs}ms)`,
+          );
+          throw err;
+        }
+
+        // If result is a promise, attach timing to its resolution
+        if (result && typeof (result as Promise<unknown>).then === "function") {
+          return (result as Promise<unknown>).then(
+            (resolved) => {
+              const durationMs = Math.round(performance.now() - start);
+              if (durationMs > slowThresholdMs) {
+                logger.info(
+                  { service: serviceName, method: methodName, durationMs },
+                  `${serviceName}.${methodName} slow (${durationMs}ms)`,
+                );
+              }
+              return resolved;
+            },
+            (err) => {
+              const durationMs = Math.round(performance.now() - start);
+              logger.error(
+                { service: serviceName, method: methodName, durationMs, err },
+                `${serviceName}.${methodName} failed (${durationMs}ms)`,
+              );
+              throw err;
+            },
+          );
+        }
+
+        return result;
+      };
+    },
+  });
+}

package/src/kernel/state-machine/machine.ts

@@ -0,0 +1,101 @@
+import { CommerceInvalidTransitionError } from "../errors.js";
+
+export interface StateDefinition<TState extends string> {
+  states: readonly TState[];
+  initial: TState;
+  transitions: Record<TState, readonly TState[]>;
+  terminal: readonly TState[];
+}
+
+export type OrderState = string;
+
+const DEFAULT_TRANSITIONS: Record<string, readonly string[]> = {
+  pending: ["confirmed", "cancelled"],
+  confirmed: ["processing", "cancelled"],
+  processing: ["partially_fulfilled", "fulfilled", "cancelled"],
+  partially_fulfilled: ["fulfilled", "cancelled"],
+  fulfilled: ["refunded"],
+  cancelled: [],
+  refunded: [],
+};
+
+const DEFAULT_STATES: readonly string[] = [
+  "pending", "confirmed", "processing", "partially_fulfilled",
+  "fulfilled", "cancelled", "refunded",
+];
+
+const DEFAULT_TERMINAL: readonly string[] = ["cancelled", "refunded"];
+
+export const orderStateMachine: StateDefinition<string> = {
+  states: DEFAULT_STATES,
+  initial: "pending",
+  transitions: DEFAULT_TRANSITIONS,
+  terminal: DEFAULT_TERMINAL,
+};
+
+/**
+ * Extend the order state machine with custom transitions.
+ * New states are added automatically. Existing state transition arrays
+ * are merged (union, not replaced) with the custom ones.
+ *
+ * Usage:
+ *   const extended = extendOrderStateMachine({
+ *     pending: ["payment_initiated"],
+ *     payment_initiated: ["payment_authorized", "payment_failed"],
+ *     payment_authorized: ["processing"],
+ *   });
+ */
+export function extendOrderStateMachine(
+  customTransitions: Record<string, string[]>,
+): StateDefinition<string> {
+  const merged: Record<string, string[]> = {};
+
+  // Copy defaults
+  for (const [state, targets] of Object.entries(DEFAULT_TRANSITIONS)) {
+    merged[state] = [...targets];
+  }
+
+  // Merge custom
+  for (const [state, targets] of Object.entries(customTransitions)) {
+    if (!merged[state]) merged[state] = [];
+    for (const t of targets) {
+      if (!merged[state].includes(t)) merged[state].push(t);
+    }
+    // Ensure target states also exist in the map
+    for (const t of targets) {
+      if (!merged[t]) merged[t] = [];
+    }
+  }
+
+  const allStates = Object.keys(merged);
+  const terminal = allStates.filter((s) => merged[s]!.length === 0);
+
+  return {
+    states: allStates,
+    initial: "pending",
+    transitions: merged,
+    terminal,
+  };
+}
+
+export function canTransition<TState extends string>(
+  machine: StateDefinition<TState>,
+  from: TState,
+  to: TState,
+): boolean {
+  return machine.transitions[from].includes(to);
+}
+
+export function assertTransition<TState extends string>(
+  machine: StateDefinition<TState>,
+  from: TState,
+  to: TState,
+): void {
+  if (!canTransition(machine, from, to)) {
+    throw new CommerceInvalidTransitionError(
+      `Cannot transition from "${from}" to "${to}". Allowed transitions from "${from}": [${machine.transitions[
+        from
+      ].join(", ")}]`,
+    );
+  }
+}