@atproto/lex-schema 0.0.0

package/src/schema/object.ts

@@ -0,0 +1,180 @@
+import { isPlainObject } from '@atproto/lex-data'
+import { Simplify } from '../core.js'
+import {
+  Infer,
+  ValidationResult,
+  Validator,
+  ValidatorContext,
+} from '../validation.js'
+import { DictSchema } from './dict.js'
+
+export type ObjectSchemaProperties = { [_ in string]: Validator<any> }
+export type ObjectSchemaOptions = {
+  required?: readonly string[]
+  nullable?: readonly string[]
+  unknownProperties?: 'strict' | DictSchema
+}
+
+export type ObjectSchemaNullValue<
+  O extends ObjectSchemaOptions,
+  K extends string,
+> = O extends { nullable: readonly (infer N extends string)[] }
+  ? K extends N
+    ? null
+    : never
+  : never
+
+export type ObjectSchemaPropertiesOutput<
+  P extends ObjectSchemaProperties,
+  O extends ObjectSchemaOptions,
+> = O extends { required: readonly (infer R extends string)[] }
+  ? {
+      -readonly [K in string & keyof P & R]-?:
+        | Infer<P[K]>
+        | ObjectSchemaNullValue<O, K>
+    } & {
+      -readonly [K in Exclude<string & keyof P, R>]?:
+        | Infer<P[K]>
+        | ObjectSchemaNullValue<O, K>
+    }
+  : {
+      -readonly [K in string & keyof P]?:
+        | Infer<P[K]>
+        | ObjectSchemaNullValue<O, K>
+    }
+
+/**
+ * Allows to more accurately represent the intersection of two object types
+ * where both types may share some keys, and one of them uses an index
+ * signature.
+ *
+ * @see {@link https://www.typescriptlang.org/play/?#code/C4TwDgpgBAglC8UDeUBmB7dAuKByARgIYBOuUAvlAGTJQDaA+lAJYB2UAzsMWwOYC6OVgFcAtvgjEKAKGkATCAGMANiWiL0rLlEI4YsjVuBQA1hBA4uPVrwRQARBnT2Dm7QDdCy4dESE6ZiD8UAD0IVAi4pJQABQcABbowspyUBIORMT2AJSyEAAeYOjExqCQUACSrMCSHErAzJoAPNJQsFAFNaxyHFAASkrFck1WfAA0UMKsJqzoAO6sAHxjrVAAQh35XT39g8TDozYTUzPzSyuLdqtwVKttMYHoqO00j88bnRDdvawQ7pJ3NpQAD860BbRwSHBQLadAA0ix2G91oJ1vDggAfWABcxPF5QOH8aFtci5aRlaAwVDMfIQVKIKo1Yh1RQNZq0Jw4AgkMjkCYoRiIzjcPioyISKTkRayBQqNRQQzaQgAMRpdL01NpclcRignm8EFVWrsKrVchxQVC4XF0SxmSAA Playground link}
+ */
+type Intersect<
+  A extends Record<string, unknown>,
+  B extends Record<string, unknown>,
+> = B[keyof B] extends never
+  ? A
+  : keyof A & keyof B extends never
+    ? // If A and B don't overlap, just return A & B
+      A & B
+    : // Otherwise, properly represent the fact that accessing using an
+      // index signature could return a value from either A or B
+      A & { [K in keyof B]: B[K] | A[keyof A & K] }
+
+export type ObjectSchemaOutput<
+  P extends ObjectSchemaProperties,
+  O extends ObjectSchemaOptions,
+> = O extends {
+  unknownProperties: Validator<infer D extends Record<string, unknown>>
+}
+  ? Simplify<Intersect<ObjectSchemaPropertiesOutput<P, O>, D>>
+  : Simplify<ObjectSchemaPropertiesOutput<P, O>>
+
+export class ObjectSchema<
+  const Validators extends ObjectSchemaProperties = any,
+  const Options extends ObjectSchemaOptions = any,
+  const Output extends ObjectSchemaOutput<
+    Validators,
+    Options
+  > = ObjectSchemaOutput<Validators, Options>,
+> extends Validator<Output> {
+  constructor(
+    readonly validators: Validators,
+    readonly options: Options,
+  ) {
+    super()
+  }
+
+  get validatorsMap(): Map<string, Validator> {
+    const map = new Map(Object.entries(this.validators))
+
+    // Cache the map on the instance (to avoid re-creating it)
+    Object.defineProperty(this, 'validatorsMap', {
+      value: map,
+      writable: false,
+      enumerable: false,
+      configurable: true,
+    })
+
+    return map
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<Output> {
+    if (!isPlainObject(input)) {
+      return ctx.issueInvalidType(input, ['object'])
+    }
+
+    // Lazily copy value
+    let copy: undefined | Record<string, unknown>
+
+    for (const [key, propDef] of this.validatorsMap) {
+      if (input[key] === null && this.options.nullable?.includes(key)) {
+        continue
+      }
+
+      const result = ctx.validateChild(input, key, propDef)
+      if (!result.success) {
+        // Because default values are provided by child validators, we need to
+        // run the validator to get the default value and, in case of failure,
+        // ignore validation error that were caused by missing keys.
+        if (!(key in input)) {
+          if (this.options.required?.includes(key)) {
+            // Transform into "required key" issue
+            return ctx.issueRequiredKey(input, key)
+          }
+
+          // Ignore missing non-required key
+          continue
+        }
+
+        return result
+      } else if (result.value === undefined) {
+        // Special case for validators that output "undefined" values (typically
+        // UnknownSchema) since they cannot differentiate between "missing key"
+        // and "key with undefined value"
+
+        if (!(key in input)) {
+          // Input was missing the key (was "undefined")
+          if (this.options.required?.includes(key)) {
+            return ctx.issueRequiredKey(input, key)
+          }
+
+          // Ignore missing non-required key
+          continue
+        }
+
+        // if "key" existed in input (would typically be "undefined"), we keep
+        // it as-is by continuing processing as if it was any other value.
+      }
+
+      if (result.value !== input[key]) {
+        copy ??= { ...input }
+        copy[key] = result.value
+      }
+    }
+
+    if (this.options.unknownProperties === 'strict') {
+      for (const key of Object.keys(input)) {
+        if (!this.validatorsMap.has(key)) {
+          return ctx.issueInvalidPropertyType(input, key, 'undefined')
+        }
+      }
+    } else if (this.options.unknownProperties) {
+      const result = this.options.unknownProperties.validateInContext(
+        copy ?? input,
+        ctx,
+        { ignoredKeys: this.validatorsMap },
+      )
+      if (!result.success) return result
+      if (result.value !== input) copy = result.value
+    }
+
+    const output = (copy ?? input) as Output
+
+    return ctx.success(output)
+  }
+}

package/src/schema/params.ts

@@ -0,0 +1,157 @@
+import { isPlainObject } from '@atproto/lex-data'
+import { ValidationResult, Validator, ValidatorContext } from '../validation.js'
+import { Param, ParamScalar, paramSchema } from './_parameters.js'
+import { ObjectSchemaPropertiesOutput } from './object.js'
+import { StringSchema } from './string.js'
+
+export type ParamsSchemaProperties = {
+  [_ in string]: Validator<Param>
+}
+
+export type ParamsSchemaOptions = {
+  required?: readonly string[]
+}
+
+export type ParamsSchemaOutput<
+  P extends ParamsSchemaProperties,
+  O extends ParamsSchemaOptions,
+> = ObjectSchemaPropertiesOutput<P, O>
+
+export type InferParamsSchema<T> =
+  T extends ParamsSchema<infer P, infer O>
+    ? NonNullable<unknown> extends ParamsSchemaOutput<P, O>
+      ? ParamsSchemaOutput<P, O> | undefined
+      : ParamsSchemaOutput<P, O>
+    : never
+
+export class ParamsSchema<
+  const Validators extends ParamsSchemaProperties = ParamsSchemaProperties,
+  const Options extends ParamsSchemaOptions = ParamsSchemaOptions,
+  Output extends ParamsSchemaOutput<Validators, Options> = ParamsSchemaOutput<
+    Validators,
+    Options
+  >,
+> extends Validator<Output> {
+  readonly lexiconType = 'params' as const
+
+  constructor(
+    readonly validators: Validators,
+    readonly options: Options,
+  ) {
+    super()
+  }
+
+  get validatorsMap(): Map<string, Validator<Param>> {
+    const map = new Map(Object.entries(this.validators))
+
+    // Cache the map on the instance (to avoid re-creating it)
+    Object.defineProperty(this, 'validatorsMap', {
+      value: map,
+      writable: false,
+      enumerable: false,
+      configurable: true,
+    })
+
+    return map
+  }
+
+  override validateInContext(
+    input: unknown = {},
+    ctx: ValidatorContext,
+  ): ValidationResult<Output> {
+    if (!isPlainObject(input)) {
+      return ctx.issueInvalidType(input, 'object')
+    }
+
+    // Lazily copy value
+    let copy: undefined | Record<string, unknown>
+
+    // Ensure that non-specified params conform to param schema
+    for (const key in input) {
+      if (this.validatorsMap.has(key)) continue
+
+      const result = ctx.validateChild(input, key, paramSchema)
+      if (!result.success) return result
+
+      if (result.value !== input[key]) {
+        copy ??= { ...input }
+        copy[key] = result.value
+      }
+    }
+
+    for (const [key, propDef] of this.validatorsMap) {
+      const result = ctx.validateChild(input, key, propDef)
+      if (!result.success) {
+        // Because default values are provided by child validators, we need to
+        // run the validator to get the default value and, in case of failure,
+        // ignore validation error that were caused by missing keys.
+        if (!(key in input)) {
+          if (!this.options.required?.includes(key)) {
+            // Ignore missing non-required key
+            continue
+          } else {
+            // Transform into "required key" issue
+            return ctx.issueRequiredKey(input, key)
+          }
+        }
+
+        return result
+      }
+
+      if (result.value !== input[key]) {
+        // Copy on write
+        copy ??= { ...input }
+        copy[key] = result.value
+      }
+    }
+
+    return ctx.success((copy ?? input) as Output)
+  }
+
+  fromURLSearchParams(urlSearchParams: URLSearchParams): Output {
+    const params: Record<string, Param> = {}
+
+    for (const [key, value] of urlSearchParams.entries()) {
+      const validator = this.validatorsMap.get(key)
+
+      const coerced: ParamScalar =
+        validator != null && validator instanceof StringSchema
+          ? value
+          : value === 'true'
+            ? true
+            : value === 'false'
+              ? false
+              : /^-?\d+$/.test(value)
+                ? Number(value)
+                : value
+
+      if (params[key] === undefined) {
+        params[key] = coerced
+      } else if (Array.isArray(params[key])) {
+        params[key].push(coerced)
+      } else {
+        params[key] = [params[key] as ParamScalar, coerced]
+      }
+    }
+
+    return this.parse(params)
+  }
+
+  toURLSearchParams(input: Output): URLSearchParams {
+    const urlSearchParams = new URLSearchParams()
+
+    if (input !== undefined) {
+      for (const [key, value] of Object.entries(input)) {
+        if (Array.isArray(value)) {
+          for (const v of value) {
+            urlSearchParams.append(key, String(v))
+          }
+        } else if (value !== undefined) {
+          urlSearchParams.append(key, String(value))
+        }
+      }
+    }
+
+    return urlSearchParams
+  }
+}

package/src/schema/payload.ts

@@ -0,0 +1,53 @@
+import { LexValue } from '@atproto/lex-data'
+import { Validator } from '../validation.js'
+
+export type LexBody<E extends string = any> = E extends `text/${string}`
+  ? string // Text encodings always yield string bodies
+  : E extends 'application/json'
+    ? LexValue
+    : Uint8Array
+
+export type InferPayloadEncoding<P extends Payload> =
+  P extends Payload<infer E, any> ? E : undefined
+
+export type InferPayloadBody<P extends Payload> =
+  P extends Payload<any, infer S>
+    ? S extends Validator<infer V>
+      ? V
+      : P extends Payload<infer E extends string>
+        ? LexBody<E>
+        : undefined
+    : undefined
+
+export type PayloadOutput<
+  E extends string | undefined = any,
+  S extends Validator | undefined = any,
+> = E extends string
+  ? S extends Validator<infer V>
+    ? {
+        encoding: E
+        body: V
+      }
+    : {
+        encoding: E
+        body: LexBody<E>
+      }
+  : void
+
+export type PayloadBody<E extends string | undefined> = E extends undefined
+  ? undefined
+  : Validator | undefined
+
+export class Payload<
+  const Encoding extends string | undefined = string | undefined,
+  const Body extends PayloadBody<Encoding> = PayloadBody<Encoding>,
+> {
+  constructor(
+    readonly encoding: Encoding,
+    readonly schema: Body,
+  ) {
+    if (encoding === undefined && schema !== undefined) {
+      throw new TypeError('schema cannot be defined when encoding is undefined')
+    }
+  }
+}

package/src/schema/permission-set.ts

@@ -0,0 +1,22 @@
+import { Permission } from './permission.js'
+
+export type PermissionSetOptions = {
+  title?: string
+  'title:lang'?: Record<string, undefined | string>
+  detail?: string
+  'detail:lang'?: Record<string, undefined | string>
+}
+
+export class PermissionSet<
+  const Nsid extends string = any,
+  const Permissions extends readonly Permission[] = any,
+  const Options extends PermissionSetOptions = any,
+> {
+  readonly lexiconType = 'permission-set' as const
+
+  constructor(
+    readonly nsid: Nsid,
+    readonly permissions: Permissions,
+    readonly options: Options,
+  ) {}
+}

package/src/schema/permission.ts

@@ -0,0 +1,15 @@
+import { Params } from './_parameters.js'
+
+export type PermissionOptions = Params
+
+export class Permission<
+  const Resource extends string = any,
+  const Options extends PermissionOptions = any,
+> {
+  readonly lexiconType = 'permission' as const
+
+  constructor(
+    readonly resource: Resource,
+    readonly options: Options,
+  ) {}
+}

package/src/schema/procedure.ts

@@ -0,0 +1,35 @@
+import { Nsid } from '../core.js'
+import { Infer } from '../validation.js'
+import { ParamsSchema } from './params.js'
+import { InferPayloadBody, Payload } from './payload.js'
+
+export type InferProcedureParameters<Q extends Procedure> =
+  Q extends Procedure<any, infer P extends ParamsSchema, any> ? Infer<P> : never
+
+export type InferProcedureInputBody<Q extends Procedure> =
+  Q extends Procedure<any, any, infer I extends Payload, any>
+    ? InferPayloadBody<I>
+    : never
+
+export type InferProcedureOutputBody<Q extends Procedure> =
+  Q extends Procedure<any, any, any, infer O extends Payload>
+    ? InferPayloadBody<O>
+    : never
+
+export class Procedure<
+  N extends Nsid = any,
+  P extends ParamsSchema = any,
+  I extends Payload = any,
+  O extends Payload = any,
+  E extends undefined | readonly string[] = any,
+> {
+  readonly lexiconType = 'procedure' as const
+
+  constructor(
+    readonly nsid: N,
+    readonly parameters: P,
+    readonly input: I,
+    readonly output: O,
+    readonly errors: E,
+  ) {}
+}

package/src/schema/query.ts

@@ -0,0 +1,28 @@
+import { Nsid } from '../core.js'
+import { Infer } from '../validation.js'
+import { ParamsSchema } from './params.js'
+import { InferPayloadBody, Payload } from './payload.js'
+
+export type InferQueryParameters<Q extends Query> =
+  Q extends Query<any, infer P extends ParamsSchema, any> ? Infer<P> : never
+
+export type InferQueryOutputBody<Q extends Query> =
+  Q extends Query<any, any, infer O extends Payload>
+    ? InferPayloadBody<O>
+    : never
+
+export class Query<
+  N extends Nsid = any,
+  P extends ParamsSchema = any,
+  O extends Payload = any,
+  E extends undefined | readonly string[] = any,
+> {
+  readonly lexiconType = 'query' as const
+
+  constructor(
+    readonly nsid: N,
+    readonly parameters: P,
+    readonly output: O,
+    readonly errors: E,
+  ) {}
+}

package/src/schema/record.ts

@@ -0,0 +1,106 @@
+import { Nsid, RecordKey, Simplify } from '../core.js'
+import {
+  Infer,
+  ValidationResult,
+  Validator,
+  ValidatorContext,
+} from '../validation.js'
+import { LiteralSchema } from './literal.js'
+import { StringSchema } from './string.js'
+
+export type InferRecordKey<R extends RecordSchema> =
+  R extends RecordSchema<infer K, any, any, any>
+    ? RecordKeySchemaOutput<K>
+    : never
+
+export class RecordSchema<
+  Key extends RecordKey = any,
+  Type extends Nsid = any,
+  Schema extends Validator<object> = any,
+  Output extends Infer<Schema> & { $type: Type } = Infer<Schema> & {
+    $type: Type
+  },
+> extends Validator<Output> {
+  readonly lexiconType = 'record' as const
+
+  keySchema: RecordKeySchema<Key>
+
+  constructor(
+    readonly key: Key,
+    readonly $type: Type,
+    readonly schema: Schema,
+  ) {
+    super()
+    this.keySchema = recordKey(key)
+  }
+
+  isTypeOf<X extends { $type?: unknown }>(
+    value: X,
+  ): value is X extends { $type: Type } ? X : never {
+    return value.$type === this.$type
+  }
+
+  build<X extends Omit<Output, '$type'>>(
+    input: X,
+  ): Simplify<Omit<X, '$type'> & { $type: Type }> {
+    return { ...input, $type: this.$type }
+  }
+
+  $isTypeOf<X extends { $type?: unknown }>(value: X) {
+    return this.isTypeOf<X>(value)
+  }
+
+  $build<X extends Omit<Output, '$type'>>(input: X) {
+    return this.build<X>(input)
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<Output> {
+    const result = ctx.validate(input, this.schema) as ValidationResult<Output>
+
+    if (!result.success) {
+      return result
+    }
+
+    if (this.$type !== result.value.$type) {
+      return ctx.issueInvalidPropertyValue(result.value, '$type', [this.$type])
+    }
+
+    return result
+  }
+}
+
+export type RecordKeySchemaOutput<Key extends RecordKey> = Key extends 'any'
+  ? string
+  : Key extends 'tid'
+    ? string
+    : Key extends 'nsid'
+      ? Nsid
+      : Key extends `literal:${infer L extends string}`
+        ? L
+        : never
+
+export type RecordKeySchema<Key extends RecordKey> = Validator<
+  RecordKeySchemaOutput<Key>
+>
+
+const keySchema = new StringSchema({ minLength: 1 })
+const tidSchema = new StringSchema({ format: 'tid' })
+const nsidSchema = new StringSchema({ format: 'nsid' })
+const selfLiteralSchema = new LiteralSchema('self')
+
+function recordKey<Key extends RecordKey>(key: Key): RecordKeySchema<Key> {
+  // @NOTE Use cached instances for common schemas
+  if (key === 'any') return keySchema as any
+  if (key === 'tid') return tidSchema as any
+  if (key === 'nsid') return nsidSchema as any
+  if (key.startsWith('literal:')) {
+    const value = key.slice(8) as RecordKeySchemaOutput<Key>
+    if (value === 'self') return selfLiteralSchema as any
+    return new LiteralSchema(value)
+  }
+
+  throw new Error(`Unsupported record key type: ${key}`)
+}

package/src/schema/ref.ts

@@ -0,0 +1,47 @@
+import { ValidationResult, Validator, ValidatorContext } from '../validation.js'
+
+export type RefSchemaGetter<V> = () => Validator<V>
+
+export class RefSchema<V = any> extends Validator<V> {
+  readonly lexiconType = 'ref' as const
+
+  #getter: RefSchemaGetter<V>
+
+  constructor(getter: RefSchemaGetter<V>) {
+    // @NOTE In order to avoid circular dependency issues, we don't resolve
+    // the schema here. Instead, we resolve it lazily when first accessed.
+
+    super()
+
+    this.#getter = getter
+  }
+
+  get schema(): Validator<V> {
+    const value = this.#getter.call(null)
+
+    // Prevents a getter from depending on itself recursively, also allows GC to
+    // clean up the getter function.
+    this.#getter = throwAlreadyCalled
+
+    // Disable the getter and cache the resolved schema on the instance
+    Object.defineProperty(this, 'schema', {
+      value,
+      writable: false,
+      enumerable: false,
+      configurable: true,
+    })
+
+    return value
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<V> {
+    return ctx.validate(input, this.schema)
+  }
+}
+
+function throwAlreadyCalled(): never {
+  throw new Error('RefSchema getter called multiple times')
+}