@atproto/lex-schema 0.0.11 → 0.0.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (238) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/dist/core/$type.d.ts +149 -0
  3. package/dist/core/$type.d.ts.map +1 -1
  4. package/dist/core/$type.js +44 -0
  5. package/dist/core/$type.js.map +1 -1
  6. package/dist/core/record-key.d.ts +44 -0
  7. package/dist/core/record-key.d.ts.map +1 -1
  8. package/dist/core/record-key.js +30 -0
  9. package/dist/core/record-key.js.map +1 -1
  10. package/dist/core/result.d.ts +85 -4
  11. package/dist/core/result.d.ts.map +1 -1
  12. package/dist/core/result.js +60 -4
  13. package/dist/core/result.js.map +1 -1
  14. package/dist/core/schema.d.ts +229 -2
  15. package/dist/core/schema.d.ts.map +1 -1
  16. package/dist/core/schema.js +197 -4
  17. package/dist/core/schema.js.map +1 -1
  18. package/dist/core/string-format.d.ts +244 -11
  19. package/dist/core/string-format.d.ts.map +1 -1
  20. package/dist/core/string-format.js +150 -0
  21. package/dist/core/string-format.js.map +1 -1
  22. package/dist/core/types.d.ts +90 -3
  23. package/dist/core/types.d.ts.map +1 -1
  24. package/dist/core/types.js.map +1 -1
  25. package/dist/core/validation-error.d.ts +60 -0
  26. package/dist/core/validation-error.d.ts.map +1 -1
  27. package/dist/core/validation-error.js +60 -0
  28. package/dist/core/validation-error.js.map +1 -1
  29. package/dist/core/validation-issue.d.ts +61 -0
  30. package/dist/core/validation-issue.d.ts.map +1 -1
  31. package/dist/core/validation-issue.js +51 -0
  32. package/dist/core/validation-issue.js.map +1 -1
  33. package/dist/core/validator.d.ts +347 -10
  34. package/dist/core/validator.d.ts.map +1 -1
  35. package/dist/core/validator.js +184 -3
  36. package/dist/core/validator.js.map +1 -1
  37. package/dist/helpers.d.ts +9 -24
  38. package/dist/helpers.d.ts.map +1 -1
  39. package/dist/helpers.js.map +1 -1
  40. package/dist/schema/array.d.ts +45 -0
  41. package/dist/schema/array.d.ts.map +1 -1
  42. package/dist/schema/array.js +14 -0
  43. package/dist/schema/array.js.map +1 -1
  44. package/dist/schema/blob.d.ts +46 -0
  45. package/dist/schema/blob.d.ts.map +1 -1
  46. package/dist/schema/blob.js +39 -0
  47. package/dist/schema/blob.js.map +1 -1
  48. package/dist/schema/boolean.d.ts +28 -0
  49. package/dist/schema/boolean.d.ts.map +1 -1
  50. package/dist/schema/boolean.js +28 -0
  51. package/dist/schema/boolean.js.map +1 -1
  52. package/dist/schema/bytes.d.ts +38 -0
  53. package/dist/schema/bytes.d.ts.map +1 -1
  54. package/dist/schema/bytes.js +32 -0
  55. package/dist/schema/bytes.js.map +1 -1
  56. package/dist/schema/cid.d.ts +38 -0
  57. package/dist/schema/cid.d.ts.map +1 -1
  58. package/dist/schema/cid.js +33 -0
  59. package/dist/schema/cid.js.map +1 -1
  60. package/dist/schema/custom.d.ts +66 -1
  61. package/dist/schema/custom.d.ts.map +1 -1
  62. package/dist/schema/custom.js +54 -0
  63. package/dist/schema/custom.js.map +1 -1
  64. package/dist/schema/dict.d.ts +44 -0
  65. package/dist/schema/dict.d.ts.map +1 -1
  66. package/dist/schema/dict.js +44 -0
  67. package/dist/schema/dict.js.map +1 -1
  68. package/dist/schema/discriminated-union.d.ts +58 -0
  69. package/dist/schema/discriminated-union.d.ts.map +1 -1
  70. package/dist/schema/discriminated-union.js +45 -0
  71. package/dist/schema/discriminated-union.js.map +1 -1
  72. package/dist/schema/enum.d.ts +48 -0
  73. package/dist/schema/enum.d.ts.map +1 -1
  74. package/dist/schema/enum.js +48 -0
  75. package/dist/schema/enum.js.map +1 -1
  76. package/dist/schema/integer.d.ts +42 -0
  77. package/dist/schema/integer.d.ts.map +1 -1
  78. package/dist/schema/integer.js +36 -0
  79. package/dist/schema/integer.js.map +1 -1
  80. package/dist/schema/intersection.d.ts +54 -0
  81. package/dist/schema/intersection.d.ts.map +1 -1
  82. package/dist/schema/intersection.js +49 -0
  83. package/dist/schema/intersection.js.map +1 -1
  84. package/dist/schema/literal.d.ts +44 -0
  85. package/dist/schema/literal.d.ts.map +1 -1
  86. package/dist/schema/literal.js +44 -0
  87. package/dist/schema/literal.js.map +1 -1
  88. package/dist/schema/never.d.ts +42 -0
  89. package/dist/schema/never.d.ts.map +1 -1
  90. package/dist/schema/never.js +42 -0
  91. package/dist/schema/never.js.map +1 -1
  92. package/dist/schema/null.d.ts +29 -0
  93. package/dist/schema/null.d.ts.map +1 -1
  94. package/dist/schema/null.js +29 -0
  95. package/dist/schema/null.js.map +1 -1
  96. package/dist/schema/nullable.d.ts +41 -0
  97. package/dist/schema/nullable.d.ts.map +1 -1
  98. package/dist/schema/nullable.js +41 -0
  99. package/dist/schema/nullable.js.map +1 -1
  100. package/dist/schema/object.d.ts +56 -0
  101. package/dist/schema/object.d.ts.map +1 -1
  102. package/dist/schema/object.js +51 -0
  103. package/dist/schema/object.js.map +1 -1
  104. package/dist/schema/optional.d.ts +42 -0
  105. package/dist/schema/optional.d.ts.map +1 -1
  106. package/dist/schema/optional.js +42 -0
  107. package/dist/schema/optional.js.map +1 -1
  108. package/dist/schema/params.d.ts +90 -10
  109. package/dist/schema/params.d.ts.map +1 -1
  110. package/dist/schema/params.js +84 -10
  111. package/dist/schema/params.js.map +1 -1
  112. package/dist/schema/payload.d.ts +111 -15
  113. package/dist/schema/payload.d.ts.map +1 -1
  114. package/dist/schema/payload.js +70 -0
  115. package/dist/schema/payload.js.map +1 -1
  116. package/dist/schema/permission-set.d.ts +58 -0
  117. package/dist/schema/permission-set.d.ts.map +1 -1
  118. package/dist/schema/permission-set.js +50 -0
  119. package/dist/schema/permission-set.js.map +1 -1
  120. package/dist/schema/permission.d.ts +42 -0
  121. package/dist/schema/permission.d.ts.map +1 -1
  122. package/dist/schema/permission.js +39 -0
  123. package/dist/schema/permission.js.map +1 -1
  124. package/dist/schema/procedure.d.ts +64 -0
  125. package/dist/schema/procedure.d.ts.map +1 -1
  126. package/dist/schema/procedure.js +64 -0
  127. package/dist/schema/procedure.js.map +1 -1
  128. package/dist/schema/query.d.ts +55 -0
  129. package/dist/schema/query.d.ts.map +1 -1
  130. package/dist/schema/query.js +55 -0
  131. package/dist/schema/query.js.map +1 -1
  132. package/dist/schema/record.d.ts +63 -8
  133. package/dist/schema/record.d.ts.map +1 -1
  134. package/dist/schema/record.js +20 -0
  135. package/dist/schema/record.js.map +1 -1
  136. package/dist/schema/ref.d.ts +50 -0
  137. package/dist/schema/ref.d.ts.map +1 -1
  138. package/dist/schema/ref.js +17 -0
  139. package/dist/schema/ref.js.map +1 -1
  140. package/dist/schema/refine.d.ts +58 -9
  141. package/dist/schema/refine.d.ts.map +1 -1
  142. package/dist/schema/refine.js.map +1 -1
  143. package/dist/schema/regexp.d.ts +44 -0
  144. package/dist/schema/regexp.d.ts.map +1 -1
  145. package/dist/schema/regexp.js +44 -0
  146. package/dist/schema/regexp.js.map +1 -1
  147. package/dist/schema/string.d.ts +50 -0
  148. package/dist/schema/string.d.ts.map +1 -1
  149. package/dist/schema/string.js +41 -0
  150. package/dist/schema/string.js.map +1 -1
  151. package/dist/schema/subscription.d.ts +72 -2
  152. package/dist/schema/subscription.d.ts.map +1 -1
  153. package/dist/schema/subscription.js +59 -0
  154. package/dist/schema/subscription.js.map +1 -1
  155. package/dist/schema/token.d.ts +47 -0
  156. package/dist/schema/token.d.ts.map +1 -1
  157. package/dist/schema/token.js +47 -0
  158. package/dist/schema/token.js.map +1 -1
  159. package/dist/schema/typed-object.d.ts +62 -8
  160. package/dist/schema/typed-object.d.ts.map +1 -1
  161. package/dist/schema/typed-object.js +18 -0
  162. package/dist/schema/typed-object.js.map +1 -1
  163. package/dist/schema/typed-ref.d.ts +53 -0
  164. package/dist/schema/typed-ref.d.ts.map +1 -1
  165. package/dist/schema/typed-ref.js +15 -0
  166. package/dist/schema/typed-ref.js.map +1 -1
  167. package/dist/schema/typed-union.d.ts +50 -1
  168. package/dist/schema/typed-union.d.ts.map +1 -1
  169. package/dist/schema/typed-union.js +50 -1
  170. package/dist/schema/typed-union.js.map +1 -1
  171. package/dist/schema/union.d.ts +45 -0
  172. package/dist/schema/union.d.ts.map +1 -1
  173. package/dist/schema/union.js +40 -0
  174. package/dist/schema/union.js.map +1 -1
  175. package/dist/schema/unknown-object.d.ts +34 -0
  176. package/dist/schema/unknown-object.d.ts.map +1 -1
  177. package/dist/schema/unknown-object.js +31 -0
  178. package/dist/schema/unknown-object.js.map +1 -1
  179. package/dist/schema/unknown.d.ts +33 -0
  180. package/dist/schema/unknown.d.ts.map +1 -1
  181. package/dist/schema/unknown.js +33 -0
  182. package/dist/schema/unknown.js.map +1 -1
  183. package/dist/schema/with-default.d.ts +44 -0
  184. package/dist/schema/with-default.d.ts.map +1 -1
  185. package/dist/schema/with-default.js +44 -0
  186. package/dist/schema/with-default.js.map +1 -1
  187. package/package.json +3 -3
  188. package/src/core/$type.ts +150 -18
  189. package/src/core/record-key.ts +44 -0
  190. package/src/core/result.ts +86 -4
  191. package/src/core/schema.ts +236 -7
  192. package/src/core/string-format.ts +259 -13
  193. package/src/core/types.ts +91 -3
  194. package/src/core/validation-error.ts +60 -0
  195. package/src/core/validation-issue.ts +65 -0
  196. package/src/core/validator.ts +351 -10
  197. package/src/helpers.test.ts +110 -29
  198. package/src/helpers.ts +9 -14
  199. package/src/schema/array.test.ts +94 -79
  200. package/src/schema/array.ts +45 -0
  201. package/src/schema/blob.ts +46 -0
  202. package/src/schema/boolean.ts +28 -0
  203. package/src/schema/bytes.ts +38 -0
  204. package/src/schema/cid.ts +38 -0
  205. package/src/schema/custom.ts +66 -1
  206. package/src/schema/dict.ts +44 -0
  207. package/src/schema/discriminated-union.ts +58 -0
  208. package/src/schema/enum.ts +48 -0
  209. package/src/schema/integer.ts +42 -0
  210. package/src/schema/intersection.ts +54 -0
  211. package/src/schema/literal.ts +44 -0
  212. package/src/schema/never.ts +42 -0
  213. package/src/schema/null.ts +29 -0
  214. package/src/schema/nullable.ts +41 -0
  215. package/src/schema/object.ts +56 -0
  216. package/src/schema/optional.ts +42 -0
  217. package/src/schema/params.test.ts +58 -2
  218. package/src/schema/params.ts +125 -19
  219. package/src/schema/payload.test.ts +3 -3
  220. package/src/schema/payload.ts +142 -38
  221. package/src/schema/permission-set.ts +58 -0
  222. package/src/schema/permission.ts +42 -0
  223. package/src/schema/procedure.ts +64 -0
  224. package/src/schema/query.ts +55 -0
  225. package/src/schema/record.ts +63 -8
  226. package/src/schema/ref.ts +50 -0
  227. package/src/schema/refine.ts +58 -9
  228. package/src/schema/regexp.ts +44 -0
  229. package/src/schema/string.ts +50 -0
  230. package/src/schema/subscription.ts +72 -2
  231. package/src/schema/token.ts +47 -0
  232. package/src/schema/typed-object.ts +62 -8
  233. package/src/schema/typed-ref.ts +53 -0
  234. package/src/schema/typed-union.ts +55 -2
  235. package/src/schema/union.ts +45 -0
  236. package/src/schema/unknown-object.ts +34 -0
  237. package/src/schema/unknown.ts +33 -0
  238. package/src/schema/with-default.ts +44 -0
@@ -2,23 +2,83 @@ import { PropertyKey } from './property-key.js';
2
2
  import { ResultFailure, ResultSuccess } from './result.js';
3
3
  import { ValidationError } from './validation-error.js';
4
4
  import { Issue, MeasurableType } from './validation-issue.js';
5
+ /**
6
+ * Represents a successful validation result.
7
+ *
8
+ * @typeParam Value - The type of the validated value
9
+ */
5
10
  export type ValidationSuccess<Value = unknown> = ResultSuccess<Value>;
11
+ /**
12
+ * Represents a failed validation result containing a {@link ValidationError}.
13
+ */
6
14
  export type ValidationFailure = ResultFailure<ValidationError>;
15
+ /**
16
+ * Discriminated union representing the outcome of a validation operation.
17
+ *
18
+ * Check the `success` property to determine if validation passed or failed:
19
+ * - If `success` is `true`, the `value` property contains the validated data
20
+ * - If `success` is `false`, the `reason` property contains the {@link ValidationError}
21
+ *
22
+ * @typeParam Value - The type of the validated value on success
23
+ *
24
+ * @example
25
+ * ```typescript
26
+ * const result: ValidationResult<string> = schema.safeParse(data)
27
+ * if (result.success) {
28
+ * // result.value is string
29
+ * } else {
30
+ * // result.reason is ValidationError
31
+ * }
32
+ * ```
33
+ */
7
34
  export type ValidationResult<Value = unknown> = ValidationSuccess<Value> | ValidationFailure;
35
+ /**
36
+ * Extracts the input type that a validator accepts.
37
+ *
38
+ * Use this utility type to infer what type a schema will accept during validation.
39
+ *
40
+ * @typeParam V - A validator type
41
+ *
42
+ * @example
43
+ * ```typescript
44
+ * const userSchema = new ObjectSchema({ name: stringSchema, age: numberSchema })
45
+ * type UserInput = InferInput<typeof userSchema>
46
+ * // { name: string; age: number }
47
+ * ```
48
+ */
8
49
  export type InferInput<V extends Validator> = V['__lex']['input'];
50
+ /**
51
+ * Extracts the output type that a validator produces after parsing.
52
+ *
53
+ * The output type may differ from the input type when the schema applies
54
+ * transformations such as default values or type coercion during parsing.
55
+ *
56
+ * @typeParam V - A validator type
57
+ *
58
+ * @example
59
+ * ```typescript
60
+ * const schema = new StringSchema().default('hello')
61
+ * type Input = InferInput<typeof schema> // string | undefined
62
+ * type Output = InferOutput<typeof schema> // string
63
+ * ```
64
+ */
9
65
  export type InferOutput<V extends Validator> = V['__lex']['output'];
66
+ /**
67
+ * Alias for {@link InferInput} for convenient type inference.
68
+ *
69
+ * @typeParam V - A validator type
70
+ */
10
71
  export type { InferInput as Infer };
11
72
  export interface Validator<TInput = unknown, TOutput = TInput> {
12
73
  /**
13
74
  * This property is used for type inference purposes and does not actually
14
75
  * exist at runtime.
15
76
  *
77
+ * @internal
16
78
  * @deprecated **INTERNAL API, DO NOT USE**.
17
79
  */
18
80
  readonly ['__lex']: {
19
- /** @internal The inferred validation type */
20
81
  input: TInput;
21
- /** @internal The inferred parse type */
22
82
  output: TOutput;
23
83
  };
24
84
  /**
@@ -49,57 +109,334 @@ export interface Validator<TInput = unknown, TOutput = TInput> {
49
109
  */
50
110
  validateInContext(input: unknown, ctx: ValidationContext): ValidationResult;
51
111
  }
112
+ /**
113
+ * Configuration options for validation and parsing operations.
114
+ *
115
+ * @example
116
+ * ```typescript
117
+ * // Validate mode (strict, no transformations)
118
+ * ValidationContext.validate(data, schema, { mode: 'validate' })
119
+ *
120
+ * // Parse mode (allows transformations like defaults)
121
+ * ValidationContext.validate(data, schema, { mode: 'parse' })
122
+ *
123
+ * // With initial path for nested validation
124
+ * ValidationContext.validate(data, schema, { path: ['user', 'profile'] })
125
+ * ```
126
+ */
52
127
  export type ValidationOptions = {
53
128
  /**
54
- * When set to `"validate"` (default), the result of validation must be
55
- * strictly equal to the input value (i.e. no transformation, such as applying
56
- * default values, is allowed).
129
+ * The validation mode determining how transformations are handled.
130
+ *
131
+ * - `"validate"` (default): Strict validation where the result must be
132
+ * strictly equal to the input value. No transformations such as applying
133
+ * default values are allowed.
134
+ * - `"parse"`: Allows the schema to transform the input value, such as
135
+ * applying default values or performing type coercion.
57
136
  */
58
137
  mode?: 'validate' | 'parse';
59
138
  /**
60
- * The path to the value being validated. This is used to provide more
61
- * context in validation issues.
139
+ * The initial path to the value being validated.
140
+ *
141
+ * This is used to provide context in validation issues when validating
142
+ * nested structures. The path is prepended to all issue paths.
143
+ *
144
+ * @example
145
+ * ```typescript
146
+ * // Issues will be reported at paths like "user.name" instead of just "name"
147
+ * ValidationContext.validate(data, schema, { path: ['user'] })
148
+ * ```
62
149
  */
63
150
  path?: readonly PropertyKey[];
64
151
  };
152
+ /**
153
+ * Manages the state and context for validation operations.
154
+ *
155
+ * The `ValidationContext` class is responsible for:
156
+ * - Tracking the current path in nested structures for error reporting
157
+ * - Collecting validation issues during traversal
158
+ * - Enforcing validation mode (validate vs parse)
159
+ * - Providing factory methods for creating validation results
160
+ *
161
+ * Use the static {@link ValidationContext.validate} method as the primary entry point
162
+ * for validation. This ensures proper mode enforcement and issue aggregation.
163
+ *
164
+ * @example
165
+ * ```typescript
166
+ * // Primary usage via static method
167
+ * const result = ValidationContext.validate(data, schema, { mode: 'parse' })
168
+ *
169
+ * // Within a custom validator implementation
170
+ * class MyValidator implements Validator {
171
+ * validateInContext(input: unknown, ctx: ValidationContext): ValidationResult {
172
+ * if (typeof input !== 'string') {
173
+ * return ctx.issueInvalidType(input, 'string')
174
+ * }
175
+ * return ctx.success(input)
176
+ * }
177
+ * }
178
+ * ```
179
+ */
65
180
  export declare class ValidationContext {
66
181
  readonly options: Required<ValidationOptions>;
182
+ /**
183
+ * Validates input against a validator in parse mode.
184
+ *
185
+ * In parse mode, the schema may transform the input (e.g., apply defaults).
186
+ *
187
+ * @param input - The value to validate
188
+ * @param validator - The validator to use
189
+ * @param options - Validation options with mode set to 'parse'
190
+ * @returns A validation result with the parsed output type
191
+ */
67
192
  static validate<V extends Validator>(input: unknown, validator: V, options: ValidationOptions & {
68
193
  mode: 'parse';
69
194
  }): ValidationResult<InferOutput<V>>;
195
+ /**
196
+ * Validates input against a validator in validate mode (default).
197
+ *
198
+ * In validate mode, the result must be strictly equal to the input.
199
+ * No transformations are allowed.
200
+ *
201
+ * @typeParam V - The validator type
202
+ * @typeParam I - The input type
203
+ * @param input - The value to validate
204
+ * @param validator - The validator to use
205
+ * @param options - Optional validation options (defaults to validate mode)
206
+ * @returns A validation result preserving the input type intersected with the schema type
207
+ */
70
208
  static validate<V extends Validator, I = unknown>(input: I, validator: V, options?: ValidationOptions & {
71
209
  mode?: 'validate';
72
210
  }): ValidationResult<I & InferInput<V>>;
211
+ /**
212
+ * Validates input against a validator with configurable options.
213
+ *
214
+ * @param input - The value to validate
215
+ * @param validator - The validator to use
216
+ * @param options - Optional validation options
217
+ * @returns A validation result with either the input or output type
218
+ */
73
219
  static validate<V extends Validator>(input: unknown, validator: V, options?: ValidationOptions): ValidationResult<InferOutput<V> | InferInput<V>>;
220
+ /**
221
+ * The current path being validated, used for error reporting.
222
+ */
74
223
  protected readonly currentPath: PropertyKey[];
224
+ /**
225
+ * Accumulated validation issues collected during traversal.
226
+ */
75
227
  protected readonly issues: Issue[];
228
+ /**
229
+ * Creates a new validation context with the specified options.
230
+ *
231
+ * @param options - The validation options (path and mode are required)
232
+ */
76
233
  constructor(options: Required<ValidationOptions>);
234
+ /**
235
+ * Returns a copy of the current validation path.
236
+ *
237
+ * The path represents the location in the data structure being validated,
238
+ * used for constructing meaningful error messages.
239
+ */
77
240
  get path(): PropertyKey[];
241
+ /**
242
+ * Creates a new path by appending segments to the current path.
243
+ *
244
+ * @param path - Optional path segment(s) to append
245
+ * @returns A new path array with the segment(s) appended
246
+ */
78
247
  concatPath(path?: PropertyKey | readonly PropertyKey[]): PropertyKey[];
79
248
  /**
80
- * This is basically the entry point for validation within a context. Use this
81
- * method instead of using {@link Validator.validateInContext} directly,
82
- * because this method ensures the proper use of {@link ValidationOptions}.
249
+ * Validates input against a validator within this context.
250
+ *
251
+ * This is the primary entry point for validation within a context. Always use
252
+ * this method instead of calling {@link Validator.validateInContext} directly,
253
+ * as this method enforces validation mode rules and handles transformation detection.
254
+ *
255
+ * @typeParam V - The validator type
256
+ * @param input - The value to validate
257
+ * @param validator - The validator to use
258
+ * @returns A validation result with the validated value or error
83
259
  */
84
260
  validate<V extends Validator>(input: unknown, validator: V): ValidationResult<InferInput<V>>;
261
+ /**
262
+ * Validates a child property of an object within this context.
263
+ *
264
+ * This method automatically manages the path stack, pushing the property key
265
+ * before validation and popping it afterward. Use this for validating object
266
+ * properties to ensure proper path tracking in error messages.
267
+ *
268
+ * @typeParam I - The input object type
269
+ * @typeParam K - The property key type
270
+ * @typeParam V - The validator type
271
+ * @param input - The parent object containing the property
272
+ * @param key - The property key to validate
273
+ * @param validator - The validator to use for the property value
274
+ * @returns A validation result for the property value
275
+ *
276
+ * @example
277
+ * ```typescript
278
+ * // In a custom object validator
279
+ * const result = ctx.validateChild(input, 'name', stringSchema)
280
+ * // If validation fails, error path will include 'name'
281
+ * ```
282
+ */
85
283
  validateChild<I extends object, K extends PropertyKey & keyof I, V extends Validator>(input: I, key: K, validator: V): ValidationResult<InferInput<V>>;
284
+ /**
285
+ * Adds a validation issue to the context without immediately failing.
286
+ *
287
+ * Use this method to collect multiple issues during validation before
288
+ * determining the final result. Issues added this way will be included
289
+ * in the final error if validation fails.
290
+ *
291
+ * @param issue - The validation issue to add
292
+ */
86
293
  addIssue(issue: Issue): void;
294
+ /**
295
+ * Creates a successful validation result with the given value.
296
+ *
297
+ * @typeParam V - The value type
298
+ * @param value - The validated value
299
+ * @returns A successful validation result
300
+ */
87
301
  success<V>(value: V): ValidationResult<V>;
302
+ /**
303
+ * Creates a failed validation result with the given error.
304
+ *
305
+ * @param reason - The validation error
306
+ * @returns A failed validation result
307
+ */
88
308
  failure(reason: ValidationError): ValidationFailure;
309
+ /**
310
+ * Creates a failed validation result from a single issue.
311
+ *
312
+ * Any previously accumulated issues in the context are included in the error.
313
+ *
314
+ * @param issue - The validation issue that caused the failure
315
+ * @returns A failed validation result
316
+ */
89
317
  issue(issue: Issue): ValidationFailure;
318
+ /**
319
+ * Creates a failure for an invalid value that doesn't match expected values.
320
+ *
321
+ * @param input - The actual value that was received
322
+ * @param values - The expected valid values
323
+ * @returns A failed validation result with an invalid value issue
324
+ */
90
325
  issueInvalidValue(input: unknown, values: readonly unknown[]): ValidationFailure;
326
+ /**
327
+ * Creates a failure for an invalid type.
328
+ *
329
+ * @param input - The actual value that was received
330
+ * @param expected - The expected type name
331
+ * @returns A failed validation result with an invalid type issue
332
+ */
91
333
  issueInvalidType(input: unknown, expected: string): ValidationFailure;
334
+ /**
335
+ * Creates a failure for a missing required key in an object.
336
+ *
337
+ * @param input - The object missing the required key
338
+ * @param key - The name of the required key
339
+ * @returns A failed validation result with a required key issue
340
+ */
92
341
  issueRequiredKey(input: object, key: PropertyKey): ValidationFailure;
342
+ /**
343
+ * Creates a failure for an invalid string format.
344
+ *
345
+ * @param input - The actual value that was received
346
+ * @param format - The expected format name (e.g., 'did', 'handle', 'uri')
347
+ * @param msg - Optional additional message describing the format error
348
+ * @returns A failed validation result with an invalid format issue
349
+ */
93
350
  issueInvalidFormat(input: unknown, format: string, msg?: string): ValidationFailure;
351
+ /**
352
+ * Creates a failure for a value that exceeds a maximum constraint.
353
+ *
354
+ * @param input - The actual value that was received
355
+ * @param type - The type of measurement (e.g., 'string', 'array', 'bytes')
356
+ * @param max - The maximum allowed value
357
+ * @param actual - The actual measured value
358
+ * @returns A failed validation result with a too big issue
359
+ */
94
360
  issueTooBig(input: unknown, type: MeasurableType, max: number, actual: number): ValidationFailure;
361
+ /**
362
+ * Creates a failure for a value that is below a minimum constraint.
363
+ *
364
+ * @param input - The actual value that was received
365
+ * @param type - The type of measurement (e.g., 'string', 'array', 'bytes')
366
+ * @param min - The minimum required value
367
+ * @param actual - The actual measured value
368
+ * @returns A failed validation result with a too small issue
369
+ */
95
370
  issueTooSmall(input: unknown, type: MeasurableType, min: number, actual: number): ValidationFailure;
371
+ /**
372
+ * Creates a failure for an invalid property value within an object.
373
+ *
374
+ * This is a convenience method that automatically extracts the property value
375
+ * and constructs the appropriate path.
376
+ *
377
+ * @typeParam I - The input object type
378
+ * @param input - The object containing the invalid property
379
+ * @param property - The property key with the invalid value
380
+ * @param values - The expected valid values
381
+ * @returns A failed validation result with an invalid value issue at the property path
382
+ */
96
383
  issueInvalidPropertyValue<I>(input: I, property: keyof I & PropertyKey, values: readonly unknown[]): ValidationFailure;
384
+ /**
385
+ * Creates a failure for an invalid property type within an object.
386
+ *
387
+ * This is a convenience method that automatically extracts the property value
388
+ * and constructs the appropriate path.
389
+ *
390
+ * @typeParam I - The input object type
391
+ * @param input - The object containing the invalid property
392
+ * @param property - The property key with the invalid type
393
+ * @param expected - The expected type name
394
+ * @returns A failed validation result with an invalid type issue at the property path
395
+ */
97
396
  issueInvalidPropertyType<I>(input: I, property: keyof I & PropertyKey, expected: string): ValidationFailure;
98
397
  }
398
+ /**
399
+ * Recursively unwraps a wrapped validator to its innermost validator type.
400
+ *
401
+ * Some validators wrap other validators (e.g., optional, nullable). This type
402
+ * utility recursively unwraps such wrappers to reveal the core validator.
403
+ *
404
+ * @typeParam T - A validator type, possibly wrapped
405
+ *
406
+ * @example
407
+ * ```typescript
408
+ * type Inner = UnwrapValidator<OptionalValidator<NullableValidator<StringSchema>>>
409
+ * // Result: StringSchema
410
+ * ```
411
+ */
99
412
  export type UnwrapValidator<T extends Validator> = T extends {
100
413
  unwrap(): infer U extends Validator;
101
414
  } ? UnwrapValidator<U> : T;
415
+ /**
416
+ * Interface for validators that wrap another validator.
417
+ *
418
+ * Implement this interface when creating validators that wrap or modify
419
+ * the behavior of another validator (e.g., optional, nullable, transform).
420
+ *
421
+ * @typeParam Validator - The type of the wrapped validator
422
+ *
423
+ * @example
424
+ * ```typescript
425
+ * class OptionalSchema<V extends Validator> implements WrappedValidator<V> {
426
+ * constructor(private inner: V) {}
427
+ *
428
+ * unwrap(): V {
429
+ * return this.inner
430
+ * }
431
+ * }
432
+ * ```
433
+ */
102
434
  export interface WrappedValidator<out Validator> {
435
+ /**
436
+ * Returns the inner wrapped validator.
437
+ *
438
+ * @returns The wrapped validator
439
+ */
103
440
  unwrap(): Validator;
104
441
  }
105
442
  //# sourceMappingURL=validator.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/core/validator.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/core/validator.ts"],"names":[],"mappings":"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"}