@c9up/station 0.1.6 → 0.1.8

package/dist/StationProvider.d.ts

@@ -18,6 +18,7 @@
  * swallowed.
  */
 import type { ColumnMetadata } from "@c9up/atlas";
+import type { Resource } from "./types.js";
 /**
  * Duck-typed slice of the host's IoC container — Station MUST stay
  * publishable without importing `@c9up/ream` directly (memory
@@ -25,7 +26,7 @@ import type { ColumnMetadata } from "@c9up/atlas";
  */
 interface StationContainer {
     singleton<T>(key: unknown, factory: () => T): void;
-    resolve<T>(key: unknown): T;
+    resolve<T>(key: unknown): Promise<T>;
     has(key: unknown): boolean;
 }
 interface StationConfigStore {
@@ -35,6 +36,54 @@ export interface StationAppContext {
     container: StationContainer;
     config: StationConfigStore;
 }
+/** A rune `RuleChain` — only the builders the derivation calls. */
+interface RuneRuleChain {
+    optional(): RuneRuleChain;
+    nullable(): RuneRuleChain;
+    parse(fn: (value: unknown) => unknown): RuneRuleChain;
+}
+/** rune's `rules` factory — the constructors Station maps columns to. */
+interface RuneRules {
+    string(): RuneRuleChain;
+    number(): RuneRuleChain;
+    boolean(): RuneRuleChain;
+    /** Type-free chain — a structural (`json`/`jsonb`) column that must accept objects/arrays. */
+    any(): RuneRuleChain;
+}
+/** A single rune `ValidationError`. */
+interface RuneValidationError {
+    field: string;
+    rule: string;
+    message: string;
+    index?: number;
+    meta?: Record<string, unknown>;
+}
+/** Result of `schema.validateResult()` — synchronous, never throws. */
+type RuneValidationResult = {
+    valid: true;
+    errors: ReadonlyArray<RuneValidationError>;
+    data: Record<string, unknown>;
+} | {
+    valid: false;
+    errors: ReadonlyArray<RuneValidationError>;
+    data?: undefined;
+};
+/**
+ * A built rune schema — only the result-based check is consumed.
+ *
+ * `validateResult`, NOT `validate`: rune reserves `validate()` for the VineJS
+ * contract (async, throwing). Reading `.valid` off a Promise gives `undefined`,
+ * so keeping the old name would have made every admin write fail closed with an
+ * empty error list.
+ */
+interface RuneSchema {
+    validateResult(data: unknown): RuneValidationResult;
+}
+/** Lazy-imported `@c9up/rune` value surface (mirror `AtlasModule`). */
+interface RuneModule {
+    schema(fields: Record<string, RuneRuleChain>): RuneSchema;
+    rules: RuneRules;
+}
 /**
  * Config block read from `app.config.get<StationConfig>('station')`.
  * Every field is optional — the defaults match the 54.2 / 54.3 / 54.4
@@ -68,26 +117,53 @@ export interface StationConfig {
 /** @internal Reset module-level flags between tests. */
 export declare function resetStationProviderFlags(): void;
 /**
- * Mass-assignment guard. Only accepts keys that are:
- *   1. A declared `@Column` propertyKey on the resource entity, AND
- *   2. Not the primary key (DB-managed), AND
- *   3. Not a framework-managed timestamp. Two signals, both honoured:
- *      (a) the Lucid-style auto flag — `@column.dateTime({ autoCreate })` /
- *          `{ autoUpdate }` (passed in via `autoManaged`); this is the
- *          authoritative one and catches custom-named timestamp columns
- *          (e.g. `registeredAt`) the name list below would miss, AND
- *      (b) the conventional name fallback (created_at / updated_at /
- *          deleted_at) for plain `@Column` timestamps declared without the
- *          auto flag.
+ * True when at least one resource mounts a write action that maps a request
+ * body onto columns (create / edit). `destroy` needs no body validation. This
+ * is the AC7 predicate: it decides whether `@c9up/rune` is REQUIRED at boot —
+ * exported so `agnostic-peers-missing.test.ts` can pin the decision directly
+ * (the dynamic-import-absent path can't be simulated inside vitest, exactly as
+ * for atlas — see that file's header).
+ */
+export declare function resourcesNeedValidation(resources: ReadonlyArray<Resource>): boolean;
+/**
+ * Derive a `@c9up/rune` validation schema (57.7) from an entity's writable
+ * column metadata — the structural replacement for the hand-rolled
+ * `filterWritableBody`. The mass-assignment guarantee is now INHERENT:
+ * `schema.validateResult()` returns only declared-column keys, so unknown body keys
+ * (`role`, `passwordHash`, PK, timestamps) are dropped automatically — no
+ * explicit filtering pass.
  *
- * The `_method` synthetic field from browser-form method-overrides is
- * dropped automatically because it never matches a column propertyKey.
+ * Excluded, exactly as the old guard did: the primary key, framework-managed
+ * timestamps (both the Lucid-style `autoManaged` flag AND the `created_at /
+ * updated_at / deleted_at` name convention) — plus, new in 57.7, relations and
+ * the soft-delete column (`excludedProps`). Metadata is read column-by-column,
+ * NEVER `in` on an instance (`@Column() declare` makes `in` always false —
+ * mirror `BaseRepository.#hydrate`).
  *
- * Returning a fresh object — never the caller's reference — so a
- * downstream mutation can't poison the audit snapshot.
+ * Per-column rule mapping tolerates the form-post wire shape (values arrive as
+ * strings — rune does NOT coerce): booleans `.parse(isCheckedValue)`, numbers
+ * `.parse` string→Number (NaN falls through to a type error), everything else
+ * `rules.string()`. `.parse`/`.optional`/`.nullable` force rune's TS path, so
+ * no native `.node` is touched.
+ *
+ * Returns the built schema plus the set of boolean columns — the handler
+ * default-fills an ABSENT boolean key to `false` before validating (an
+ * unchecked checkbox submits nothing; this preserves the old edit-clears-box
+ * behaviour).
+ */
+export declare function deriveWritableSchema(columns: ReadonlyArray<ColumnMetadata>, pkColumn: string, autoManaged: ReadonlySet<string>, excludedProps: ReadonlySet<string>, rune: RuneModule): {
+    schema: RuneSchema;
+    booleanKeys: ReadonlySet<string>;
+};
+/**
+ * Validate a request body against a derived schema (57.7). Default-fills any
+ * ABSENT boolean column to `false` first (unchecked checkbox = no submission),
+ * preserving the old `filterWritableBody` checkbox semantics, then runs rune's
+ * synchronous, never-throwing `validateResult()`. On success `result.data` holds only
+ * declared-column keys (mass-assignment inherent). Exported for the unit tests
+ * that pin the coercion CRUX.
  */
-/** @internal Exported for unit tests — the mass-assignment + checkbox coercion guard. */
-export declare function filterWritableBody(body: Record<string, unknown>, columns: ReadonlyArray<ColumnMetadata>, pkColumn: string, autoManaged: ReadonlySet<string>): Record<string, unknown>;
+export declare function validateWritableBody(schema: RuneSchema, booleanKeys: ReadonlySet<string>, body: Record<string, unknown>): RuneValidationResult;
 export default class StationProvider {
     #private;
     protected app: StationAppContext;

package/dist/StationProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StationProvider.d.ts","sourceRoot":"","sources":["../src/StationProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAEX,cAAc,EAGd,MAAM,aAAa,CAAC;AAYrB;;;;GAIG;AACH,UAAU,gBAAgB;IACzB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACnD,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,GAAG,CAAC,CAAC;IAC5B,GAAG,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;CAC3B;AAED,UAAU,kBAAkB;IAC3B,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IACjC,SAAS,EAAE,gBAAgB,CAAC;IAC5B,MAAM,EAAE,kBAAkB,CAAC;CAC3B;AA2MD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAaD,wDAAwD;AACxD,wBAAgB,yBAAyB,IAAI,IAAI,CAMhD;AAaD;;;;;;;;;;;;;;;;;;GAkBG;AACH,yFAAyF;AACzF,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,EACtC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BzB;AAmDD,MAAM,CAAC,OAAO,OAAO,eAAe;;IAgBvB,SAAS,CAAC,GAAG,EAAE,iBAAiB;gBAAtB,GAAG,EAAE,iBAAiB;IAE5C,QAAQ,IAAI,IAAI;IAWV,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAMrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0PtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAEtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CA+iB/B;AAwED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAItD"}
+{"version":3,"file":"StationProvider.d.ts","sourceRoot":"","sources":["../src/StationProvider.ts"],"names":[],"mappings":"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"}