typesea 0.2.0 → 0.3.0

package/dist/schema/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/schema/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoBH,OAAO,KAAK,EAER,MAAM,EAET,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAK7D"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/schema/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsBH,OAAO,KAAK,EAIR,MAAM,EAET,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAK7D"}

package/dist/schema/validate.js

@@ -4,7 +4,7 @@
  * @details Schema helpers enforce construction-time invariants before values reach
  * validation, compilation, or export.
  */
-import { NumberCheckTag, ObjectModeTag, PresenceTag, SchemaTag, StringCheckTag } from "../kind/index.js";
+import { ArrayCheckTag, DateCheckTag, NumberCheckTag, ObjectModeTag, PresenceTag, SchemaTag, StringCheckTag } from "../kind/index.js";
 import { isLiteralValue } from "./literal.js";
 import { includesString, isMissingDataProperty, isObjectKeyLookup, isPlainRegExp, isRecord, isStringArray, isUnknownArray, readOwnDataProperty } from "./common.js";
 /**
@@ -69,6 +69,8 @@ function isSchemaRecord(value, state) {
         case SchemaTag.Symbol:
         case SchemaTag.Boolean:
             return true;
+        case SchemaTag.Date:
+            return isDateChecks(readOwnDataProperty(value, "checks"));
         case SchemaTag.String:
             return isStringChecks(readOwnDataProperty(value, "checks"));
         case SchemaTag.Number:
@@ -82,11 +84,25 @@ function isSchemaRecord(value, state) {
             return !isMissingDataProperty(literal) && isLiteralValue(literal);
         }
         case SchemaTag.Array:
-            return isSchemaValueInner(readOwnDataProperty(value, "item"), state);
+            return isSchemaValueInner(readOwnDataProperty(value, "item"), state) &&
+                isArrayChecks(readOwnDataProperty(value, "checks"));
         case SchemaTag.Tuple:
-            return isSchemaArray(readOwnDataProperty(value, "items"), state);
+            return isSchemaArray(readOwnDataProperty(value, "items"), state) &&
+                isOptionalSchemaValue(readOwnDataProperty(value, "rest"), state);
         case SchemaTag.Record:
             return isSchemaValueInner(readOwnDataProperty(value, "value"), state);
+        case SchemaTag.Map:
+            return isSchemaValueInner(readOwnDataProperty(value, "key"), state) &&
+                isSchemaValueInner(readOwnDataProperty(value, "value"), state);
+        case SchemaTag.Set:
+            return isSchemaValueInner(readOwnDataProperty(value, "item"), state);
+        case SchemaTag.InstanceOf:
+            return typeof readOwnDataProperty(value, "constructor") === "function" &&
+                typeof readOwnDataProperty(value, "name") === "string";
+        case SchemaTag.Property:
+            return typeof readOwnDataProperty(value, "key") === "string" &&
+                isSchemaValueInner(readOwnDataProperty(value, "base"), state) &&
+                isSchemaValueInner(readOwnDataProperty(value, "value"), state);
         case SchemaTag.Object:
             return isObjectSchemaValue(value, state);
         case SchemaTag.Union:
@@ -113,6 +129,15 @@ function isSchemaRecord(value, state) {
             return false;
     }
 }
+/**
+ * @brief Validate an optional schema payload.
+ * @param value Candidate child schema or undefined.
+ * @param state Recursion state for child schemas.
+ * @returns True when the value is absent or a valid schema.
+ */
+function isOptionalSchemaValue(value, state) {
+    return value === undefined || isSchemaValueInner(value, state);
+}
 /**
  * @brief Validate the check vector attached to a string schema.
  * @param value Candidate check vector.
@@ -149,6 +174,13 @@ function isStringChecks(value) {
                 }
                 break;
             case StringCheckTag.Uuid:
+            case StringCheckTag.Email:
+            case StringCheckTag.Url:
+            case StringCheckTag.IsoDate:
+            case StringCheckTag.IsoDateTime:
+            case StringCheckTag.Ulid:
+            case StringCheckTag.Ipv4:
+            case StringCheckTag.Ipv6:
                 break;
             default:
                 return false;
@@ -176,7 +208,47 @@ function isNumberChecks(value) {
             case NumberCheckTag.Integer:
                 break;
             case NumberCheckTag.Gte:
-            case NumberCheckTag.Lte: {
+            case NumberCheckTag.Lte:
+            case NumberCheckTag.Gt:
+            case NumberCheckTag.Lt: {
+                const bound = readOwnDataProperty(check, "value");
+                if (typeof bound !== "number" || !Number.isFinite(bound)) {
+                    return false;
+                }
+                break;
+            }
+            case NumberCheckTag.MultipleOf: {
+                const divisor = readOwnDataProperty(check, "value");
+                if (typeof divisor !== "number" ||
+                    !Number.isFinite(divisor) ||
+                    divisor <= 0) {
+                    return false;
+                }
+                break;
+            }
+            default:
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * @brief Validate the check vector attached to a Date schema.
+ * @param value Candidate check vector.
+ * @returns True when every Date bound is finite epoch milliseconds.
+ */
+function isDateChecks(value) {
+    if (!isUnknownArray(value)) {
+        return false;
+    }
+    for (let index = 0; index < value.length; index += 1) {
+        const check = value[index];
+        if (!isRecord(check)) {
+            return false;
+        }
+        switch (readOwnDataProperty(check, "tag")) {
+            case DateCheckTag.Min:
+            case DateCheckTag.Max: {
                 const bound = readOwnDataProperty(check, "value");
                 if (typeof bound !== "number" || !Number.isFinite(bound)) {
                     return false;
@@ -189,6 +261,37 @@ function isNumberChecks(value) {
     }
     return true;
 }
+/**
+ * @brief Validate the check vector attached to an array schema.
+ * @param value Candidate check vector.
+ * @returns True when every array length bound is a non-negative integer.
+ * @details Array length checks are admitted once at schema construction so
+ * interpreters and code generators can emit direct `length` comparisons later.
+ */
+function isArrayChecks(value) {
+    if (!isUnknownArray(value)) {
+        return false;
+    }
+    for (let index = 0; index < value.length; index += 1) {
+        const check = value[index];
+        if (!isRecord(check)) {
+            return false;
+        }
+        switch (readOwnDataProperty(check, "tag")) {
+            case ArrayCheckTag.Min:
+            case ArrayCheckTag.Max: {
+                const bound = readOwnDataProperty(check, "value");
+                if (typeof bound !== "number" || !Number.isInteger(bound) || bound < 0) {
+                    return false;
+                }
+                break;
+            }
+            default:
+                return false;
+        }
+    }
+    return true;
+}
 /**
  * @brief Validate a dense vector of child schemas.
  * @details Schema helpers enforce construction-time invariants before values reach
@@ -226,10 +329,14 @@ function isObjectSchemaValue(value, state) {
     const entries = readOwnDataProperty(value, "entries");
     const keys = readOwnDataProperty(value, "keys");
     const keyLookup = readOwnDataProperty(value, "keyLookup");
+    const catchall = readOwnDataProperty(value, "catchall");
     if (!isUnknownArray(entries) || !isStringArray(keys) ||
         !isObjectKeyLookup(keyLookup, keys) || entries.length !== keys.length) {
         return false;
     }
+    if (catchall !== undefined && !isSchemaValueInner(catchall, state)) {
+        return false;
+    }
     const seen = [];
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];

package/docs/api.md

@@ -27,6 +27,7 @@ condition.
 interface Guard<T> {
   is(value: unknown): value is T;
   check(value: unknown): CheckResult<T>;
+  checkFirst(value: unknown): CheckResult<T>;
   assert(value: unknown): asserts value is T;
   graph(): Graph;
 }
@@ -36,6 +37,7 @@ interface Guard<T> {
 | --- | --- | --- |
 | `is` | Hot boolean narrowing | Avoids diagnostic allocation on the success path. |
 | `check` | Validation with issues | Returns frozen `Result<T, Issue[]>` containers. |
+| `checkFirst` | Hot rejection diagnostics | Returns the same frozen `Result` shape, but failure contains at most one issue. Compiled and AOT guards use a dedicated first-fault collector. |
 | `assert` | Throwing integration boundaries | Throws `TypeSeaAssertionError` with copied, frozen issues. |
 | `graph` | Runtime plan introspection | Returns the validated, optimized, frozen Sea-of-Nodes graph held by the validation plan. |
 
@@ -47,14 +49,19 @@ cross the API boundary.
 
 | Family | Builders |
 | --- | --- |
-| Scalars | `t.unknown`, `t.never`, `t.string`, `t.number`, `t.bigint`, `t.symbol`, `t.boolean` |
-| Literals and containers | `t.literal(value)`, `t.array(item)`, `t.tuple([a, b])`, `t.record(value)` |
+| Scalars | `t.unknown`, `t.never`, `t.string`, `t.number`, `t.date`, `t.bigint`, `t.symbol`, `t.boolean`, `t.null`, `t.undefined`, `t.void` |
+| String checks | `.min`, `.max`, `.length`, `.nonempty`, `.regex`, `.startsWith`, `.endsWith`, `.includes`, `.uuid`, `.email`, `.url`, `.isoDate`, `.isoDateTime`, `.ulid`, `.ipv4`, `.ipv6` |
+| Number checks | `.int`, `.finite`, `.safe`, `.gte`, `.lte`, `.min`, `.max`, `.gt`, `.lt`, `.multipleOf`, `.positive`, `.nonnegative`, `.negative`, `.nonpositive` |
+| Date checks | `.min`, `.max` |
+| Literals and containers | `t.literal(value)`, `t.enum(values)`, `t.array(item)`, `t.tuple([a, b])`, `t.tuple([head], rest)`, `t.record(value)`, `t.map(key, value)`, `t.set(item)`, `t.json()` |
+| Array checks | `.min`, `.max`, `.length`, `.nonempty` |
 | Objects | `t.object(shape)`, `t.strictObject(shape)` |
-| Object transforms | `t.extend`, `t.pick`, `t.omit`, `t.partial`, and matching object guard methods |
+| Object transforms | `t.extend`, `t.safeExtend`, `t.merge`, `t.pick`, `t.omit`, `t.partial`, `t.deepPartial`, `t.required`, `t.strict`, `t.passthrough`, `t.strip`, `t.catchall`, and matching object guard methods |
+| Runtime object contracts | `t.instanceOf(Ctor)`, `t.property(base, key, value)`, `guard.property(key, value)` |
 | Composition | `t.union`, `t.discriminatedUnion`, `t.intersect`, `guard.intersect` |
-| Presence | `t.optional`, `t.undefinedable`, `t.nullable` |
+| Presence | `t.optional`, `t.undefinedable`, `t.nullable`, `t.nullish` |
 | Dynamic guards | `t.lazy`, `t.refine` |
-| Decoders | `t.decoder`, `t.transform`, `t.pipe`, `t.coerce` |
+| Decoders | `t.decoder`, `t.transform`, `t.pipe`, `t.default`, `t.defaultValue`, `t.prefault`, `t.catch`, `t.codec`, `t.coerce`, `t.string.trim()`, `t.string.toLowerCase()`, `t.string.toUpperCase()` |
 | Async decoders | `t.asyncDecoder`, `t.asyncRefine`, `t.asyncTransform`, `t.asyncPipe` |
 
 Builder functions validate inputs before a schema can enter the validation plan,
@@ -80,6 +87,8 @@ const Shape = t.object({
 - `name` may be absent. If `name` exists, its value must be a string.
 - `nickname` must be present. Its value may be a string or `undefined`.
 - `t.nullable(inner)` adds `null` to the value domain.
+- `t.nullish(inner)` combines nullable value semantics with optional object-key
+  presence.
 - Presence-preserving wrappers keep optional-key semantics through `nullable`,
   `undefinedable`, `brand`, and `refine`.
 
@@ -87,6 +96,18 @@ Object combinators preserve object mode. Strict object guards remain strict
 after `extend`, `pick`, `omit`, or `partial`; passthrough object guards keep
 allowing unknown keys.
 
+`catchall(schema)` validates every undeclared own key with `schema`.
+`strip()` is validation-only in TypeSea: guards return the original value, so it
+has the same validation behavior as `passthrough()`.
+`pick` and `omit` accept either key arrays or Zod-style `{ key: true }` masks.
+`deepPartial()` recursively partializes pure object, array, tuple, tuple rest,
+record, map, set, property, union, intersection, nullable, undefinedable,
+optional, and brand schemas. Lazy and refinement schemas are semantic barriers.
+
+`property` validates only own data descriptors. It is useful for class instances
+with stable fields; prototype getters and accessor-backed properties are rejected
+instead of executed.
+
 ## Composition
 
 `t.union(a, b)` accepts a value that satisfies at least one branch.
@@ -125,6 +146,16 @@ lazy chain must eventually resolve to a concrete non-lazy schema.
 ```ts
 const Count = t.pipe(t.coerce.number(), t.number.int().gte(0));
 const result = Count.decode("42");
+
+const Name = t.default(t.string.min(1), "anonymous");
+const NumberText = t.codec(
+  t.string.regex(/^\d+$/u, "digits"),
+  t.number.int().nonnegative(),
+  {
+    decode: (value) => Number(value),
+    encode: (value) => String(value)
+  }
+);
 ```
 
 Decoders are for output-producing operations. They return `Result` from
@@ -134,8 +165,15 @@ not be the same runtime value as the input.
 - `t.transform(source, mapper)` decodes `source`, then maps the decoded value.
 - `t.pipe(source, next)` feeds a successful decoded value into the next guard or
   decoder.
+- `t.default(source, value)` returns a fallback output for `undefined` input.
+- `t.prefault(source, value)` feeds a fallback input through the source.
+- `t.codec(input, output, mapping)` validates both sides of a bidirectional
+  decode/encode pair.
 - `t.coerce.string`, `t.coerce.number`, and `t.coerce.boolean` provide explicit
   primitive coercion.
+- `t.string.trim()`, `t.string.toLowerCase()`, and `t.string.toUpperCase()`
+  are decoder helpers. They validate the string first, then return transformed
+  output from `decode()`.
 - `t.asyncRefine`, `t.asyncTransform`, and `t.asyncPipe` return
   `Promise<Result<T, Issue[]>>` from `decodeAsync()`.
 
@@ -152,14 +190,16 @@ const checked = withMessages(User.check(input), {
 });
 ```
 
-`formatIssue`, `formatIssues`, and `withMessages` render diagnostics after
-validation has finished. This keeps `is()` and ordinary `check()` paths free from
-message allocation.
+`formatIssue`, `formatIssues`, `flattenIssues`, and `withMessages` render
+diagnostics after validation has finished. This keeps `is()` and ordinary
+`check()` paths free from message allocation.
 
 Built-in locales are `en` and `ko`. Custom catalogs can use string templates
 with `{path}`, `{code}`, `{expected}`, and `{actual}`, or formatter callbacks.
 `withMessages(result, options)` preserves successful results and returns a new
 failed `Result` with copied, frozen issues whose `message` fields are populated.
+`flattenIssues(issues, options)` groups rendered messages into `formErrors` and
+top-level `fieldErrors` buckets.
 
 ## Runtime Compile
 
@@ -270,6 +310,28 @@ const resolver = toReactHookFormResolver(User);
 Adapters are structural and zero-dependency. TypeSea does not import tRPC,
 Fastify, or React Hook Form.
 
+Compiled guards can be passed to the same adapters. This is the preferred shape
+for hot request paths: compile once during startup, then let the adapter reuse
+the generated predicate.
+
+```ts
+const FastUser = compile(User);
+const fastParser = toTrpcParser(FastUser);
+const fastValidatorCompiler = toFastifyValidatorCompiler(FastUser);
+```
+
+Use the default compiled mode at public input boundaries. For trusted,
+already-normalized internal data, the faster modes can be wired through adapters
+the same way.
+
+```ts
+const UnsafeUser = compile(User, { mode: "unsafe" });
+const internalParser = toTrpcParser(UnsafeUser);
+
+const TrustedShapeUser = compile(User, { mode: "unchecked" });
+const internalValidatorCompiler = toFastifyValidatorCompiler(TrustedShapeUser);
+```
+
 | Adapter | Export | Behavior |
 | --- | --- | --- |
 | tRPC | `toTrpcParser`, `toAsyncTrpcParser` | Return parser objects that emit decoded values or throw `TypeSeaAssertionError`. |
@@ -314,6 +376,7 @@ Runtime-only concepts return explicit export issues:
 - `undefined`
 - `bigint`
 - `symbol`
+- JavaScript `Date`, `Map`, `Set`, `instanceOf`, and `property` contracts
 - `lazy`
 - `refine`
 - decoder transforms

package/docs/engine-notes.md

@@ -154,6 +154,10 @@ still checking the original object fields on the outer frame.
 Compiled `lazy` and `refine` fallbacks use the same IR-backed runtime path, so
 recursive behavior stays consistent across execution engines.
 
+`checkFirst()` has a separate generated collector. It returns one frozen issue
+as soon as the first diagnostic is known, instead of running the full `check()`
+collector and truncating its issue array.
+
 ## JSON Schema Export
 
 JSON Schema export succeeds only when the TypeSea schema can be represented over