rastack 0.0.46 → 0.0.48

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.48](https://github.com/theserverkid/reactapistack/compare/v0.0.47...v0.0.48) (2026-07-13)
+
+### [0.0.47](https://github.com/theserverkid/reactapistack/compare/v0.0.46...v0.0.47) (2026-07-13)
+
 ### [0.0.46](https://github.com/theserverkid/reactapistack/compare/v0.0.45...v0.0.46) (2026-07-13)
 
 ### [0.0.45](https://github.com/theserverkid/reactapistack/compare/v0.0.44...v0.0.45) (2026-07-13)

package/dist/compile/entities.d.ts

@@ -1,54 +1,5 @@
 import * as ts from "typescript";
 import { ResourceModel } from "./model";
-/**
- * Interface-driven resource inference — "the entities in the app are a list of
- * interfaces".
- *
- * Instead of (or alongside) the `resource()` DSL, an app can describe its data
- * as plain TypeScript interfaces and consume them through typed hooks. The
- * analyser works the resource graph out from the *usage*:
- *
- * 1. **Roots come from the hooks.** Every hook call that carries a type
- *    argument — `useEntityList<Airport>(…)`, `useQuery<Terminal>(…)` — marks
- *    the interface behind that type argument as an entity. An interface can
- *    also opt in explicitly with a `@rastackResource` JSDoc tag.
- * 2. **Datatypes come from the interfaces.** Each property's TypeScript type
- *    maps to a manifest scalar (`string` → string, `number` → float,
- *    `boolean` → bool, `Date` → datetime). Constraints are carried in the
- *    type system with `DbConfig` brands from `rastack/types` —
- *    `code: string & Unique & MaxLength<3>`, `age: Int` — or, equivalently,
- *    as JSDoc tags (`@unique`, `@maxLength 3`, `@int`, `@uuid`, `@default`).
- *    Optional / `| null` properties become nullable fields.
- * 3. **Foreign keys come from the type system.** A property whose type is
- *    another entity interface is a foreign key, and the referenced interface
- *    is pulled into the resource graph transitively — the closure of the
- *    hook-rooted interfaces is the app's resource set.
- * 4. **Circular dependencies are detected.** The FK graph is walked for
- *    cycles; a cycle is an *error* when every edge in it is required (no row
- *    could ever be inserted) and a *warning* when it is breakable through a
- *    nullable field (e.g. an optional self-referencing `manager`).
- *
- * ```ts
- * // entities/airports.ts
- * export interface Airport {
- *   code: string;   // JSDoc tags refine: @maxLength 3, @unique
- *   name: string;
- * }
- * export interface Terminal {
- *   airport: Airport;   // FK — inferred from the property type
- *   label: string;
- * }
- *
- * // app/screen.tsx — the hook call is what roots the graph
- * const terminals = useEntityList<Terminal>("terminals");
- * // → resources: airports.terminal (root) + airports.airport (transitive)
- * ```
- *
- * Naming: `model` is the lower-camel interface name (a leading `I` prefix as
- * in generated `IFlight` interfaces is stripped, so hook usage of generated
- * types round-trips onto the same resource); `app` defaults to the defining
- * file's basename. Both are overridable with `@rastackApp` / `@rastackModel` tags.
- */
 export interface EntityDiagnostic {
     severity: "error" | "warning";
     message: string;

package/dist/compile/entities.js

@@ -43,17 +43,20 @@ function analyzeEntities(program, fileNames) {
     const diagnostics = [];
     const sourceFiles = (0, program_1.resourceSourceFiles)(program, fileNames);
     const scanned = new Set(sourceFiles.map((sf) => path.resolve(sf.fileName)));
-    // Every interface declared in the scanned files is a *candidate* entity.
+    // Every class/interface declared in the scanned files is a *candidate* entity.
     const candidates = new Set();
     for (const sf of sourceFiles) {
         ts.forEachChild(sf, function walk(node) {
             if (ts.isInterfaceDeclaration(node))
                 candidates.add(node);
+            if (ts.isClassDeclaration(node) && node.name)
+                candidates.add(node);
             ts.forEachChild(node, walk);
         });
     }
-    // 1. Roots: interfaces used as type arguments of hook calls, plus explicit
-    //    `@rastackResource` opt-ins.
+    // 1. Roots: declarations used as type arguments of hook calls, explicit
+    //    `@rastackResource` opt-ins, and plain data classes (declaring one *is*
+    //    the opt-in).
     const roots = [];
     const rooted = new Set();
     const addRoot = (decl) => {
@@ -66,7 +69,7 @@ function analyzeEntities(program, fileNames) {
         ts.forEachChild(sf, function walk(node) {
             if (ts.isCallExpression(node) && isHookCall(node)) {
                 for (const typeArg of node.typeArguments ?? []) {
-                    const decl = interfaceBehindTypeNode(typeArg, checker, scanned);
+                    const decl = entityBehindTypeNode(typeArg, checker, scanned);
                     if (decl && candidates.has(decl))
                         addRoot(decl);
                 }
@@ -77,9 +80,11 @@ function analyzeEntities(program, fileNames) {
     for (const decl of candidates) {
         if (jsdocTags(decl).has("rastackresource"))
             addRoot(decl);
+        else if (ts.isClassDeclaration(decl) && isDataClass(decl))
+            addRoot(decl);
     }
-    // 2. Transitive closure over FK references: an entity's interface-typed
-    //    property pulls the referenced interface in as an entity too.
+    // 2. Transitive closure over FK references: an entity's entity-typed
+    //    property pulls the referenced declaration in as an entity too.
     const propsByDecl = new Map();
     const analyzed = (decl) => {
         let props = propsByDecl.get(decl);
@@ -166,36 +171,93 @@ function isHookCall(call) {
             : undefined;
     return !!name && /^use[A-Z0-9_]/.test(name);
 }
-/** Resolve a type node to an interface declared in one of the scanned files. */
-function interfaceBehindTypeNode(node, checker, scanned) {
-    return interfaceBehindType(checker.getTypeFromTypeNode(node), scanned);
+/** Resolve a type node to a class/interface declared in a scanned file. */
+function entityBehindTypeNode(node, checker, scanned) {
+    return entityBehindType(checker.getTypeFromTypeNode(node), scanned);
 }
-function interfaceBehindType(type, scanned) {
+function entityBehindType(type, scanned) {
     const symbol = type.aliasSymbol ?? type.getSymbol();
     for (const decl of symbol?.declarations ?? []) {
-        if (ts.isInterfaceDeclaration(decl) &&
+        if ((ts.isInterfaceDeclaration(decl) ||
+            (ts.isClassDeclaration(decl) && decl.name)) &&
             scanned.has(path.resolve(decl.getSourceFile().fileName))) {
             return decl;
         }
     }
     return undefined;
 }
+/**
+ * A *plain data class* — the class-authored equivalent of a `resource()` call,
+ * so it roots itself. It must carry no heritage clause (a subclass of
+ * `React.Component` or a service base is app code, not a table), not be
+ * abstract, contain nothing but property declarations, and have at least one
+ * instance property. Anything richer can still opt in via a hook or the
+ * `@rastackResource` tag.
+ */
+function isDataClass(decl) {
+    if (decl.heritageClauses?.length)
+        return false;
+    if (ts.getCombinedModifierFlags(decl) &
+        (ts.ModifierFlags.Abstract | ts.ModifierFlags.Ambient)) {
+        return false;
+    }
+    let properties = 0;
+    for (const member of decl.members) {
+        if (!ts.isPropertyDeclaration(member))
+            return false; // method/ctor/accessor
+        if (ts.getCombinedModifierFlags(member) & ts.ModifierFlags.Static)
+            continue;
+        properties += 1;
+    }
+    return properties > 0;
+}
 function analyzeProperties(decl, checker, scanned) {
     const props = [];
     for (const member of decl.members) {
-        if (!ts.isPropertySignature(member) || !member.type)
+        let prop;
+        if (ts.isPropertySignature(member) && member.type) {
+            prop = member;
+        }
+        else if (ts.isPropertyDeclaration(member) &&
+            (member.type || member.initializer) &&
+            !ts.isPrivateIdentifier(member.name) &&
+            !(ts.getCombinedModifierFlags(member) &
+                (ts.ModifierFlags.Static |
+                    ts.ModifierFlags.Private |
+                    ts.ModifierFlags.Protected))) {
+            prop = member;
+        }
+        if (!prop)
             continue;
-        const name = ts.isIdentifier(member.name) || ts.isStringLiteralLike(member.name)
-            ? member.name.text
+        const name = ts.isIdentifier(prop.name) || ts.isStringLiteralLike(prop.name)
+            ? prop.name.text
             : undefined;
         if (!name)
             continue;
-        props.push(analyzeProperty(name, member, checker, scanned));
+        props.push(analyzeProperty(name, prop, checker, scanned));
     }
     return props;
 }
 function analyzeProperty(name, member, checker, scanned) {
     let nullable = !!member.questionToken;
+    // A class field with no annotation infers its (widened) type from the
+    // initializer — `region = "EU"` is a string column defaulting to "EU".
+    if (!member.type) {
+        const type = checker.getTypeAtLocation(member);
+        const base = classifyType(type, scanned);
+        if (base === undefined) {
+            return { name, nullable, skip: "unsupported type — skipped" };
+        }
+        if (typeof base !== "string")
+            return { name, nullable, target: base };
+        const config = configFromTags(jsdocTags(member));
+        if (config.default === undefined) {
+            const dflt = initializerDefault(member);
+            if (dflt !== undefined)
+                config.default = dflt;
+        }
+        return scalarProp(name, base, config, nullable);
+    }
     // Unwrap parens and unions: strip null/undefined (→ nullable), and require a
     // single remaining arm (unions of string literals collapse to `string`).
     let typeNode = unwrapParens(member.type);
@@ -219,7 +281,7 @@ function analyzeProperty(name, member, checker, scanned) {
     // but is intentionally not an error. Arrays of scalars have no manifest shape.
     const element = arrayElement(typeNode);
     if (element) {
-        if (interfaceBehindTypeNode(element, checker, scanned)) {
+        if (entityBehindTypeNode(element, checker, scanned)) {
             return { name, nullable, inverse: true };
         }
         return { name, nullable, skip: "array fields are not supported — skipped" };
@@ -230,19 +292,44 @@ function analyzeProperty(name, member, checker, scanned) {
         return { name, nullable, skip: "unsupported type — skipped" };
     }
     if (typeof base !== "string") {
-        return { name, nullable, target: base }; // entity interface → FK
+        return { name, nullable, target: base }; // entity class/interface → FK
     }
     const config = {
         ...configFromTags(jsdocTags(member)),
         ...configFromType(type, checker, member),
     };
+    if (config.default === undefined) {
+        const dflt = initializerDefault(member);
+        if (dflt !== undefined)
+            config.default = dflt;
+    }
     return scalarProp(name, base, config, nullable);
 }
+/** The literal value of a class field's initializer, used as the default. */
+function initializerDefault(member) {
+    if (!ts.isPropertyDeclaration(member) || !member.initializer)
+        return undefined;
+    const init = member.initializer;
+    if (ts.isStringLiteralLike(init))
+        return init.text;
+    if (ts.isNumericLiteral(init))
+        return Number(init.text);
+    if (ts.isPrefixUnaryExpression(init) &&
+        init.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(init.operand)) {
+        return -Number(init.operand.text);
+    }
+    if (init.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (init.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    return undefined;
+}
 /**
- * What a property type *is*: a manifest scalar, an entity interface (→ FK), or
- * unsupported. Intersections classify by their first classifiable constituent,
- * which is what lets `DbConfig` brands ride along — `string & Unique` is a
- * string; the brand carries configuration, not a datatype.
+ * What a property type *is*: a manifest scalar, an entity class/interface
+ * (→ FK), or unsupported. Intersections classify by their first classifiable
+ * constituent, which is what lets `DbConfig` brands ride along — `string &
+ * Unique` is a string; the brand carries configuration, not a datatype.
  */
 function classifyType(type, scanned) {
     if (type.flags & ts.TypeFlags.StringLike)
@@ -261,7 +348,7 @@ function classifyType(type, scanned) {
     }
     if (type.getProperty("__rastackDb"))
         return undefined; // a bare config brand
-    const decl = interfaceBehindType(type, scanned);
+    const decl = entityBehindType(type, scanned);
     if (decl)
         return decl;
     if (type.getSymbol()?.getName() === "Date")
@@ -390,6 +477,7 @@ function arrayElement(node) {
 }
 function entityNaming(decl) {
     const tags = jsdocTags(decl);
+    // Class candidates are only ever collected with a name (see analyzeEntities).
     const raw = decl.name.text;
     // Generated entity interfaces are `I`-prefixed (`IFlight`); strip the prefix
     // so hook usage of generated types resolves to the same resource.

package/dist/compile/index.d.ts

@@ -19,7 +19,7 @@ export interface CompileResult {
  * beside `app/airports/index.tsx` — instead of in one top-level `resources/`
  * folder. `.tsx` files carry no `resource(...)` definitions but are scanned
  * for the typed hook calls (`useEntityList<Airport>(…)`) that root the
- * interface-driven entity graph; co-located helpers are harmless.
+ * class/interface entity graph; co-located helpers are harmless.
  */
 export declare function resolveResourceFiles(input: string): string[];
 export interface ProjectAnalysis {

package/dist/compile/index.js

@@ -77,7 +77,7 @@ const IGNORE_DIRS = new Set([
  * beside `app/airports/index.tsx` — instead of in one top-level `resources/`
  * folder. `.tsx` files carry no `resource(...)` definitions but are scanned
  * for the typed hook calls (`useEntityList<Airport>(…)`) that root the
- * interface-driven entity graph; co-located helpers are harmless.
+ * class/interface entity graph; co-located helpers are harmless.
  */
 function resolveResourceFiles(input) {
     const stat = fs.existsSync(input) ? fs.statSync(input) : undefined;

package/dist/compile/program.js

@@ -55,7 +55,7 @@ function createProgram(fileNames) {
         esModuleInterop: true,
         noEmit: true,
         // `.tsx` app files are scanned for the typed hook calls that root the
-        // interface-driven entity graph.
+        // class/interface entity graph.
         jsx: ts.JsxEmit.ReactJSX,
         baseUrl: process.cwd(),
         paths: {

package/dist/define/db.d.ts

@@ -1,5 +1,5 @@
 /**
- * Type-level column configuration for interface-driven entities.
+ * Type-level column configuration for class- and interface-driven entities.
  *
  * Interface entities are plain TypeScript, so their column constraints are
  * expressed *in the type system*: intersect a property type with one or more

package/dist/define/db.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * Type-level column configuration for interface-driven entities.
+ * Type-level column configuration for class- and interface-driven entities.
  *
  * Interface entities are plain TypeScript, so their column constraints are
  * expressed *in the type system*: intersect a property type with one or more

package/dist/import/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `rastack import` — load external data (CSV, Excel, PDF) and validate it
+ * against a resource's constraint state machine.
+ *
+ * `parseTabular` dispatches on the file extension to the format parsers, all
+ * of which produce the same {@link TabularData}; `validateDataset` (in
+ * `tabular.ts`) is the shared, pure validation core.
+ */
+import type { TabularData } from "./tabular";
+export * from "./tabular";
+export { parseXlsx } from "./xlsx";
+export { parsePdfTable } from "./pdf";
+/** The source formats `rastack import` understands. */
+export type TabularFormat = "csv" | "xlsx" | "pdf";
+/** Infer the source format from a filename, or `null` if unsupported. */
+export declare function formatOf(fileName: string): TabularFormat | null;
+/** Parse a source file's bytes into headers + rows, by format. */
+export declare function parseTabular(format: TabularFormat, data: Buffer): TabularData;

package/dist/import/index.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * `rastack import` — load external data (CSV, Excel, PDF) and validate it
+ * against a resource's constraint state machine.
+ *
+ * `parseTabular` dispatches on the file extension to the format parsers, all
+ * of which produce the same {@link TabularData}; `validateDataset` (in
+ * `tabular.ts`) is the shared, pure validation core.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePdfTable = exports.parseXlsx = void 0;
+exports.formatOf = formatOf;
+exports.parseTabular = parseTabular;
+const csv_schema_1 = require("../csv-schema");
+const xlsx_1 = require("./xlsx");
+const pdf_1 = require("./pdf");
+__exportStar(require("./tabular"), exports);
+var xlsx_2 = require("./xlsx");
+Object.defineProperty(exports, "parseXlsx", { enumerable: true, get: function () { return xlsx_2.parseXlsx; } });
+var pdf_2 = require("./pdf");
+Object.defineProperty(exports, "parsePdfTable", { enumerable: true, get: function () { return pdf_2.parsePdfTable; } });
+/** Infer the source format from a filename, or `null` if unsupported. */
+function formatOf(fileName) {
+    const ext = fileName.toLowerCase().split(".").pop();
+    if (ext === "csv")
+        return "csv";
+    if (ext === "xlsx" || ext === "xlsm")
+        return "xlsx";
+    if (ext === "pdf")
+        return "pdf";
+    return null;
+}
+/** Parse a source file's bytes into headers + rows, by format. */
+function parseTabular(format, data) {
+    switch (format) {
+        case "csv":
+            return (0, csv_schema_1.parseCsv)(data.toString("utf-8"));
+        case "xlsx":
+            return (0, xlsx_1.parseXlsx)(data);
+        case "pdf":
+            return (0, pdf_1.parsePdfTable)(data);
+    }
+}

package/dist/import/pdf.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A tiny, dependency-free PDF *table* extractor for `rastack import`.
+ *
+ * PDFs carry no table structure — only positioned text — so this is
+ * deliberately a best-effort extractor for the common case of a machine-
+ * generated tabular report: it decodes every content stream (FlateDecode via
+ * node's zlib, plus raw streams), replays the text-positioning operators
+ * (`Tm`/`Td`/`TD`/`T*`) to give each shown string (`Tj`/`TJ`/`'`) an (x, y),
+ * clusters strings that share a baseline into rows, and orders each row's
+ * cells left-to-right. The first row becomes the header.
+ *
+ * Anything a text-line model can't represent — merged cells, wrapped cell
+ * text, scanned images — won't survive; for those, export the source data to
+ * CSV/XLSX instead. Every extracted value still goes through the constraint
+ * state machine, so a misread cell is *rejected with a located error*, never
+ * silently imported.
+ */
+import type { TabularData } from "./tabular";
+/**
+ * Parse a PDF buffer into headers + rows: text chunks sharing a baseline form
+ * a row (top of the page first), ordered left-to-right; the first row is the
+ * header. Rows with a different cell count than the header are padded or
+ * truncated — the state machine will flag what doesn't validate.
+ */
+export declare function parsePdfTable(buf: Buffer): TabularData;