@fougere/core 0.17.3-alpha.0 → 0.18.0-alpha.0

package/src/wire/Addresses.ts

@@ -1,17 +1,17 @@
 import type { FougereOperations } from './FougereOperations.js';
 
-type Served = keyof FougereOperations & string;
+type Generated = keyof FougereOperations & string;
 
 /**
  * Both halves below take the union through a type PARAMETER, which is what makes the
- * conditional distribute: `Served` is an alias, and an alias is matched whole — `'a.x' | 'b.y'`
+ * conditional distribute: `Generated` is an alias, and an alias is matched whole — `'a.x' | 'b.y'`
  * does not extend `` `${string}.${string}` `` as one thing, so the naive form answers `never`.
  */
 type AddressIn<Key> = Key extends `${infer Address}.${string}` ? Address : never;
 
 /**
  * The addresses this app answers at — or any string, until a scan has said otherwise. The
- * `[Served] extends [never]` form is what keeps an ungenerated project compiling: a bare `never`
+ * `[Generated] extends [never]` form is what keeps an ungenerated project compiling: a bare `never`
  * in a parameter position refuses every call, the correct ones included.
  */
-export type Addresses = [Served] extends [never] ? string : AddressIn<Served>;
+export type Addresses = [Generated] extends [never] ? string : AddressIn<Generated>;

package/src/wire/Cardinality.ts

@@ -0,0 +1,4 @@
+/** How MUCH an operation answers — the half of a return type that a view cannot say. */
+export const CARDINALITIES = ['one', 'maybe', 'many', 'page', 'none'] as const;
+
+export type Cardinality = (typeof CARDINALITIES)[number];

package/src/wire/OperationContract.ts

@@ -5,6 +5,7 @@ import type { TypeRef } from './TypeRef.js';
 import type { ErrorCode } from './ErrorCode.js';
 import type { OperationKind } from './OperationKind.js';
 import type { OperationKindInference } from './OperationKindInference.js';
+import type { Cardinality } from './Cardinality.js';
 
 /** The contract of one operation — everything the façade needs to serve a call. */
 export interface OperationContract {
@@ -17,7 +18,7 @@ export interface OperationContract {
   /** The operation in words, for a caller that meets it over the wire and has to choose. */
   description?: string;
   /** How MUCH comes back — the half of the return type that `output` cannot say. */
-  cardinality?: 'one' | 'maybe' | 'many' | 'page' | 'none';
+  cardinality?: Cardinality;
   /** The argument names and TYPES — the one thing `binding` cannot say. */
   signature?: Signature;
   /**

package/src/wire/OperationKind.ts

@@ -1 +1,4 @@
-export type OperationKind = 'query' | 'command';
+/** `query` reads, `command` writes — the same call REST turns into GET vs POST. */
+export const OPERATION_KINDS = ['query', 'command'] as const;
+
+export type OperationKind = (typeof OPERATION_KINDS)[number];

package/src/wire/Placement.ts

@@ -0,0 +1,4 @@
+/** Where something answers — in this process, or a process away. */
+export const PLACEMENTS = ['local', 'remote'] as const;
+
+export type Placement = (typeof PLACEMENTS)[number];

package/src/wire/RouteKind.ts

@@ -1,2 +1,4 @@
+import type { Placement } from './Placement.js';
+
 /** Which kind of destination served a call — it travels in a `CallRecord`. */
-export type RouteKind = 'local' | 'remote' | 'system';
+export type RouteKind = Placement | 'system';

package/src/wire/StateShape.ts

@@ -1,4 +1,4 @@
-import { InputValidator, dotted, optional, type Field, type Fields } from '@fougere/schema';
+import { Schema, dotted, optional, type Field, type Fields, type SchemaConstructor, type SchemaView } from '@fougere/schema';
 import { ErrorCode } from './ErrorCode.js';
 import { FougereError } from './FougereError.js';
 
@@ -16,19 +16,16 @@ export interface StateDeclaration {
  * Documented: [collectors](https://fougere.dev/docs/business/collectors).
  */
 export class StateShape {
-  static readonly empty = new StateShape({});
+  static readonly empty = new StateShape(Schema.of({ fields: {} }));
 
-  private readonly validator: InputValidator;
-
-  private constructor(private readonly fields: Fields) {
-    this.validator = InputValidator.of(fields);
-  }
+  private constructor(private readonly schema: SchemaView) {}
 
   /** Two extensions declaring one member refuse: the field that judges it would depend on wiring order. */
   static of(declarations: readonly StateDeclaration[]): StateShape {
-    const fields: Fields = {};
     const owners = new Map<string, string>();
+    let schema: SchemaConstructor<Fields> = Schema.of({ fields: {} as Fields });
     for (const { name, state } of declarations) {
+      const fields: Fields = {};
       for (const [member, field] of Object.entries(state ?? {})) {
         const owner = owners.get(member);
         if (owner) {
@@ -40,9 +37,10 @@ export class StateShape {
         owners.set(member, name);
         fields[member] = optional(field);
       }
+      schema = schema.extend(fields);
     }
 
-    return new StateShape(fields);
+    return new StateShape(schema);
   }
 
   /**
@@ -58,10 +56,10 @@ export class StateShape {
     const written = Object.fromEntries(Object.entries(state).filter(([member, value]) => entered[member] !== value));
     if (Object.keys(written).length === 0) return state;
 
-    const result = this.validator.validate(written);
+    const result = this.schema.validate(written);
     if (result.success) return { ...state, ...result.data };
 
-    const declared = Object.keys(this.fields);
+    const declared = Object.keys(this.schema.getFields());
     const errors = result.errors.map((error) => ({ ...error, path: ['state', ...error.path] }));
 
     throw new FougereError({

package/src/wire/TypeRef.ts

@@ -16,4 +16,6 @@ export interface TypeRef {
   undefined?: boolean;
   /** Whether this is a Promise wrapper (unwrapped in output). */
   promise?: boolean;
+  /** `Post['id']` — the entity whose primary key this value is, and the field holding it. */
+  identifies?: { entity: string; field: string };
 }

package/src/wire/binding.ts

@@ -17,7 +17,8 @@ type ParamSource =
    * (`Emissions.stamped`, which realizes `created()`); this is the declared form of it.
    */
   | { kind: 'pipe'; factName: string }
-  | { kind: 'param'; name: string; coerce?: 'number' | 'boolean' }
+  /** `identifies` names the entity whose row the value designates — `id: Post['id']`. */
+  | { kind: 'param'; name: string; coerce?: 'number' | 'boolean'; identifies?: string }
   | { kind: 'input' }
   | { kind: 'context' }
   /** The whole query bag, for an op whose argument IS the options (list). */
@@ -76,7 +77,11 @@ function sourceOf(param: Param, collectorTypeNames: Set<string>): ParamSource {
 
   if (collectorTypeNames.has(typeKey)) return { kind: 'collector', typeName: typeKey };
   if (typeName === 'InvocationContext') return { kind: 'context' };
-  if (PRIMITIVES.has(typeName)) return { kind: 'param', name: param.name, coerce: coercionFor(typeName) };
+  if (PRIMITIVES.has(typeName)) {
+    const identifies = param.type.identifies?.entity;
+
+    return { kind: 'param', name: param.name, coerce: coercionFor(typeName), ...(identifies && { identifies }) };
+  }
 
   return { kind: 'input' };
 }

package/src/wire/card/CardOp.ts

@@ -1,24 +1,18 @@
 import type { SchemaDescriptor } from '@fougere/schema';
-import type { ErrorCode } from '../ErrorCode.js';
+import type { OperationContract } from '../OperationContract.js';
+import type { OperationKind } from '../OperationKind.js';
 
 /**
  * One operation, as a stranger meets it — its name, what it is for, what it takes and whether it
  * reads or writes.
  */
-export interface CardOp {
+export interface CardOp extends Pick<OperationContract, 'description' | 'cardinality' | 'errors'> {
   name: string;
-  /** The author's own doc sentence, when the method carries one. */
-  description?: string;
   /** JSON Schema of what it accepts, when the contract names a view. */
   input?: SchemaDescriptor;
   /** JSON Schema of what it emits, when the contract names one. */
   output?: SchemaDescriptor;
-  /** `query` reads, `command` writes — the same call REST turns into GET vs POST. */
-  kind: 'query' | 'command';
-  /** How much `output` describes. */
-  cardinality?: 'one' | 'maybe' | 'many' | 'page' | 'none';
-  /** What this op can REFUSE, beyond what `kind` and `input` already imply. */
-  errors?: ErrorCode[];
+  kind: OperationKind;
   /** The fact this op is handed when it is announced — its `Fact<T>`, which IS the subscription. */
   listens?: string;
 }

package/src/wire/refusals.ts

@@ -14,10 +14,11 @@
  * Documented: [observability](https://fougere.dev/docs/infra/observability).
  */
 import { ErrorCode } from './ErrorCode.js';
+import type { OperationKind } from './OperationKind.js';
 
 /** The little of an operation this reads — so a card op and an effective one both fit. */
 export interface Refusable {
-  kind?: 'query' | 'command';
+  kind?: OperationKind;
   input?: unknown;
   errors?: readonly string[];
   /** Absent on a card op read from a frond that answers in this process. */

package/src/wire/topology/DeclaredFrond.ts

@@ -1,7 +1,9 @@
+import type { Placement } from '../Placement.js';
+
 /** A frond the config knows of, and where it says to reach it. */
 export interface DeclaredFrond {
   frond: string;
-  placement: 'local' | 'remote';
+  placement: Placement;
   /**
    * Host and port of the address `remotes:` names, absent when the frond runs here. Never the
    * whole address: a declared one may carry credentials, and this answer leaves the process.

package/src/wire/topology/FrondPlacement.ts

@@ -1,7 +1,9 @@
+import type { Placement } from '../Placement.js';
+
 /** A frond this process knows about, and whether it runs here. */
 export interface FrondPlacement {
   frond: string;
-  placement: 'local' | 'remote';
+  placement: Placement;
   entities: number;
   facades: number;
 }