@atproto/lex-schema 0.0.8 → 0.0.10

package/src/core/validation-issue.ts

@@ -44,7 +44,7 @@ export class IssueInvalidFormat extends Issue {
   }
 
   toString() {
-    return `Invalid ${this.formatDescription} format${this.message ? ` (${this.message})` : ''}${stringifyPath(this.path)} (got ${stringifyValue(this.input)})`
+    return `Invalid ${this.formatDescription}${this.message ? ` (${this.message})` : ''}${stringifyPath(this.path)} (got ${stringifyValue(this.input)})`
   }
 
   toJSON() {

package/src/core/validator.ts

@@ -12,47 +12,48 @@ import {
   MeasurableType,
 } from './validation-issue.js'
 
-export type ValidationSuccess<Value = any> = ResultSuccess<Value>
+export type ValidationSuccess<Value = unknown> = ResultSuccess<Value>
 export type ValidationFailure = ResultFailure<ValidationError>
-export type ValidationResult<Value = any> =
+export type ValidationResult<Value = unknown> =
   | ValidationSuccess<Value>
   | ValidationFailure
 
-export type ValidationOptions = {
-  path?: PropertyKey[]
-
-  /** @default true */
-  allowTransform?: boolean
-}
+export type InferInput<V extends Validator> = V['__lex']['input']
+export type InferOutput<V extends Validator> = V['__lex']['output']
 
-export type Infer<T extends Validator> = T['__lex']['output']
+export type { InferInput as Infer }
 
-export interface Validator<Output = any> {
+export interface Validator<TInput = unknown, TOutput = TInput> {
   /**
    * This property is used for type inference purposes and does not actually
    * exist at runtime.
    *
    * @deprecated **INTERNAL API, DO NOT USE**.
    */
-  readonly ['__lex']: { output: Output }
+  readonly ['__lex']: {
+    /** @internal The inferred validation type */
+    input: TInput
+    /** @internal The inferred parse type */
+    output: TOutput
+  }
 
   /**
-   * @internal **INTERNAL API**: use {@link ValidatorContext.validate} instead
+   * @internal **INTERNAL API**: use {@link ValidationContext.validate} instead
    *
    * This method is implemented by subclasses to perform transformation and
    * validation of the input value. Do not call this method directly; as the
-   * {@link ValidatorContext.options.allowTransform} option will **not** be
-   * enforced. See {@link ValidatorContext.validate} for details. When
-   * delegating validation from one validator sub-class implementation to
-   * another schema, {@link ValidatorContext.validate} must be used instead of
-   * calling {@link Validator.validateInContext}. This will allow to stop the
-   * validation process if the value was transformed (by the other schema) but
+   * {@link ValidationContext.options.mode} option will **not** be enforced. See
+   * {@link ValidationContext.validate} for details. When delegating validation
+   * from one validator sub-class implementation to another schema,
+   * {@link ValidationContext.validate} must be used instead of calling
+   * {@link Validator.validateInContext}. This will allow to stop the validation
+   * process if the value was transformed (by the other schema) but
    * transformations are not allowed.
    *
    * By convention, the {@link ValidationResult} must return the original input
    * value if validation was successful and no transformation was applied (i.e.
    * the input already conformed to the schema). If a default value, or any
-   * other transformation was applied, the returned value c&an be different from
+   * other transformation was applied, the returned value can be different from
    * the input.
    *
    * This convention allows the {@link Validator.check check} and
@@ -60,34 +61,64 @@ export interface Validator<Output = any> {
    * exactly matches the schema (without defaults or transformations), by
    * checking if the returned value is strictly equal to the input.
    *
-   * @see {@link ValidatorContext.validate}
+   * @see {@link ValidationContext.validate}
    */
-  validateInContext(
-    input: unknown,
-    ctx: ValidatorContext,
-  ): ValidationResult<Output>
+  validateInContext(input: unknown, ctx: ValidationContext): ValidationResult
 }
 
-export class ValidatorContext {
+export type ValidationOptions = {
+  /**
+   * When set to `"validate"` (default), the result of validation must be
+   * strictly equal to the input value (i.e. no transformation, such as applying
+   * default values, is allowed).
+   */
+  mode?: 'validate' | 'parse'
+
   /**
-   * Creates a new validation context and validates the input using the
-   * provided validator.
+   * The path to the value being validated. This is used to provide more
+   * context in validation issues.
    */
-  static validate<V>(
+  path?: readonly PropertyKey[]
+}
+
+export class ValidationContext {
+  static validate<V extends Validator>(
+    input: unknown,
+    validator: V,
+    options: ValidationOptions & {
+      mode: 'parse'
+    },
+  ): ValidationResult<InferOutput<V>>
+  static validate<V extends Validator, I = unknown>(
+    input: I,
+    validator: V,
+    options?: ValidationOptions & {
+      mode?: 'validate'
+    },
+  ): ValidationResult<I & InferInput<V>>
+  static validate<V extends Validator>(
+    input: unknown,
+    validator: V,
+    options?: ValidationOptions,
+  ): ValidationResult<InferOutput<V> | InferInput<V>>
+  static validate<V extends Validator>(
     input: unknown,
-    validator: Validator<V>,
-    options: ValidationOptions = {},
-  ): ValidationResult<V> {
-    const context = new ValidatorContext(options)
+    validator: V,
+    options?: ValidationOptions,
+  ): ValidationResult<InferOutput<V> | InferInput<V>> {
+    const context = new ValidationContext({
+      path: options?.path ?? [],
+      mode: options?.mode ?? 'validate',
+    })
     return context.validate(input, validator)
   }
 
-  private readonly currentPath: PropertyKey[]
-  private readonly issues: Issue[] = []
+  protected readonly currentPath: PropertyKey[]
+  protected readonly issues: Issue[] = []
 
-  protected constructor(readonly options: ValidationOptions) {
+  constructor(readonly options: Required<ValidationOptions>) {
     // Create a copy because we will be mutating the array during validation.
-    this.currentPath = options?.path != null ? Array.from(options.path) : []
+    this.currentPath = Array.from(options.path)
   }
 
   get path() {
@@ -101,22 +132,27 @@ export class ValidatorContext {
 
   /**
    * This is basically the entry point for validation within a context. Use this
-   * method instead of {@link Validator.validateInContext} directly, because
-   * this method enforces the {@link ValidationOptions.allowTransform} option.
+   * method instead of using {@link Validator.validateInContext} directly,
+   * because this method ensures the proper use of {@link ValidationOptions}.
    */
-  validate<V>(input: unknown, validator: Validator<V>): ValidationResult<V> {
+  validate<V extends Validator>(
+    input: unknown,
+    validator: V,
+  ): ValidationResult<InferInput<V>> {
     // This is the only place where validateInContext should be called.
     const result = validator.validateInContext(input, this)
 
     if (result.success) {
-      if (
-        // Defaults to true
-        this.options?.allowTransform === false &&
-        !Object.is(result.value, input)
-      ) {
+      if (this.issues.length > 0) {
+        // Validator returned a success but issues were added via the context.
+        // This means the overall validation failed.
+        return failure(new ValidationError(Array.from(this.issues)))
+      }
+
+      if (this.options.mode !== 'parse' && !Object.is(result.value, input)) {
         // If the value changed, it means that a default (or some other
         // transformation) was applied, meaning that the original value did
-        // *not* match the (output) schema. When "allowTransform" is false, we
+        // *not* match the (output) schema. When not in "parse" mode, we
         // consider this a failure.
 
         // This check is the reason why Validator.validateInContext should not
@@ -129,22 +165,16 @@ export class ValidatorContext {
         // "failure" method below), resulting in a more complete error report.
         return this.issueInvalidValue(input, [result.value])
       }
-
-      if (this.issues.length > 0) {
-        // Validator returned a success but issues were added via the context.
-        // This means the overall validation failed.
-        return failure(new ValidationError(Array.from(this.issues)))
-      }
     }
 
-    return result as ValidationResult<V>
+    return result as ValidationResult<InferInput<V>>
   }
 
   validateChild<
     I extends object,
     K extends PropertyKey & keyof I,
     V extends Validator,
-  >(input: I, key: K, validator: V): ValidationResult<Infer<V>> {
+  >(input: I, key: K, validator: V): ValidationResult<InferInput<V>> {
     // Instead of creating a new context, we just push/pop the path segment.
     this.currentPath.push(key)
     try {
@@ -224,3 +254,13 @@ export class ValidatorContext {
     return this.issue(new IssueInvalidType(path, value, [expected]))
   }
 }
+
+export type UnwrapValidator<T extends Validator> = T extends {
+  unwrap(): infer U extends Validator
+}
+  ? UnwrapValidator<U>
+  : T
+
+export interface WrappedValidator<out Validator> {
+  unwrap(): Validator
+}

package/src/external.ts

@@ -1,407 +1,3 @@
-import {
-  $Type,
-  $TypeOf,
-  $type,
-  Infer,
-  LexiconRecordKey,
-  NsidString,
-  PropertyKey,
-  Schema,
-  Validator,
-} from './core.js'
-import {
-  ArraySchema,
-  ArraySchemaOptions,
-  BlobSchema,
-  BlobSchemaOptions,
-  BooleanSchema,
-  BooleanSchemaOptions,
-  BytesSchema,
-  BytesSchemaOptions,
-  CidSchema,
-  CidSchemaOptions,
-  CustomAssertion,
-  CustomSchema,
-  DictSchema,
-  DiscriminatedUnionSchema,
-  DiscriminatedUnionVariants,
-  EnumSchema,
-  EnumSchemaOptions,
-  IntegerSchema,
-  IntegerSchemaOptions,
-  IntersectionSchema,
-  LiteralSchema,
-  LiteralSchemaOptions,
-  NeverSchema,
-  NullSchema,
-  NullableSchema,
-  ObjectSchema,
-  ObjectSchemaShape,
-  OptionalSchema,
-  ParamsSchema,
-  ParamsSchemaShape,
-  Payload,
-  PayloadSchema,
-  Permission,
-  PermissionOptions,
-  PermissionSet,
-  PermissionSetOptions,
-  Procedure,
-  Query,
-  RecordSchema,
-  RefSchema,
-  RefSchemaGetter,
-  RegexpSchema,
-  StringSchema,
-  StringSchemaOptions,
-  Subscription,
-  TokenSchema,
-  TypedObjectSchema,
-  TypedRefGetter,
-  TypedRefSchema,
-  TypedUnionSchema,
-  UnionSchema,
-  UnionSchemaValidators,
-  UnknownObjectOutput,
-  UnknownObjectSchema,
-  UnknownSchema,
-  refine,
-} from './schema.js'
-import { memoizedOptions, memoizedTransformer } from './util/memoize.js'
-
 export * from './core.js'
 export * from './helpers.js'
 export * from './schema.js'
-
-export { _null as null }
-
-export const never = /*#__PURE__*/ memoizedOptions(function () {
-  return new NeverSchema()
-})
-
-export const unknown = /*#__PURE__*/ memoizedOptions(function () {
-  return new UnknownSchema()
-})
-
-const _null = /*#__PURE__*/ memoizedOptions(function () {
-  return new NullSchema()
-})
-
-/*@__NO_SIDE_EFFECTS__*/
-export function literal<const V extends null | string | number | boolean>(
-  value: V,
-  options?: LiteralSchemaOptions<V>,
-) {
-  return new LiteralSchema<V>(value, options)
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-export function _enum<const V extends null | string | number | boolean>(
-  value: readonly V[],
-  options?: EnumSchemaOptions<V>,
-) {
-  return new EnumSchema<V>(value, options)
-}
-
-// @NOTE "enum" is a reserved keyword in JS/TS
-export { _enum as enum }
-
-export const boolean = /*#__PURE__*/ memoizedOptions(
-  function (options?: BooleanSchemaOptions) {
-    return new BooleanSchema(options)
-  },
-  (options) => {
-    const keys = Object.keys(options)
-    if (keys.length === 1 && keys[0] === 'default') return options.default!
-  },
-)
-
-export const integer = /*#__PURE__*/ memoizedOptions(function (
-  options?: IntegerSchemaOptions,
-) {
-  return new IntegerSchema(options)
-})
-
-export const cidLink = /*#__PURE__*/ memoizedOptions(function <
-  O extends CidSchemaOptions = NonNullable<unknown>,
->(options: O = {} as O) {
-  return new CidSchema(options)
-})
-
-export const bytes = /*#__PURE__*/ memoizedOptions(function (
-  options?: BytesSchemaOptions,
-) {
-  return new BytesSchema(options)
-})
-
-export const blob = /*#__PURE__*/ memoizedOptions(function <
-  O extends BlobSchemaOptions = NonNullable<unknown>,
->(options: O = {} as O) {
-  return new BlobSchema(options)
-})
-
-export const string = /*#__PURE__*/ memoizedOptions(function <
-  const O extends StringSchemaOptions = NonNullable<unknown>,
->(options: StringSchemaOptions & O = {} as O) {
-  return new StringSchema<O>(options)
-})
-
-/*@__NO_SIDE_EFFECTS__*/
-export function regexp<T extends string = string>(pattern: RegExp) {
-  return new RegexpSchema<T>(pattern)
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-export function array<const S extends Validator>(
-  items: S,
-  options?: ArraySchemaOptions,
-): ArraySchema<S>
-export function array<T, const S extends Validator<T> = Validator<T>>(
-  items: S,
-  options?: ArraySchemaOptions,
-): ArraySchema<S>
-export function array<const S extends Validator>(
-  items: S,
-  options?: ArraySchemaOptions,
-) {
-  return new ArraySchema<S>(items, options)
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-export function object<const P extends ObjectSchemaShape>(properties: P) {
-  return new ObjectSchema<P>(properties)
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-export function dict<
-  const K extends Validator<string>,
-  const V extends Validator,
->(key: K, value: V) {
-  return new DictSchema<K, V>(key, value)
-}
-
-// Utility
-export type { UnknownObjectOutput as UnknownObject }
-
-export const unknownObject = /*#__PURE__*/ memoizedOptions(function () {
-  return new UnknownObjectSchema()
-})
-
-/*@__NO_SIDE_EFFECTS__*/
-export function ref<T>(get: RefSchemaGetter<T>) {
-  return new RefSchema<T>(get)
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-export function custom<T>(
-  assertion: CustomAssertion<T>,
-  message: string,
-  path?: PropertyKey | readonly PropertyKey[],
-) {
-  return new CustomSchema<T>(assertion, message, path)
-}
-
-export const nullable = /*#__PURE__*/ memoizedTransformer(function <
-  const S extends Validator,
->(schema: S) {
-  return new NullableSchema<Infer<S>>(schema)
-})
-
-export const optional = /*#__PURE__*/ memoizedTransformer(function <
-  const S extends Validator,
->(schema: S) {
-  return new OptionalSchema<Infer<S>>(schema)
-})
-
-/*@__NO_SIDE_EFFECTS__*/
-export function union<const V extends UnionSchemaValidators>(validators: V) {
-  return new UnionSchema<V>(validators)
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-export function intersection<
-  const Left extends ObjectSchema,
-  const Right extends DictSchema,
->(left: Left, right: Right) {
-  return new IntersectionSchema<Left, Right>(left, right)
-}
-
-export { refine }
-
-/*@__NO_SIDE_EFFECTS__*/
-export function discriminatedUnion<
-  const Discriminator extends string,
-  const Options extends DiscriminatedUnionVariants<Discriminator>,
->(discriminator: Discriminator, variants: Options) {
-  return new DiscriminatedUnionSchema<Discriminator, Options>(
-    discriminator,
-    variants,
-  )
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-export function token<const N extends NsidString, const H extends string>(
-  nsid: N,
-  hash: H,
-) {
-  return new TokenSchema($type(nsid, hash))
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-export function typedRef<const V extends { $type?: string }>(
-  get: TypedRefGetter<V>,
-) {
-  return new TypedRefSchema<V>(get)
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-export function typedUnion<
-  const R extends readonly TypedRefSchema[],
-  const C extends boolean,
->(refs: R, closed: C) {
-  return new TypedUnionSchema<R, C>(refs, closed)
-}
-
-/**
- * This function offers two overloads:
- * - One that allows creating a {@link TypedObjectSchema}, and infer the output
- *   type from the provided arguments, without requiring to specify any of the
- *   generics. This is useful when you want to define a record without
- *   explicitly defining its interface. This version does not support circular
- *   references, as TypeScript cannot infer types in such cases.
- * - One allows creating a {@link TypedObjectSchema} with an explicitly defined
- *   interface. This will typically be used by codegen (`lex build`) to generate
- *   schemas that work even if they contain circular references.
- */
-export function typedObject<
-  const N extends NsidString,
-  const H extends string,
-  const S extends Validator<{ [k: string]: unknown }>,
->(nsid: N, hash: H, schema: S): TypedObjectSchema<$Type<N, H>, S>
-export function typedObject<V extends { $type?: $Type }>(
-  nsid: V extends { $type?: infer T extends string }
-    ? T extends `${infer N}#${string}`
-      ? N
-      : T // (T is a "main" type, so already an NSID)
-    : never,
-  hash: V extends { $type?: infer T extends string }
-    ? T extends `${string}#${infer H}`
-      ? H
-      : 'main'
-    : never,
-  schema: Validator<Omit<V, '$type'>>,
-): TypedObjectSchema<$TypeOf<V>, Validator<Omit<V, '$type'>>>
-/*@__NO_SIDE_EFFECTS__*/
-export function typedObject<
-  const N extends NsidString,
-  const H extends string,
-  const S extends Validator<{ [k: string]: unknown }>,
->(nsid: N, hash: H, schema: S) {
-  return new TypedObjectSchema<$Type<N, H>, S>($type(nsid, hash), schema)
-}
-
-/**
- * Ensures that a `$type` used in a record is a valid NSID (i.e. no fragment).
- */
-type AsNsid<T> = T extends `${string}#${string}` ? never : T
-
-/**
- * This function offers two overloads:
- * - One that allows creating a {@link RecordSchema}, and infer the output type
- *   from the provided arguments, without requiring to specify any of the
- *   generics. This is useful when you want to define a record without
- *   explicitly defining its interface. This version does not support circular
- *   references, as TypeScript cannot infer types in such cases.
- * - One allows creating a {@link RecordSchema} with an explicitly defined
- *   interface. This will typically be used by codegen (`lex build`) to generate
- *   schemas that work even if they contain circular references.
- */
-export function record<
-  const K extends LexiconRecordKey,
-  const T extends NsidString,
-  const S extends Validator<{ [k: string]: unknown }>,
->(key: K, type: AsNsid<T>, schema: S): RecordSchema<K, T, S>
-export function record<
-  const K extends LexiconRecordKey,
-  const V extends { $type: NsidString },
->(
-  key: K,
-  type: AsNsid<V['$type']>,
-  schema: Validator<Omit<V, '$type'>>,
-): RecordSchema<K, V['$type'], Validator<Omit<V, '$type'>>>
-/*@__NO_SIDE_EFFECTS__*/
-export function record<
-  const K extends LexiconRecordKey,
-  const T extends NsidString,
-  const S extends Validator<{ [k: string]: unknown }>,
->(key: K, type: T, schema: S) {
-  return new RecordSchema<K, T, S>(key, type, schema)
-}
-
-export const params = /*#__PURE__*/ memoizedOptions(function <
-  const P extends ParamsSchemaShape = NonNullable<unknown>,
->(properties: P = {} as P) {
-  return new ParamsSchema<P>(properties)
-})
-
-/*@__NO_SIDE_EFFECTS__*/
-export function payload<
-  const E extends string | undefined = undefined,
-  const S extends PayloadSchema<E> = undefined,
->(encoding: E = undefined as E, schema: S = undefined as S) {
-  return new Payload<E, S>(encoding, schema)
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-export function jsonPayload<const P extends ObjectSchemaShape>(
-  properties: P,
-): Payload<'application/json', ObjectSchema<P>> {
-  return payload('application/json', object(properties))
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-export function query<
-  const N extends NsidString,
-  const P extends ParamsSchema,
-  const O extends Payload,
-  const E extends undefined | readonly string[] = undefined,
->(nsid: N, parameters: P, output: O, errors: E = undefined as E) {
-  return new Query<N, P, O, E>(nsid, parameters, output, errors)
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-export function procedure<
-  const N extends NsidString,
-  const P extends ParamsSchema,
-  const I extends Payload,
-  const O extends Payload,
-  const E extends undefined | readonly string[] = undefined,
->(nsid: N, parameters: P, input: I, output: O, errors: E = undefined as E) {
-  return new Procedure<N, P, I, O, E>(nsid, parameters, input, output, errors)
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-export function subscription<
-  const N extends NsidString,
-  const P extends ParamsSchema,
-  const M extends Schema,
-  const E extends undefined | readonly string[] = undefined,
->(nsid: N, parameters: P, message: M, errors: E = undefined as E) {
-  return new Subscription<N, P, M, E>(nsid, parameters, message, errors)
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-export function permission<
-  const R extends string,
-  const O extends PermissionOptions,
->(resource: R, options: PermissionOptions & O = {} as O) {
-  return new Permission<R, O>(resource, options)
-}
-
-/*@__NO_SIDE_EFFECTS__*/
-export function permissionSet<
-  const N extends NsidString,
-  const P extends readonly Permission[],
->(nsid: N, permissions: P, options?: PermissionSetOptions) {
-  return new PermissionSet<N, P>(nsid, permissions, options)
-}