rastack 0.0.46 → 0.0.48

package/src/compile/entities.ts

@@ -4,55 +4,67 @@ import { FieldModel, RelationModel, ResourceModel, ScalarType } from "./model";
 import { resourceSourceFiles } from "./program";
 
 /**
- * Interface-driven resource inference — "the entities in the app are a list of
- * interfaces".
+ * Type-driven resource inference — "the entities in the app are a list of
+ * plain TypeScript types".
  *
  * 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*:
+ * as plain TypeScript **classes or 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
+ *    the class/interface behind that type argument as an entity. A declaration
+ *    can also opt in explicitly with a `@rastackResource` JSDoc tag. And a
+ *    **plain data class** — no heritage clause, no methods or constructor,
+ *    only property declarations — is an entity by virtue of being declared:
+ *    writing `export class Airport { code: string }` is the whole authoring
+ *    step, no DSL and no tag required. (Interfaces are ubiquitous in app code,
+ *    so they still need a hook or a tag to root; an entity-shaped class is a
+ *    deliberate declaration.)
+ * 2. **Datatypes come from the properties.** 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.
+ *    Optional / `| null` properties become nullable fields. On a class, a
+ *    literal property initializer (`status = "scheduled"`) doubles as the
+ *    column default, and the property type may be inferred from it.
  * 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.
+ *    another entity class/interface is a foreign key, and the referenced
+ *    declaration is pulled into the resource graph transitively — the closure
+ *    of the rooted declarations 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 {
+ * // entities/airports.ts — plain data classes are entities by declaration
+ * export class Airport {
  *   code: string;   // JSDoc tags refine: @maxLength 3, @unique
  *   name: string;
  * }
- * export interface Terminal {
+ * export class Terminal {
  *   airport: Airport;   // FK — inferred from the property type
  *   label: string;
  * }
  *
+ * // interfaces root through usage instead:
  * // 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.
+ * Naming: `model` is the lower-camel class/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.
  */
 
+/** An entity can be declared as an interface or as a (named) class. */
+type EntityDecl = ts.InterfaceDeclaration | ts.ClassDeclaration;
+
 export interface EntityDiagnostic {
   severity: "error" | "warning";
   message: string;
@@ -72,20 +84,22 @@ export function analyzeEntities(
   const sourceFiles = 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.
-  const candidates = new Set<ts.InterfaceDeclaration>();
+  // Every class/interface declared in the scanned files is a *candidate* entity.
+  const candidates = new Set<EntityDecl>();
   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.
-  const roots: ts.InterfaceDeclaration[] = [];
-  const rooted = new Set<ts.InterfaceDeclaration>();
-  const addRoot = (decl: ts.InterfaceDeclaration) => {
+  // 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: EntityDecl[] = [];
+  const rooted = new Set<EntityDecl>();
+  const addRoot = (decl: EntityDecl) => {
     if (!rooted.has(decl)) {
       rooted.add(decl);
       roots.push(decl);
@@ -95,7 +109,7 @@ export function analyzeEntities(
     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);
         }
       }
@@ -104,12 +118,13 @@ export function analyzeEntities(
   }
   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.
-  const propsByDecl = new Map<ts.InterfaceDeclaration, PropInfo[]>();
-  const analyzed = (decl: ts.InterfaceDeclaration): PropInfo[] => {
+  // 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<EntityDecl, PropInfo[]>();
+  const analyzed = (decl: EntityDecl): PropInfo[] => {
     let props = propsByDecl.get(decl);
     if (!props) {
       props = analyzeProperties(decl, checker, scanned);
@@ -118,8 +133,8 @@ export function analyzeEntities(
     return props;
   };
 
-  const included: ts.InterfaceDeclaration[] = [];
-  const seen = new Set<ts.InterfaceDeclaration>();
+  const included: EntityDecl[] = [];
+  const seen = new Set<EntityDecl>();
   const queue = [...roots];
   while (queue.length) {
     const decl = queue.shift()!;
@@ -200,23 +215,24 @@ function isHookCall(call: ts.CallExpression): boolean {
   return !!name && /^use[A-Z0-9_]/.test(name);
 }
 
-/** Resolve a type node to an interface declared in one of the scanned files. */
-function interfaceBehindTypeNode(
+/** Resolve a type node to a class/interface declared in a scanned file. */
+function entityBehindTypeNode(
   node: ts.TypeNode,
   checker: ts.TypeChecker,
   scanned: Set<string>,
-): ts.InterfaceDeclaration | undefined {
-  return interfaceBehindType(checker.getTypeFromTypeNode(node), scanned);
+): EntityDecl | undefined {
+  return entityBehindType(checker.getTypeFromTypeNode(node), scanned);
 }
 
-function interfaceBehindType(
+function entityBehindType(
   type: ts.Type,
   scanned: Set<string>,
-): ts.InterfaceDeclaration | undefined {
+): EntityDecl | undefined {
   const symbol = type.aliasSymbol ?? type.getSymbol();
   for (const decl of symbol?.declarations ?? []) {
     if (
-      ts.isInterfaceDeclaration(decl) &&
+      (ts.isInterfaceDeclaration(decl) ||
+        (ts.isClassDeclaration(decl) && decl.name)) &&
       scanned.has(path.resolve(decl.getSourceFile().fileName))
     ) {
       return decl;
@@ -225,6 +241,31 @@ function interfaceBehindType(
   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: ts.ClassDeclaration): boolean {
+  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;
+}
+
 // -- property analysis --------------------------------------------------------
 
 interface PropInfo {
@@ -232,43 +273,79 @@ interface PropInfo {
   nullable: boolean;
   /** Scalar field (mutually exclusive with `target`). */
   field?: FieldModel;
-  /** FK target interface (relation resolved after naming). */
-  target?: ts.InterfaceDeclaration;
+  /** FK target declaration (relation resolved after naming). */
+  target?: EntityDecl;
   /** `Entity[]` — the reverse side of a FK; contributes no column. */
   inverse?: boolean;
   /** Unsupported type — reported as a warning and skipped. */
   skip?: string;
 }
 
+/** A column-shaped member: an interface property or a class instance field. */
+type EntityProp = ts.PropertySignature | ts.PropertyDeclaration;
+
 function analyzeProperties(
-  decl: ts.InterfaceDeclaration,
+  decl: EntityDecl,
   checker: ts.TypeChecker,
   scanned: Set<string>,
 ): PropInfo[] {
   const props: PropInfo[] = [];
   for (const member of decl.members) {
-    if (!ts.isPropertySignature(member) || !member.type) continue;
+    let prop: EntityProp | undefined;
+    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
+      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: string,
-  member: ts.PropertySignature,
+  member: EntityProp,
   checker: ts.TypeChecker,
   scanned: Set<string>,
 ): PropInfo {
   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!);
+  let typeNode = unwrapParens(member.type);
   if (ts.isUnionTypeNode(typeNode)) {
     const arms = typeNode.types.filter((t) => {
       const isNullish =
@@ -290,7 +367,7 @@ function analyzeProperty(
   // 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" };
@@ -302,26 +379,50 @@ function analyzeProperty(
     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: EntityProp,
+): string | number | boolean | undefined {
+  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: ts.Type,
   scanned: Set<string>,
-): ScalarType | ts.InterfaceDeclaration | undefined {
+): ScalarType | EntityDecl | undefined {
   if (type.flags & ts.TypeFlags.StringLike) return "string";
   if (type.flags & ts.TypeFlags.NumberLike) return "float";
   if (type.flags & ts.TypeFlags.BooleanLike) return "bool";
@@ -333,7 +434,7 @@ function classifyType(
     return undefined;
   }
   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") return "datetime";
   return undefined;
@@ -476,9 +577,10 @@ interface EntityNaming {
   permission?: ResourceModel["permission"];
 }
 
-function entityNaming(decl: ts.InterfaceDeclaration): EntityNaming {
+function entityNaming(decl: EntityDecl): EntityNaming {
   const tags = jsdocTags(decl);
-  const raw = decl.name.text;
+  // 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.
   const stripped = /^I[A-Z]/.test(raw) ? raw.slice(1) : raw;

package/src/compile/index.ts

@@ -39,7 +39,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.
  */
 export function resolveResourceFiles(input: string): string[] {
   const stat = fs.existsSync(input) ? fs.statSync(input) : undefined;

package/src/compile/program.ts

@@ -20,7 +20,7 @@ export function createProgram(fileNames: string[]): ts.Program {
     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/src/define/db.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/src/import/index.ts

@@ -0,0 +1,41 @@
+/**
+ * `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 { parseCsv } from "../csv-schema";
+import { parseXlsx } from "./xlsx";
+import { parsePdfTable } from "./pdf";
+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 function formatOf(fileName: string): TabularFormat | null {
+  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. */
+export function parseTabular(format: TabularFormat, data: Buffer): TabularData {
+  switch (format) {
+    case "csv":
+      return parseCsv(data.toString("utf-8"));
+    case "xlsx":
+      return parseXlsx(data);
+    case "pdf":
+      return parsePdfTable(data);
+  }
+}