@stacksjs/validation 0.70.45 → 0.70.54

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/conditional.d.ts

@@ -0,0 +1,59 @@
+import type { Validator } from '@stacksjs/ts-validation';
+/**
+ * Mixin: add `.when()` / `.sometimes()` to a validator instance.
+ *
+ * Mutates the validator in place (assigning the new methods) so the
+ * existing chainable surface (`.required()`, `.minLength()`, etc.)
+ * keeps returning `this`. Returns the same instance with the augmented
+ * type so callers see the new methods on the fluent chain.
+ */
+export declare function withConditionals<V extends Validator<any>>(validator: V): V & ConditionalAPI<V>;
+/**
+ * Evaluate a single `when` clause against a parent object.
+ *
+ * Returns `true` when the conditional should fire (and its refinement
+ * should be applied). Pure function — no side effects, safe to call
+ * during introspection too.
+ */
+export declare function shouldApplyConditional(record: ConditionalRecord<Validator<any>>, parent: Record<string, unknown> | null | undefined): boolean;
+/**
+ * Apply every matching conditional on `base` against `parent`, in
+ * registration order. Returns the (possibly refined) validator that
+ * should be used to validate the field.
+ *
+ * The base validator is NEVER mutated — ts-validation methods like
+ * `.required()` and `.min(3)` MUTATE `this` and return it, so calling
+ * refine functions directly on the base would leak across `validate()`
+ * invocations (each call would compound the previous refinements,
+ * making "VAT required for EU customers" sticky across requests).
+ * {@link cloneValidator} produces an isolated instance the refine
+ * pipeline can safely mutate without polluting the schema definition.
+ */
+export declare function applyConditionals<V extends Validator<any>>(base: V, parent: Record<string, unknown> | null | undefined): V;
+/**
+ * A single `.when()` clause attached to a field validator. Multiple
+ * `.when()` calls stack — they're evaluated in registration order and
+ * each matching one further refines the base validator.
+ */
+export declare interface ConditionalRecord<V extends Validator<any>> {
+  field: string
+  match: unknown | ((value: unknown) => boolean)
+  refine: (validator: V) => V
+}
+/** Anything that has a mutable conditionals array — duck-typed so this
+ *  works across all the ts-validation validator subclasses. */
+export declare interface ValidatorWithConditionals<V extends Validator<any>> {
+  __conditionals?: ConditionalRecord<V>[]
+}
+/**
+ * Conditional-rules surface — apps reach these methods through
+ * `.when()` / `.sometimes()` on any validator the schema proxy returns.
+ */
+export declare interface ConditionalAPI<V extends Validator<any>> {
+  when: (
+    field: string,
+    match: unknown | ((value: unknown) => boolean),
+    refine: (validator: V) => V,
+  ) => V & ConditionalAPI<V>
+  sometimes: () => V & ConditionalAPI<V>
+}

package/dist/file-validator.d.ts

@@ -0,0 +1,65 @@
+/** Factory matching ts-validation's `v.string()` / `v.number()` style. */
+export declare function file(): FileValidator;
+/**
+ * `schema.file()` — chainable validator for uploaded files
+ * (stacksjs/stacks#1856).
+ *
+ * Mirrors the ergonomics of `schema.string()` / `schema.number()` /
+ * `schema.enum()` from ts-validation but targets the `UploadedFile`
+ * shape that `req.file('avatar')` / `req.files` return. Conforms to the
+ * `{ rule: { validate(value): { valid, errors? } } }` contract that the
+ * Action layer ({@link `@stacksjs/router`} → `validateActionInput`)
+ * iterates, so file validations slot into the same `validations:` block
+ * as the rest of the field rules:
+ *
+ * @example
+ * ```ts
+ * new Action({
+ *   method: 'POST',
+ *   validations: {
+ *     avatar: { rule: schema.file().image().maxBytes(2 * 1024 * 1024) },
+ *   },
+ *   async handle(req) {
+ *     const file = req.file('avatar')!
+ *     const { url } = await Storage.put(file, { disk: 'public', dir: 'avatars' })
+ *     // …
+ *   },
+ * })
+ * ```
+ *
+ * The validator is intentionally narrow on the input it accepts: a
+ * structural shape with `size: number` and either `mimetype` or
+ * `mimeType`, optionally with `originalName` / `name`. Both the
+ * router's wrapping `UploadedFile` class and the raw multipart-parse
+ * shape satisfy it.
+ */
+/** Shape this validator runs against. */
+export declare interface FileLike {
+  size: number
+  mimetype?: string
+  mimeType?: string
+  originalName?: string
+  name?: string
+}
+declare interface ValidationError { message: string }
+declare interface ValidationResult { valid: boolean, errors?: ValidationError[] }
+/**
+ * Chainable file validator. Each method returns `this` so callers can
+ * stack constraints in any order; rules accumulate into an internal
+ * list and run sequentially on `.validate()`.
+ *
+ * Designed to be cheap to construct — most validators in an Action's
+ * `validations:` block are built once at module load. No I/O happens
+ * here; image dimension / content-sniffing rules belong in a separate
+ * `@stacksjs/storage/image` opt-in (deliverable 5 of #1856).
+ */
+export declare class FileValidator {
+  required(): this;
+  image(): this;
+  mimeTypes(allowed: string[]): this;
+  maxBytes(max: number): this;
+  minBytes(min: number): this;
+  extensions(allowed: string[]): this;
+  custom(rule: (file: FileLike) => string | null): this;
+  validate(value: unknown): ValidationResult;
+}

package/dist/index.d.ts

@@ -1,3 +1,9 @@
+export type {
+  ConditionalAPI,
+  ConditionalRecord,
+  ObjectWithContextValidator,
+  ValidatorWithConditionals,
+} from './schema';
 // Type guard utilities
 export declare function isString(value: unknown): value is string;
 export declare function isNumber(value: unknown): value is number;
@@ -16,6 +22,14 @@ export declare function isNullOrUndefined(value: unknown): value is null | undef
 // `export *` re-exports from `@stacksjs/ts-validation` (which also exports
 // a `schema` symbol) and see whichever binding was registered first.
 export { schema } from './schema';
+// Conditional validation surface — `.when()` / `.sometimes()` mixins +
+// context-aware object validator (stacksjs/stacks#1890).
+export {
+  applyConditionals,
+  objectWithContext,
+  shouldApplyConditional,
+  withConditionals,
+} from './schema';
 // Re-export everything from @stacksjs/ts-validation. The explicit `schema`
 // export above shadows ts-validation's own `schema` for `import { schema }
 // from '@stacksjs/validation'` consumers — which is what we want, since the

package/dist/index.js

@@ -1,2 +1,2 @@
 // @bun
-var $=import.meta.require;import{v as A}from"@stacksjs/ts-validation";var Z=A;export*from"@stacksjs/ts-validation";var T=[];function x(V){T=V}function E(){return T}import{HttpError as W}from"@stacksjs/error-handling";import{path as C}from"@stacksjs/path";import{snakeCase as q}from"@stacksjs/strings";import{MessageProvider as I,setCustomMessages as S}from"@stacksjs/ts-validation";function F(V,z={}){let J=[];for(let D of V){let B=D.startsWith("/")?D.lastIndexOf("/"):-1,N=D.indexOf("*"),Q=N===-1?B:D.lastIndexOf("/",N),L=Q>0?D.slice(0,Q):".",U=Q>0?D.slice(Q+1):D,X=new Bun.Glob(U);for(let Y of X.scanSync({cwd:L,onlyFiles:!0}))J.push(z.absolute?`${L}/${Y}`:Y)}return J}function b(V){if(V===void 0)return!1;return Object.keys(V).length>0}async function K(V,z){let D=F([C.userModelsPath("*.ts"),C.storagePath("framework/defaults/app/Models/**/*.ts")],{absolute:!0}).find((L)=>L.endsWith(`${V}.ts`));if(!D)throw new W(404,`Model ${V} not found`);let B=(await import(D)).default.attributes,N={},Q={};for(let L in B)if(Object.prototype.hasOwnProperty.call(B,L)){let U=B[L];if(!U)continue;let X="isRequired"in(U.validation?.rule??{})?(U.validation?.rule).isRequired:!1;if(U.default!==void 0&&X===!1)continue;N[q(L)]=U.validation?.rule;let Y=U.validation?.message;if(Y)for(let _ in Y){let w=`${L}.${_}`;Q[w]=Y[_]||""}}try{S(new I(Q));let U=await Z.object(N).validate(z);if(!U.valid)throw x(U.errors),new W(422,"Validation failed",{errors:U.errors});return U}catch(L){if(L instanceof W)throw L;throw new W(500,L?.message||"An unexpected validation error occurred")}}var P=new Map;function m(V,z){P.set(V,z)}function p(V){return P.get(V)}function v(V,z,J){return async(D)=>{try{let{db:G}=await import("@stacksjs/database"),B=G.selectFrom(V).where(z,"=",D);if(J)B=B.where("id","!=",J);return await B.selectAll().executeTakeFirst()?`The ${z} has already been taken`:!0}catch{return!0}}}function d(V,z){return async(J)=>{try{let{db:D}=await import("@stacksjs/database");return await D.selectFrom(V).where(z,"=",J).selectAll().executeTakeFirst()?!0:`The selected ${z} does not exist`}catch{return!0}}}async function c(V,z,J){let D=await K(V,z);if(J&&Object.keys(J).length>0){let G={};if(await Promise.all(Object.entries(J).map(async([B,N])=>{let Q=await N(z[B],z);if(Q!==!0)G[B]=typeof Q==="string"?Q:`${B} validation failed`})),Object.keys(G).length>0)throw new W(422,"Validation failed",{errors:G})}return D}async function M(V){if(!V||typeof V!=="object")return{};if(typeof V.all==="function"){let D=V.all();return D instanceof Promise?await D:D}let z=V,J={};if(z.url)try{new URL(z.url).searchParams.forEach((G,B)=>{J[B]=G})}catch{}if(z.query&&typeof z.query==="object")Object.assign(J,z.query);if(z.jsonBody&&typeof z.jsonBody==="object")Object.assign(J,z.jsonBody);if(z.formBody&&typeof z.formBody==="object")Object.assign(J,z.formBody);if(z.params&&typeof z.params==="object")Object.assign(J,z.params);if(Object.keys(J).length===0&&!("all"in V)&&!("jsonBody"in V))return V;return J}async function i(V,z){let J=await M(V),D={},G={};for(let[B,N]of Object.entries(z)){if(!N)continue;if(typeof N.rule==="object"||typeof N.rule==="function"){D[B]=N.rule;let Q=N.message;if(typeof Q==="string")G[`${B}.default`]=Q;else if(Q&&typeof Q==="object")for(let[L,U]of Object.entries(Q))G[`${B}.${L}`]=U}else D[B]=N}try{if(Object.keys(G).length>0)S(new I(G));let N=await Z.object(D).validate(J);if(!N.valid){let L={};for(let U of N.errors||[]){let X=U.field??"_";if(!L[X])L[X]=[];L[X].push(U.message)}throw new W(422,"Validation failed",{errors:L})}return N.value??J}catch(B){if(B instanceof W)throw B;throw new W(500,B?.message||"An unexpected validation error occurred")}}async function o(V,z){let J={},D={};for(let G in V)if(Object.prototype.hasOwnProperty.call(V,G)){let B=V[G]?.rule;if(B)J[G]=B;let N=V[G]?.message;for(let Q in N){let L=`${G}.${Q}`;D[L]=V[G]?.message[Q]||""}}try{let B=await Z.object().shape(J).validate(z);if(!B.valid)throw new W(422,"Validation failed",{errors:B.errors});return B}catch(G){if(G instanceof W)throw G;throw new W(500,G?.message||"An unexpected validation error occurred")}}function l(V){return typeof V==="string"}function s(V){return typeof V==="number"&&!Number.isNaN(V)}function a(V){return typeof V==="boolean"}function t(V){return typeof V==="object"&&V!==null&&!Array.isArray(V)}function r(V){return Array.isArray(V)}function e(V){return typeof V==="function"}function VV(V){return V===void 0}function zV(V){return V===null}function BV(V){return V===null||V===void 0}export{c as validateFieldAsync,K as validateField,i as validate,v as unique,Z as schema,x as reportError,m as registerRule,VV as isUndefined,l as isString,b as isObjectNotEmpty,t as isObject,s as isNumber,BV as isNullOrUndefined,zV as isNull,e as isFunction,a as isBoolean,r as isArray,E as getErrors,p as getCustomRule,d as exists,o as customValidate};
+var q=import.meta.require;import{v as b}from"@stacksjs/ts-validation";var h=new Set(["image/jpeg","image/png","image/webp","image/gif","image/avif"]);function F(B){return B.mimetype??B.mimeType}function f(B){return B.originalName??B.name}function g(B){let D=f(B);if(!D)return null;let J=D.lastIndexOf(".");if(J<=0||J===D.length-1)return null;let L=D.slice(J+1).toLowerCase();return/^[a-z0-9]+$/.test(L)?L:null}class A{_required=!1;_rules=[];required(){return this._required=!0,this}image(){return this._rules.push((B)=>{let D=F(B);if(!D||!h.has(D.toLowerCase()))return`must be an image (got ${D||"no mimetype"})`;return null}),this}mimeTypes(B){let D=new Set(B.map((J)=>J.toLowerCase()));return this._rules.push((J)=>{let L=F(J);if(!L||!D.has(L.toLowerCase()))return`must be one of: ${B.join(", ")} (got ${L||"no mimetype"})`;return null}),this}maxBytes(B){return this._rules.push((D)=>{if(typeof D.size!=="number")return"has no size \u2014 cannot enforce maxBytes";if(D.size>B)return`is too large: ${D.size} bytes exceeds the ${B}-byte cap`;return null}),this}minBytes(B){return this._rules.push((D)=>{if(typeof D.size!=="number")return"has no size \u2014 cannot enforce minBytes";if(D.size<B)return`is too small: ${D.size} bytes is below the ${B}-byte minimum`;return null}),this}extensions(B){let D=new Set(B.map((J)=>J.toLowerCase().replace(/^\./,"")));return this._rules.push((J)=>{let L=g(J);if(!L||!D.has(L))return`must have one of these extensions: ${B.join(", ")} (got ${L?`.${L}`:"no extension"})`;return null}),this}custom(B){return this._rules.push(B),this}validate(B){if(B===null||B===void 0){if(this._required)return{valid:!1,errors:[{message:"is required"}]};return{valid:!0}}if(typeof B!=="object"||typeof B.size!=="number")return{valid:!1,errors:[{message:"must be an uploaded file"}]};let D=B,J=[];for(let L of this._rules){let U=L(D);if(U)J.push({message:U})}return J.length===0?{valid:!0}:{valid:!1,errors:J}}}function C(){return new A}function T(B){let D=B;return D.when=function(L,U,Q){if(!this.__conditionals)this.__conditionals=[];return this.__conditionals.push({field:L,match:U,refine:Q}),this},D.sometimes=function(){return this.optional(),this},D}function H(B,D){if(D===null||D===void 0)return!1;let J=D[B.field];if(typeof B.match==="function")return B.match(J);return J===B.match}function V(B,D){let J=B.__conditionals;if(!J||J.length===0)return B;let L=null;for(let U of J){if(!H(U,D))continue;if(L===null)L=y(B);L=U.refine(L)}return L??B}function y(B){let D=Object.create(Object.getPrototypeOf(B));Object.assign(D,B);let J=B.rules;if(Array.isArray(J))D.rules=J.slice();return D}function I(B){let D=B??{},J=!0,L={name:"object",isPartOfShape:!1,shape(Q){return D=Q,L},getShape(){return D},required(){return J=!0,U},optional(){return J=!1,U},validate(Q){let Z=Q===void 0||Q===null;if(!J&&Z)return{valid:!0,errors:this.isPartOfShape?{}:[]};if(J&&Z)return this.isPartOfShape?{valid:!1,errors:{object:[{message:"value is required"}]}}:{valid:!1,errors:[{message:"value is required"}]};if(typeof Q!=="object"||Array.isArray(Q))return this.isPartOfShape?{valid:!1,errors:{object:[{message:"Must be an object"}]}}:{valid:!1,errors:[{message:"Must be an object"}]};let $=Q,X={},G=!1;for(let N of Object.keys(D)){let _=D[N];if(!_)continue;let Y=V(_,$),S=$[N],P=Y.validate(S);if(P.valid)continue;if(G=!0,!Array.isArray(P.errors))for(let[w,k]of Object.entries(P.errors))X[`${N}.${w}`]=k;else X[N]=P.errors}if(G)return{valid:!1,errors:X};return{valid:!0,errors:{}}}},U=T(L);return U}var v=new Set(["array","bigint","binary","blob","boolean","custom","date","datetime","decimal","double","enum","float","integer","json","number","password","smallint","string","text","time","timestamp","timestampTz","unix"]);function m(B){return(...D)=>{let J=B(...D);return T(J)}}var W=new Proxy(b,{get(B,D,J){if(D==="file")return C;if(D==="object")return I;if(typeof D==="string"&&v.has(D)){let L=Reflect.get(B,D,J);if(typeof L==="function")return m(L)}return Reflect.get(B,D,J)}});export*from"@stacksjs/ts-validation";var M=[];function O(B){M=B}function XB(){return M}import{HttpError as z}from"@stacksjs/error-handling";import{path as R}from"@stacksjs/path";import{snakeCase as p}from"@stacksjs/strings";import{getErrorMessage as K}from"@stacksjs/utils";import{MessageProvider as E,setCustomMessages as x}from"@stacksjs/ts-validation";function c(B,D={}){let J=[];for(let L of B){let Q=L.startsWith("/")?L.lastIndexOf("/"):-1,Z=L.indexOf("*"),$=Z===-1?Q:L.lastIndexOf("/",Z),X=$>0?L.slice(0,$):".",G=$>0?L.slice($+1):L,N=new Bun.Glob(G);for(let _ of N.scanSync({cwd:X,onlyFiles:!0}))J.push(D.absolute?`${X}/${_}`:_)}return J}function YB(B){if(B===void 0)return!1;return Object.keys(B).length>0}async function d(B,D){let L=c([R.userModelsPath("*.ts"),R.storagePath("framework/defaults/app/Models/**/*.ts")],{absolute:!0}).find((X)=>X.endsWith(`${B}.ts`));if(!L)throw new z(404,`Model ${B} not found`);let Q=(await import(L)).default.attributes,Z={},$={};for(let X in Q)if(Object.prototype.hasOwnProperty.call(Q,X)){let G=Q[X];if(!G)continue;let N="isRequired"in(G.validation?.rule??{})?(G.validation?.rule).isRequired:!1;if(G.default!==void 0&&N===!1)continue;Z[p(X)]=G.validation?.rule;let _=G.validation?.message;if(_)for(let Y in _){let S=`${X}.${Y}`;$[S]=_[Y]||""}}try{x(new E($));let G=await W.object(Z).validate(D);if(!G.valid)throw O(G.errors),new z(422,"Validation failed",{errors:G.errors});return G}catch(X){if(X instanceof z)throw X;throw new z(500,K(X)||"An unexpected validation error occurred")}}var j=new Map;function PB(B,D){j.set(B,D)}function VB(B){return j.get(B)}function IB(B,D,J){return async(L)=>{try{let{db:U}=await import("@stacksjs/database"),Q=U.selectFrom(B).where(D,"=",L);if(J)Q=Q.where("id","!=",J);return await Q.selectAll().executeTakeFirst()?`The ${D} has already been taken`:!0}catch{return!0}}}function SB(B,D){return async(J)=>{try{let{db:L}=await import("@stacksjs/database");return await L.selectFrom(B).where(D,"=",J).selectAll().executeTakeFirst()?!0:`The selected ${D} does not exist`}catch{return!0}}}async function AB(B,D,J){let L=await d(B,D);if(J&&Object.keys(J).length>0){let U={};if(await Promise.all(Object.entries(J).map(async([Q,Z])=>{let $=await Z(D[Q],D);if($!==!0)U[Q]=typeof $==="string"?$:`${Q} validation failed`})),Object.keys(U).length>0)throw new z(422,"Validation failed",{errors:U})}return L}async function n(B){if(!B||typeof B!=="object")return{};if(typeof B.all==="function"){let L=B.all();return L instanceof Promise?await L:L}let D=B,J={};if(D.url)try{new URL(D.url).searchParams.forEach((U,Q)=>{J[Q]=U})}catch{}if(D.query&&typeof D.query==="object")Object.assign(J,D.query);if(D.jsonBody&&typeof D.jsonBody==="object")Object.assign(J,D.jsonBody);if(D.formBody&&typeof D.formBody==="object")Object.assign(J,D.formBody);if(D.params&&typeof D.params==="object")Object.assign(J,D.params);if(Object.keys(J).length===0&&!("all"in B)&&!("jsonBody"in B))return B;return J}async function CB(B,D){let J=await n(B),L={},U={};for(let[Q,Z]of Object.entries(D)){if(!Z)continue;if(typeof Z.rule==="object"||typeof Z.rule==="function"){L[Q]=Z.rule;let $=Z.message;if(typeof $==="string")U[`${Q}.default`]=$;else if($&&typeof $==="object")for(let[X,G]of Object.entries($))U[`${Q}.${X}`]=G}else L[Q]=Z}try{if(Object.keys(U).length>0)x(new E(U));let Z=await W.object(L).validate(J);if(!Z.valid){let X={};for(let G of Z.errors||[]){let N=G.field??"_";if(!X[N])X[N]=[];X[N].push(G.message)}throw new z(422,"Validation failed",{errors:X})}return Z.value??J}catch(Q){if(Q instanceof z)throw Q;throw new z(500,K(Q)||"An unexpected validation error occurred")}}async function HB(B,D){let J={},L={};for(let U in B)if(Object.prototype.hasOwnProperty.call(B,U)){let Q=B[U]?.rule;if(Q)J[U]=Q;let Z=B[U]?.message;for(let $ in Z){let X=`${U}.${$}`;L[X]=B[U]?.message[$]||""}}try{let Q=await W.object().shape(J).validate(D);if(!Q.valid)throw new z(422,"Validation failed",{errors:Q.errors});return Q}catch(U){if(U instanceof z)throw U;throw new z(500,K(U)||"An unexpected validation error occurred")}}function qB(B){return typeof B==="string"}function FB(B){return typeof B==="number"&&!Number.isNaN(B)}function MB(B){return typeof B==="boolean"}function OB(B){return typeof B==="object"&&B!==null&&!Array.isArray(B)}function RB(B){return Array.isArray(B)}function EB(B){return typeof B==="function"}function xB(B){return B===void 0}function jB(B){return B===null}function wB(B){return B===null||B===void 0}export{T as withConditionals,AB as validateFieldAsync,d as validateField,CB as validate,IB as unique,H as shouldApplyConditional,W as schema,O as reportError,PB as registerRule,I as objectWithContext,xB as isUndefined,qB as isString,YB as isObjectNotEmpty,OB as isObject,FB as isNumber,wB as isNullOrUndefined,jB as isNull,EB as isFunction,MB as isBoolean,RB as isArray,XB as getErrors,VB as getCustomRule,SB as exists,HB as customValidate,V as applyConditionals};

package/dist/object-with-context.d.ts

@@ -0,0 +1,37 @@
+import type { ConditionalAPI } from './conditional';
+import type { ValidationResult, Validator } from '@stacksjs/ts-validation';
+/**
+ * Build a Stacks-flavored object validator that respects conditional
+ * rules on its child validators. Drop-in for `v.object(...)` in
+ * `@stacksjs/ts-validation` — same call shape, broader behavior.
+ *
+ * @example
+ * ```ts
+ * objectWithContext({
+ *   payment_method: schema.enum(['card', 'bank']),
+ *   card_token:     schema.string().when('payment_method', 'card', s => s.required()),
+ *   bank_account:   schema.string().when('payment_method', 'bank', s => s.required()),
+ *   username:       schema.string().sometimes().minLength(3),
+ * }).validate(input)
+ * ```
+ */
+export declare function objectWithContext<T extends Record<string, Validator<any>>>(initialShape?: T): ObjectWithContextValidator<T> & ConditionalAPI<ObjectWithContextValidator<T>>;
+/**
+ * Validator-shaped object returned by `schema.object()`. Mirrors the
+ * subset of ts-validation's `ObjectValidatorType` that Stacks code
+ * actually uses today (`validate`, `shape`, `optional`, `required`).
+ *
+ * Extra method:
+ *   - `getShape()` — exposes the underlying shape map so OpenAPI export
+ *     and other introspection passes can walk the per-field validators
+ *     (and their `__conditionals` arrays).
+ */
+export declare interface ObjectWithContextValidator<T extends Record<string, Validator<any>>> {
+  readonly name: 'object'
+  validate: (value: unknown) => ValidationResult
+  getShape: () => T
+  required: () => ObjectWithContextValidator<T> & ConditionalAPI<ObjectWithContextValidator<T>>
+  optional: () => ObjectWithContextValidator<T> & ConditionalAPI<ObjectWithContextValidator<T>>
+  isPartOfShape: boolean
+  shape: (shape: T) => ObjectWithContextValidator<T>
+}

package/dist/schema.d.ts

@@ -1,2 +1,35 @@
+import { file, FileValidator } from './file-validator';
+import { objectWithContext } from './object-with-context';
+import { withConditionals } from './conditional';
+import type { ConditionalAPI } from './conditional';
+import type { ObjectWithContextValidator } from './object-with-context';
 import type { ValidationInstance } from '@stacksjs/ts-validation';
-export declare const schema: ValidationInstance;
+export type { FileLike } from './file-validator';
+export type { ConditionalAPI, ConditionalRecord, ValidatorWithConditionals } from './conditional';
+export type { ObjectWithContextValidator } from './object-with-context';
+/**
+ * `Object.assign({}, v, { file })` would defeat the ts-validation
+ * proxy's late-binding. Wrapping with `new Proxy` keeps every existing
+ * `schema.<method>()` call going through the upstream proxy while only
+ * intercepting the slots we own (`file`, `object`, and the conditional
+ * mixin on primitive factories).
+ */
+export declare const schema: SchemaWithFile;
+/**
+ * Extended `ValidationInstance` that adds `schema.file()` on top of the
+ * ts-validation surface (stacksjs/stacks#1856). Upstream ts-validation
+ * has `string()`, `number()`, `enum()`, etc. but no `file()` validator;
+ * we layer one here without forking ts-validation so the rest of the
+ * surface keeps working unchanged.
+ *
+ * The runtime value is the ts-validation proxy with `file` patched in,
+ * `object` swapped for the context-aware variant (stacksjs/stacks#1890),
+ * and every primitive factory wrapped to attach `.when()` / `.sometimes()`
+ * to the returned validator.
+ */
+export declare interface SchemaWithFile extends ValidationInstance {
+  file: () => FileValidator
+}
+export { file, FileValidator } from './file-validator';
+export { applyConditionals, shouldApplyConditional, withConditionals } from './conditional';
+export { objectWithContext } from './object-with-context';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/validation",
   "type": "module",
-  "version": "0.70.45",
+  "version": "0.70.54",
   "description": "The Stacks Validation ways.",
   "author": "Chris Breuer",
   "contributors": [
@@ -48,11 +48,11 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/ts-validation": "^0.4.9"
+    "@stacksjs/ts-validation": "^0.5.0"
   },
   "devDependencies": {
     "better-dx": "^0.2.12",
-    "@stacksjs/strings": "^0.70.45",
-    "@stacksjs/types": "^0.70.45"
+    "@stacksjs/strings": "0.70.54",
+    "@stacksjs/types": "0.70.54"
   }
 }