@sapporta/server 0.0.1

package/src/reports/loader.ts

@@ -0,0 +1,55 @@
+import { readdir } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import type { ReportDefinition } from "./report.js";
+
+/**
+ * Check if a value looks like a ReportDefinition (duck-typing).
+ */
+function isReportDefinition(val: unknown): val is ReportDefinition {
+  if (typeof val !== "object" || val === null) return false;
+  const obj = val as Record<string, unknown>;
+  return (
+    typeof obj.name === "string" &&
+    typeof obj.label === "string" &&
+    Array.isArray(obj.params) &&
+    typeof obj.sources === "object" &&
+    obj.sources !== null &&
+    typeof obj.tree === "object" &&
+    obj.tree !== null
+  );
+}
+
+/**
+ * Load all report definitions from a directory.
+ * Each .ts file should default-export a report().
+ */
+export async function loadReports(
+  dir: string,
+): Promise<ReportDefinition[]> {
+  const absDir = resolve(dir);
+  const files = await readdir(absDir);
+  const reports: ReportDefinition[] = [];
+
+  for (const file of files) {
+    if (!file.endsWith(".ts") && !file.endsWith(".js")) continue;
+    if (file.endsWith(".test.ts") || file.endsWith(".test.js")) continue;
+
+    const filePath = join(absDir, file);
+    const mod = await import(filePath);
+
+    // Check default export first
+    if (mod.default && isReportDefinition(mod.default)) {
+      reports.push(mod.default);
+      continue;
+    }
+
+    // Check named exports
+    for (const key of Object.keys(mod)) {
+      if (isReportDefinition(mod[key])) {
+        reports.push(mod[key]);
+      }
+    }
+  }
+
+  return reports;
+}

package/src/reports/report.ts

@@ -0,0 +1,308 @@
+// ============================================================================
+// REPORT DEFINITION API
+// ============================================================================
+//
+// A Sapporta report is a TypeScript file that default-exports a report definition.
+// Reports are declarative: you specify SQL data sources and a tree structure that
+// describes how to assemble the query results into hierarchical output.
+//
+// The engine loads report files from a directory, executes them with user-supplied
+// parameters, and returns a tree of output nodes.
+//
+// QUICK EXAMPLE:
+//
+//   import { report } from "@sapporta/server/report";
+//
+//   export default report({
+//     name: "my-report",
+//     label: "My Report",
+//     params: [{ name: "year", type: "integer", required: true, label: "Year" }],
+//     sources: {
+//       items: { query: "SELECT id, name, amount FROM items WHERE year = $year" },
+//     },
+//     tree: {
+//       source: "items",
+//       levelName: "item",
+//       columns: [
+//         { name: "name", header: "Name" },
+//         { name: "amount", header: "Amount", format: "currency" },
+//       ],
+//     },
+//   });
+//
+// ============================================================================
+
+// ---------------------------------------------------------------------------
+// Params — user-supplied inputs that parameterize SQL queries
+// ---------------------------------------------------------------------------
+//
+// Params are declared up front. The UI renders a form for them. The engine
+// resolves defaults, validates types, and injects values into SQL queries as
+// bind variables.
+//
+// In SQL sources, reference params with $name syntax:
+//   "SELECT * FROM accounts WHERE date <= $as_of_date"
+
+export type ParamType = "date" | "string" | "integer" | "float";
+
+export type ReportParam = {
+  /** Bind variable name. Used as $name in SQL sources. Must be unique. */
+  name: string;
+
+  /** Data type. The engine coerces user input to this type. */
+  type: ParamType;
+
+  /** If true, execution throws when this param is not supplied. */
+  required: boolean;
+
+  /** Used when the param is not supplied. Only relevant if required=false. */
+  default?: unknown;
+
+  /** Display label for the UI parameter form. Falls back to name if omitted. */
+  label?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Sources — named SQL queries that provide data for the tree
+// ---------------------------------------------------------------------------
+//
+// Each source is a raw SQL query string. Sources are referenced by tree nodes
+// via the `source` field. The same source can be referenced by multiple tree
+// nodes (e.g. a "transactions" source used by several child nodes).
+//
+// Bind variables use $name syntax: $param_name for global params, and $varname
+// for bind variables injected by parent tree nodes.
+//
+// The engine converts $name to positional $1, $2, ... for postgres.js execution.
+//
+// IMPORTANT: PostgreSQL returns numeric/decimal columns as strings. The engine
+// automatically parses these to numbers. Use ::numeric casts in SQL to ensure
+// consistent types: COALESCE(SUM(amount::numeric), 0) AS total
+
+export type ReportSource = {
+  /** Raw SQL query. Use $name for bind variables (params and parent binds). */
+  query: string;
+};
+
+// ---------------------------------------------------------------------------
+// Columns — which fields from the source row to include in the output
+// ---------------------------------------------------------------------------
+//
+// Each column maps a name from the SQL result to the output node. Only declared
+// columns appear in the output — undeclared fields from the SQL row are discarded.
+//
+// Columns can also be "virtual" — not present in the SQL result but populated
+// by a `transform` function. Declare them in columns so the UI knows about them.
+//
+// Report columns use ColumnSchema (the same type used for table columns).
+// Only `name` is required; use `header` for display label and `format` for
+// rendering hints. DB-specific fields (primary, foreignKey, etc.) are optional
+// and default to inert values.
+
+import type { ColumnSchema } from "../schema/extract.js";
+export type { ColumnSchema } from "../schema/extract.js";
+
+// ---------------------------------------------------------------------------
+// Sort — ordering of output nodes within a tree level
+// ---------------------------------------------------------------------------
+//
+// Sorting happens after all nodes at a level are assembled (including rollup
+// computation). You can sort by column keys or rollup keys.
+//
+// If no sort is specified, nodes appear in the order returned by the SQL query.
+
+export type ReportSort = {
+  /** Column key or rollup key to sort by. */
+  key: string;
+
+  /** Sort direction. Default is "asc". */
+  direction: "asc" | "desc";
+};
+
+// ---------------------------------------------------------------------------
+// TransformContext — context available to the transform function
+// ---------------------------------------------------------------------------
+
+export type TransformContext = {
+  /** The parent output node. Has columns, rollup, and children processed so far. */
+  parent: ReportOutputNode;
+
+  /** Children of the parent that were processed before the current child.
+   *  Keyed by level name. Contains the fully materialized output.
+   *
+   *  For singular children: the value is a single ReportOutputNode or null.
+   *  For list children: the value is ReportOutputNode[].
+   */
+  siblings: Record<string, ReportOutputNode | ReportOutputNode[] | null>;
+
+  /** The resolved global params. */
+  params: Record<string, unknown>;
+
+  /** Full SQL rows, parallel to the nodes array passed to the transform.
+   *  Includes ALL columns from the SQL result, even those not declared in
+   *  columns[]. This lets transforms access undeclared SQL columns without
+   *  requiring them in the columns[] declaration. */
+  rawRows: Record<string, unknown>[];
+};
+
+// ---------------------------------------------------------------------------
+// Footer — synthetic rows appended after all data nodes at a level
+// ---------------------------------------------------------------------------
+
+export type ReportFooter = {
+  /** Label for the footer row. Appears as a special column or is used by the UI. */
+  label: string;
+
+  /** Compute footer values from the assembled sibling nodes at this level.
+   *  The returned Record becomes the footer node's `columns`. */
+  compute: (nodes: ReportOutputNode[]) => Record<string, unknown>;
+};
+
+// ---------------------------------------------------------------------------
+// Tree Node — the hierarchical structure of the report
+// ---------------------------------------------------------------------------
+
+export type ReportTreeNode = {
+  /** Name of the source in the report's `sources` map. */
+  source: string;
+
+  /** Name for this tree level. Used as the key in the parent's children map. */
+  levelName: string;
+
+  /** Columns to extract from each source row into the output node. */
+  columns: ColumnSchema[];
+
+  // --- Parent-child binding ---
+
+  /** How to pass values from the parent row into this node's SQL query. */
+  bind?:
+    | Record<string, string>
+    | ((
+        parent: Record<string, unknown>,
+        params: Record<string, unknown>,
+      ) => Record<string, unknown>);
+
+  /** Conditional execution. If returns false, the child is skipped. */
+  when?: (parent: Record<string, unknown>) => boolean;
+
+  /** If true, this child produces a single object (or null) instead of an array. */
+  singular?: boolean;
+
+  // --- Post-processing ---
+
+  /** Rollup: compute values on a parent node from its materialized children. */
+  rollup?: (
+    children: Record<string, ReportOutputNode[]>,
+  ) => Record<string, unknown>;
+
+  /** Transform: post-process assembled output nodes for this tree level. */
+  transform?: (
+    nodes: ReportOutputNode[],
+    context: TransformContext,
+  ) => ReportOutputNode[];
+
+  /** Sort specification. Applied after transform. */
+  sort?: ReportSort[];
+
+  /** Footer rows. Computed after all data nodes are finalized. */
+  footer?: ReportFooter[];
+
+  /** When true, the UI renders this level's children collapsed by default.
+   *
+   *  This flag is set on the PARENT level and applies to its children's
+   *  visibility. The engine extracts it into `ReportResult.levelOptions`
+   *  (keyed by levelName) so the UI can read it without walking the tree
+   *  definition. When omitted or false, children start expanded. */
+  defaultCollapsed?: boolean;
+
+  /** Child tree nodes. Processed in declaration order for each parent row. */
+  children?: ReportTreeNode[];
+};
+
+// ---------------------------------------------------------------------------
+// Report Definition — the top-level structure
+// ---------------------------------------------------------------------------
+
+export type ReportDefinition = {
+  /** URL-safe identifier. Used in API routes: /api/_reports/:name/execute */
+  name: string;
+
+  /** Human-readable title. */
+  label: string;
+
+  /** Parameter definitions. */
+  params: ReportParam[];
+
+  /** Named SQL data sources. */
+  sources: Record<string, ReportSource>;
+
+  /** The tree structure defining how to assemble query results. */
+  tree: ReportTreeNode;
+};
+
+// ---------------------------------------------------------------------------
+// Output Types — what the engine produces
+// ---------------------------------------------------------------------------
+
+export type ReportFooterRow = {
+  label: string;
+  columns: Record<string, unknown>;
+};
+
+export type ReportOutputNode = {
+  /** Level name from the tree node definition. */
+  levelName: string;
+
+  /** Column values extracted from the source row. */
+  columns: Record<string, unknown>;
+
+  /** Values computed by the `rollup` function. */
+  rollup?: Record<string, unknown>;
+
+  /** Materialized children, keyed by level name. */
+  children?: Record<string, ReportOutputNode[] | ReportOutputNode | null>;
+
+  /** Footer rows for each child level, keyed by levelName. */
+  childFooterRows?: Record<string, ReportFooterRow[]>;
+};
+
+export type ReportResult = {
+  /** Report name from the definition. */
+  name: string;
+
+  /** Report label from the definition. */
+  label: string;
+
+  /** Parameter definitions (so the UI can render a form for re-execution). */
+  params: ReportParam[];
+
+  /** Column definitions from the root tree level. */
+  columns: ColumnSchema[];
+
+  /** Column definitions for each tree level, keyed by levelName. */
+  levelColumns: Record<string, ColumnSchema[]>;
+
+  /** The assembled tree data. */
+  data: ReportOutputNode[];
+
+  /** Per-level UI options extracted from the tree definition, keyed by levelName.
+   *
+   *  The engine walks the tree and collects `defaultCollapsed` (and potentially
+   *  future per-level flags) into this flat map so the UI doesn't need access
+   *  to the tree definition itself. Only levels with non-default values appear. */
+  levelOptions?: Record<string, { defaultCollapsed?: boolean }>;
+
+  /** Root-level footer rows (e.g. "Grand Total"). */
+  footerRows?: ReportFooterRow[];
+
+  /** Non-fatal errors collected during execution. */
+  errors?: { path: string; message: string }[];
+};
+
+// ---------------------------------------------------------------------------
+// report() factory — creates a report definition with type checking
+// ---------------------------------------------------------------------------
+
+export function report(def: ReportDefinition): ReportDefinition {
+  return def;
+}

package/src/reports/sql-bind.ts

@@ -0,0 +1,161 @@
+// ============================================================================
+// SQL BIND VARIABLES
+// ============================================================================
+//
+// A SQL query in Sapporta uses $name syntax for bind variables. This module
+// provides the operations for working with those variables:
+//
+//   scan     — walk SQL respecting strings/comments, call back for each $name
+//   extract  — discover which bind variable names appear in a query
+//   buildPositional — convert $name → ?,?,... for SQLite execution
+//
+// The scanner is the shared primitive. extract and buildPositional are both
+// built on top of it.
+
+// ---------------------------------------------------------------------------
+// Scanner — the shared primitive
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk a SQL string respecting single-quoted strings, line comments (--),
+ * and block comments. Calls onBind(name) for each $name bind variable found;
+ * the callback's return value replaces `$name` in the output.
+ * Returns the rebuilt SQL string.
+ */
+export function scanSqlBindVariables(
+  sql: string,
+  onBind: (name: string) => string,
+): string {
+  let result = "";
+  let i = 0;
+
+  while (i < sql.length) {
+    // Single-quoted string — copy verbatim, handling '' escapes
+    if (sql[i] === "'") {
+      result += "'";
+      i++;
+      while (i < sql.length) {
+        if (sql[i] === "'" && sql[i + 1] === "'") {
+          result += "''";
+          i += 2;
+        } else if (sql[i] === "'") {
+          break;
+        } else {
+          result += sql[i];
+          i++;
+        }
+      }
+      if (i < sql.length) {
+        result += "'";
+        i++; // closing quote
+      }
+      continue;
+    }
+
+    // -- line comment — copy verbatim
+    if (sql[i] === "-" && sql[i + 1] === "-") {
+      while (i < sql.length && sql[i] !== "\n") {
+        result += sql[i];
+        i++;
+      }
+      continue;
+    }
+
+    // /* block comment */ — copy verbatim
+    if (sql[i] === "/" && sql[i + 1] === "*") {
+      result += "/*";
+      i += 2;
+      while (i < sql.length - 1 && !(sql[i] === "*" && sql[i + 1] === "/")) {
+        result += sql[i];
+        i++;
+      }
+      if (i < sql.length - 1) {
+        result += "*/";
+        i += 2;
+      }
+      continue;
+    }
+
+    // $name bind variable (not $1 positional params)
+    if (sql[i] === "$" && i + 1 < sql.length && /[a-zA-Z_]/.test(sql[i + 1])) {
+      let name = "";
+      i++; // skip $
+      while (i < sql.length && /[a-zA-Z0-9_]/.test(sql[i])) {
+        name += sql[i];
+        i++;
+      }
+      result += onBind(name);
+      continue;
+    }
+
+    result += sql[i];
+    i++;
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Extract — discover bind variable names
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract $name bind variable references from a SQL string.
+ * Skips strings (single-quoted) and comments (-- and /* ... *​/).
+ * Returns variable names in order of first appearance (no duplicates).
+ */
+export function extractBindVariables(sql: string): string[] {
+  const vars: string[] = [];
+  const seen = new Set<string>();
+  scanSqlBindVariables(sql, (name) => {
+    if (!seen.has(name)) {
+      seen.add(name);
+      vars.push(name);
+    }
+    return `$${name}`;
+  });
+  return vars;
+}
+
+// ---------------------------------------------------------------------------
+// Build positional — convert $name to ? for SQLite
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert $name bind variables to ? positional parameters for SQLite.
+ *
+ * Each occurrence of $name becomes a separate ? in the output SQL,
+ * with the corresponding value appended to the values array. If the
+ * same $name appears multiple times, the value is duplicated — SQLite's
+ * ? parameters are strictly positional with no reuse mechanism (unlike
+ * Postgres's $N which allows same-position reuse).
+ *
+ * Example:
+ *   Input:  "SELECT * FROM t WHERE year = $year AND month = $month"
+ *   values: { year: 2024, month: 1 }
+ *   Output: { sql: "SELECT * FROM t WHERE year = ? AND month = ?",
+ *             values: [2024, 1] }
+ *
+ * Example with duplicate:
+ *   Input:  "SELECT * FROM t WHERE start = $year OR end = $year"
+ *   values: { year: 2024 }
+ *   Output: { sql: "SELECT * FROM t WHERE start = ? OR end = ?",
+ *             values: [2024, 2024] }
+ */
+export function buildPositionalQuery(
+  sql: string,
+  _bindVars: string[],
+  values: Record<string, unknown>,
+): { sql: string; values: unknown[] } {
+  const orderedValues: unknown[] = [];
+
+  // Replace every $name with ?, appending the value for each occurrence.
+  // SQLite's ? params are consumed in order — no way to reference by
+  // position number like Postgres's $N.
+  const result = scanSqlBindVariables(sql, (name) => {
+    orderedValues.push(values[name] ?? null);
+    return "?";
+  });
+
+  return { sql: result, values: orderedValues };
+}

package/src/reports/sqlite-bind.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect } from "vitest";
+import { buildSQLitePositionalQuery, extractBindVariables } from "./sqlite-bind.js";
+
+describe("buildSQLitePositionalQuery", () => {
+  it("replaces $name with ?", () => {
+    const result = buildSQLitePositionalQuery(
+      "SELECT * FROM t WHERE year = $year",
+      ["year"],
+      { year: 2024 },
+    );
+    expect(result.sql).toBe("SELECT * FROM t WHERE year = ?");
+    expect(result.values).toEqual([2024]);
+  });
+
+  it("handles multiple different variables", () => {
+    const result = buildSQLitePositionalQuery(
+      "SELECT * FROM t WHERE year = $year AND month = $month",
+      ["year", "month"],
+      { year: 2024, month: 1 },
+    );
+    expect(result.sql).toBe(
+      "SELECT * FROM t WHERE year = ? AND month = ?",
+    );
+    expect(result.values).toEqual([2024, 1]);
+  });
+
+  it("duplicates values for repeated $name references", () => {
+    // SQLite's ? params are strictly positional — each ? needs its own value
+    const result = buildSQLitePositionalQuery(
+      "SELECT * FROM t WHERE start_year = $year OR end_year = $year",
+      ["year"],
+      { year: 2024 },
+    );
+    expect(result.sql).toBe(
+      "SELECT * FROM t WHERE start_year = ? OR end_year = ?",
+    );
+    // Value must be duplicated — two ?s need two values
+    expect(result.values).toEqual([2024, 2024]);
+  });
+
+  it("uses null for missing values", () => {
+    const result = buildSQLitePositionalQuery(
+      "SELECT * FROM t WHERE x = $missing",
+      ["missing"],
+      {},
+    );
+    expect(result.sql).toBe("SELECT * FROM t WHERE x = ?");
+    expect(result.values).toEqual([null]);
+  });
+
+  it("does not replace $name inside single-quoted strings", () => {
+    const result = buildSQLitePositionalQuery(
+      "SELECT * FROM t WHERE name = '$literal'",
+      [],
+      {},
+    );
+    expect(result.sql).toBe("SELECT * FROM t WHERE name = '$literal'");
+    expect(result.values).toEqual([]);
+  });
+
+  it("does not replace $name inside line comments", () => {
+    const result = buildSQLitePositionalQuery(
+      "SELECT * FROM t -- WHERE year = $year\nWHERE 1=1",
+      [],
+      {},
+    );
+    expect(result.sql).toBe(
+      "SELECT * FROM t -- WHERE year = $year\nWHERE 1=1",
+    );
+    expect(result.values).toEqual([]);
+  });
+
+  it("does not replace $name inside block comments", () => {
+    const result = buildSQLitePositionalQuery(
+      "SELECT * FROM t /* $year */ WHERE 1=1",
+      [],
+      {},
+    );
+    expect(result.sql).toBe("SELECT * FROM t /* $year */ WHERE 1=1");
+    expect(result.values).toEqual([]);
+  });
+});
+
+describe("extractBindVariables (re-exported)", () => {
+  it("extracts variables from SQL", () => {
+    const vars = extractBindVariables(
+      "SELECT * FROM t WHERE year = $year AND month = $month",
+    );
+    expect(vars).toEqual(["year", "month"]);
+  });
+
+  it("deduplicates repeated variables", () => {
+    const vars = extractBindVariables(
+      "SELECT * FROM t WHERE x = $year OR y = $year",
+    );
+    expect(vars).toEqual(["year"]);
+  });
+});

package/src/reports/sqlite-bind.ts

@@ -0,0 +1,58 @@
+// ============================================================================
+// SQLite Bind Variable Conversion — $name → ? positional parameters
+// ============================================================================
+//
+// Reuses the dialect-agnostic scanner from sql-bind.ts (scanSqlBindVariables,
+// extractBindVariables) which handles string/comment skipping. Only the
+// positional parameter format differs between Postgres and SQLite:
+//
+//   Postgres: $name → $1, $2, ... (reusable — same $1 for duplicate $name)
+//   SQLite:   $name → ? (strictly positional — duplicates get separate ?s
+//             with the same value repeated in the values array)
+//
+// This is because SQLite's ? parameters are consumed in order, with no way
+// to reference a parameter by position number like Postgres's $N.
+
+import { scanSqlBindVariables } from "./sql-bind.js";
+
+// Re-export the dialect-agnostic utilities — callers of this module
+// shouldn't need to import from sql-bind.ts separately
+export { extractBindVariables } from "./sql-bind.js";
+
+/**
+ * Convert $name bind variables to ? positional parameters for SQLite.
+ *
+ * Each occurrence of $name becomes a separate ? in the output SQL,
+ * with the corresponding value appended to the values array. If the
+ * same $name appears multiple times, the value is duplicated — SQLite's
+ * ? parameters are strictly positional with no reuse mechanism.
+ *
+ * Example:
+ *   Input:  "SELECT * FROM t WHERE year = $year AND month = $month"
+ *   values: { year: 2024, month: 1 }
+ *   Output: { sql: "SELECT * FROM t WHERE year = ? AND month = ?",
+ *             values: [2024, 1] }
+ *
+ * Example with duplicate:
+ *   Input:  "SELECT * FROM t WHERE start = $year OR end = $year"
+ *   values: { year: 2024 }
+ *   Output: { sql: "SELECT * FROM t WHERE start = ? OR end = ?",
+ *             values: [2024, 2024] }
+ */
+export function buildSQLitePositionalQuery(
+  sql: string,
+  _bindVars: string[],
+  values: Record<string, unknown>,
+): { sql: string; values: unknown[] } {
+  const orderedValues: unknown[] = [];
+
+  // Replace every $name with ?, appending the value for each occurrence.
+  // Unlike Postgres buildPositionalQuery which maps $name → $N (allowing
+  // reuse of the same positional param), SQLite requires one ? per value.
+  const processedSql = scanSqlBindVariables(sql, (name) => {
+    orderedValues.push(values[name] ?? null);
+    return "?";
+  });
+
+  return { sql: processedSql, values: orderedValues };
+}