@nifrajs/schema 3.5.0 → 4.0.0

package/dist/t.js

@@ -1,13 +1,32 @@
-import { Type, } from "@sinclair/typebox";
+import { CloneType, Kind, Type, TypeRegistry, } from "@sinclair/typebox";
 import { fromTypeBox } from "./adapter.js";
-/** Pull each property's raw TypeBox schema out of its `NifraSchema` wrapper. */
-function unwrap(props) {
+import { fileOps, refuseFile } from "./file-kind.js";
+const DEFERRED_KIND = "NifraDeferred";
+/** Where `@nifrajs/web`'s output guard finds the inner schema's validate. Registered for two copies. */
+const DEFERRED_VALIDATE = Symbol.for("nifra.schema.deferredValidate");
+const isDeferredValue = (_, value) => typeof value === "object" &&
+    value !== null &&
+    value.__nifra_deferred === true &&
+    typeof value.promise?.then === "function";
+/**
+ * Pull each property's raw TypeBox schema out of its `NifraSchema` wrapper. `where` names the calling
+ * constructor: these objects are checked as JSON, so a file field is refused here (it belongs in
+ * `t.form` from `@nifrajs/schema/form`) instead of failing every request later.
+ */
+function unwrap(where, props) {
     const out = {};
     // Object.entries → own enumerable string keys only (no prototype walk).
-    for (const [key, schema] of Object.entries(props))
+    for (const [key, schema] of Object.entries(props)) {
+        refuseFile(where, schema.jsonSchema);
         out[key] = schema.jsonSchema;
+    }
     return out;
 }
+/** An open object whose scalar fields are coerced from strings - the shape of every request input
+ * that arrives as name/value text (a query string, a `Cookie` header). */
+const textFields = (where) => (props, options) => fromTypeBox(Type.Object(unwrap(where, props), { additionalProperties: true, ...options }), {
+    coerce: true,
+});
 /**
  * The built-in schema builder. Each constructor returns a `NifraSchema` - a
  * Standard Schema whose validated output type flows into `c.body`/`c.query`, and
@@ -31,28 +50,46 @@ export const t = {
     // rule. A body with extra keys fails validation (a 422), so `c.body` never carries attacker-supplied
     // properties (no mass-assignment). Use `t.looseObject` (or pass `{ additionalProperties: true }`) to
     // opt into an open object; an explicit `options.additionalProperties` always wins over the default.
-    object: (props, options) => fromTypeBox(Type.Object(unwrap(props), { additionalProperties: false, ...options })),
+    object: (props, options) => fromTypeBox(Type.Object(unwrap("t.object", props), { additionalProperties: false, ...options })),
     /** Like `t.object` but ACCEPTS (and passes through) unknown fields - the explicit opt-out of the
      * strict default. Prefer `t.object` unless you genuinely need an open object. */
-    looseObject: (props, options) => fromTypeBox(Type.Object(unwrap(props), { additionalProperties: true, ...options })),
-    array: (item, options) => fromTypeBox(Type.Array(item.jsonSchema, options)),
-    /** Marks a property optional inside `t.object`; standalone it is `T | undefined`. */
-    optional: (schema) => fromTypeBox(Type.Optional(schema.jsonSchema)),
+    looseObject: (props, options) => fromTypeBox(Type.Object(unwrap("t.looseObject", props), { additionalProperties: true, ...options })),
+    /**
+     * A list. A list of `t.file()` (from `@nifrajs/schema/form`) honors `minItems` / `maxItems` and is
+     * used inside `t.form`.
+     */
+    array: (item, options) => fileOps("t.array", item)?.array(item, options) ??
+        fromTypeBox(Type.Array(item.jsonSchema, options)),
+    /** Marks a property optional inside `t.object` / `t.form`; standalone it is `T | undefined`. */
+    optional: (schema) => {
+        const plain = () => fromTypeBox(Type.Optional(schema.jsonSchema));
+        return (fileOps("t.optional", schema)?.optional(schema) ??
+            plain());
+    },
     // `const S` captures the argument as a tuple; the explicit return type then maps
     // over that captured tuple (`S[K]["jsonSchema"]`) so the union's `Static` is
     // `A | B`, not `unknown` - the value-level `.map` can't preserve per-element
     // types, so the output type is derived from `S` and the result cast to match
     // (order/length are preserved by `map`, so the tuple shape is sound).
-    union: (schemas) => fromTypeBox(Type.Union(schemas.map((schema) => schema.jsonSchema))),
-    record: (value, options) => fromTypeBox(Type.Record(Type.String(), value.jsonSchema, options)),
+    union: (schemas) => fromTypeBox(Type.Union(schemas.map((schema) => {
+        refuseFile("t.union", schema.jsonSchema);
+        return schema.jsonSchema;
+    }))),
+    record: (value, options) => {
+        refuseFile("t.record", value.jsonSchema);
+        return fromTypeBox(Type.Record(Type.String(), value.jsonSchema, options));
+    },
     // Composed from TypeBox directly (not `t.object`/`t.array`) so the `t` literal doesn't reference
     // itself during inference. Cursor pagination - not OFFSET - is the production default: stable under
     // concurrent inserts and O(1) per page. Build pages with `paginate()` + `encodeCursor`/`decodeCursor`.
     /** A cursor-pagination response envelope: `{ items: T[]; nextCursor: string | null }` (`null` = last page). */
-    paginated: (item, options) => fromTypeBox(Type.Object({
-        items: Type.Array(item.jsonSchema),
-        nextCursor: Type.Union([Type.String(), Type.Null()]),
-    }, { additionalProperties: false, ...options })),
+    paginated: (item, options) => {
+        refuseFile("t.paginated", item.jsonSchema);
+        return fromTypeBox(Type.Object({
+            items: Type.Array(item.jsonSchema),
+            nextCursor: Type.Union([Type.String(), Type.Null()]),
+        }, { additionalProperties: false, ...options }));
+    },
     /** A request query schema for cursor pagination: `{ cursor?: string; limit?: number }`. `maxLimit`
      * caps `limit` - a larger value fails validation (a 422), so a client can't request an unbounded page.
      * `coerce` is on because query values arrive as strings (`?limit=20` → `"20"`); it's what makes `limit`
@@ -70,8 +107,39 @@ export const t = {
      * traffic appends params your schema never declares, causing 422s that never appear in dev/CI). Pass
      * `{ additionalProperties: false }` to enforce a strict allowlist. This is the query-slot constructor;
      * `t.object` stays the constructor for body slots (no coercion, a JSON body is already typed). */
-    query: (props, options) => fromTypeBox(Type.Object(unwrap(props), { additionalProperties: true, ...options }), {
-        coerce: true,
-    }),
+    query: textFields("t.query"),
+    /** A request-cookie schema for the `cookies` route slot, with the same string->scalar COERCION as
+     * `t.query` (cookie values always arrive as strings). **Open by default**: a browser sends every
+     * cookie the site has set - analytics, consent, other routes' sessions - so a strict allowlist
+     * would 422 real traffic. Declare the cookies the route reads; the rest pass through. */
+    cookies: textFields("t.cookies"),
+    /**
+     * A loader value marked with `defer()`, streamed in after the shell. `inner` describes what the
+     * promise resolves to; `@nifrajs/web` projects and validates the resolved value by it before it
+     * streams, so a deferred value is held to the same output contract as the rest of the data.
+     */
+    deferred: (inner) => {
+        refuseFile("t.deferred", inner.jsonSchema);
+        if (!TypeRegistry.Has(DEFERRED_KIND))
+            TypeRegistry.Set(DEFERRED_KIND, isDeferredValue);
+        return fromTypeBox(Type.Unsafe({
+            [Kind]: DEFERRED_KIND,
+            "x-nifra-deferred": true,
+            inner: inner.jsonSchema,
+            [DEFERRED_VALIDATE]: inner["~standard"].validate,
+        }));
+    },
+    /**
+     * Allow a field with a sensitive name (`token`, `password`, `apiKey`, ...) in an output schema.
+     * An output schema that declares one without this fails at route load; `reason` records why this
+     * value may reach the browser, for the reviewer who finds it later.
+     */
+    declassified: (reason, schema) => {
+        if (typeof reason !== "string" || reason.trim() === "") {
+            throw new TypeError("t.declassified: give the reason this field may reach the browser");
+        }
+        refuseFile("t.declassified", schema.jsonSchema);
+        return fromTypeBox(CloneType(schema.jsonSchema, { "x-nifra-declassified": reason }));
+    },
 };
 //# sourceMappingURL=t.js.map

package/dist/t.js.map

@@ -1 +1 @@
-{"version":3,"file":"t.js","sourceRoot":"","sources":["../src/t.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"t.js","sourceRoot":"","sources":["../src/t.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/schema",
-  "version": "3.5.0",
+  "version": "4.0.0",
   "description": "Built-in schema builder `t` - TypeBox-backed (free JSON Schema + compiled validators), implements Standard Schema so nifra routes validate it natively.",
   "keywords": [
     "bun",
@@ -16,6 +16,9 @@
     "standard-schema"
   ],
   "type": "module",
+  "nifra": {
+    "environment": "library"
+  },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -25,6 +28,11 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./form": {
+      "bun": "./src/form.ts",
+      "types": "./dist/form.d.ts",
+      "default": "./dist/form.js"
+    },
     "./openapi": {
       "bun": "./src/openapi.ts",
       "types": "./dist/openapi.d.ts",
@@ -45,10 +53,11 @@
     "access": "public"
   },
   "dependencies": {
+    "@nifrajs/uploads": "4.0.0",
     "@sinclair/typebox": "^0.34.49"
   },
   "peerDependencies": {
-    "@nifrajs/core": "^3.5.0"
+    "@nifrajs/core": "^4.0.0"
   },
   "devDependencies": {
     "@nifrajs/core": "workspace:*",

package/src/adapter.ts

@@ -34,6 +34,21 @@ function toIssue(error: { readonly message: string; readonly path: string }): St
   }
 }
 
+// The issues past this are never reported (a 422 lists 100), so walking them is wasted work on a
+// large hostile body.
+const MAX_ISSUES = 100
+
+function firstIssues(
+  errors: Iterable<{ readonly message: string; readonly path: string }>,
+): StandardIssue[] {
+  const issues: StandardIssue[] = []
+  for (const error of errors) {
+    issues.push(toIssue(error))
+    if (issues.length === MAX_ISSUES) break
+  }
+  return issues
+}
+
 // ---------------------------------------------------------------------------------------------
 // Precompiled coercion for flat scalar objects - the shape every real query schema has.
 //
@@ -230,10 +245,10 @@ export function fromTypeBox<T extends TSchema>(
         }
         if (compiled !== undefined) {
           if (compiled.Check(input)) return { value: input as Static<T> }
-          return { issues: [...compiled.Errors(input)].map(toIssue) }
+          return { issues: firstIssues(compiled.Errors(input)) }
         }
         if (Value.Check(schema, input)) return { value: input as Static<T> }
-        return { issues: [...Value.Errors(schema, input)].map(toIssue) }
+        return { issues: firstIssues(Value.Errors(schema, input)) }
       },
       // Phantom: `types` carries no runtime value; this cast supplies the
       // compile-time `Static<T>` that nifra's `InferOutput` reads to type `c.body`.

package/src/file-kind.ts

@@ -0,0 +1,48 @@
+/**
+ * How `t` tells a file field apart without carrying the code that validates one.
+ *
+ * File fields come from `@nifrajs/schema/form`. They mark their JSON Schema, and the schema object
+ * brings its own list and optional constructors along, so `t.array` and `t.optional` handle a file
+ * while an app that never takes an upload ships none of that code.
+ */
+import { type ArrayOptions, Kind, type TSchema } from "@sinclair/typebox"
+import type { NifraSchema } from "./adapter.ts"
+
+/** Marks the JSON Schema of a file field. Registered, so two copies of this package agree on it. */
+export const FILE: unique symbol = Symbol.for("nifra.schema.file")
+
+/** Carries the file-aware constructors on a file schema. Registered for the same reason. */
+export const FILE_OPS: unique symbol = Symbol.for("nifra.schema.fileOps")
+
+export interface FileOps {
+  optional(schema: NifraSchema): NifraSchema
+  array(item: NifraSchema, options?: ArrayOptions): NifraSchema
+}
+
+type Marked = { readonly [FILE]?: true; readonly [Kind]?: string; readonly items?: TSchema }
+
+/** Whether a JSON Schema is a file field, or a list of them. */
+export function isFileSchema(schema: TSchema): boolean {
+  const node = schema as unknown as Marked
+  return (
+    node[FILE] === true ||
+    (node[Kind] === "Array" && node.items !== undefined && isFileSchema(node.items))
+  )
+}
+
+/** Throw when a constructor that validates JSON is handed a file field. */
+export function refuseFile(where: string, schema: TSchema): void {
+  if (isFileSchema(schema)) {
+    throw new TypeError(`${where}: a file field belongs in t.form() from "@nifrajs/schema/form"`)
+  }
+}
+
+/**
+ * The file-aware constructors of a file schema, or `undefined` for any other schema. A schema whose
+ * JSON Schema says "file" but which lost its validator is refused: TypeBox cannot check a file.
+ */
+export function fileOps(where: string, schema: NifraSchema): FileOps | undefined {
+  const ops = (schema as { readonly [FILE_OPS]?: FileOps })[FILE_OPS]
+  if (ops === undefined) refuseFile(where, schema.jsonSchema)
+  return ops
+}