@atproto/lex-schema 0.0.0

package/src/schema/string.ts

@@ -0,0 +1,139 @@
+import { CID, graphemeLen, utf8Len } from '@atproto/lex-data'
+import {
+  InferStringFormat,
+  StringFormat,
+  UnknownString,
+  assertStringFormat,
+} from '../core.js'
+import { ValidationResult, Validator, ValidatorContext } from '../validation.js'
+import { TokenSchema } from './token.js'
+
+export type StringSchemaOptions = {
+  default?: string
+  knownValues?: readonly string[]
+  format?: StringFormat
+  minLength?: number
+  maxLength?: number
+  minGraphemes?: number
+  maxGraphemes?: number
+}
+
+export type StringSchemaOutput<Options> =
+  //
+  Options extends { format: infer F extends StringFormat }
+    ? InferStringFormat<F>
+    : Options extends { knownValues: readonly (infer K extends string)[] }
+      ? K | UnknownString
+      : string
+
+export class StringSchema<
+  const Options extends StringSchemaOptions = any,
+> extends Validator<StringSchemaOutput<Options>> {
+  readonly lexiconType = 'string' as const
+
+  constructor(readonly options: Options) {
+    super()
+  }
+
+  override validateInContext(
+    // @NOTE validation will be applied on the default value as well
+    input: unknown = this.options.default,
+    ctx: ValidatorContext,
+  ): ValidationResult<StringSchemaOutput<Options>> {
+    const { options } = this
+
+    const str = coerceToString(input)
+    if (str == null) {
+      return ctx.issueInvalidType(input, 'string')
+    }
+
+    let lazyUtf8Len: number
+
+    const { minLength } = options
+    if (minLength != null) {
+      if ((lazyUtf8Len ??= utf8Len(str)) < minLength) {
+        return ctx.issueTooSmall(str, 'string', minLength, lazyUtf8Len)
+      }
+    }
+
+    const { maxLength } = options
+    if (maxLength != null) {
+      // Optimization: we can avoid computing the UTF-8 length if the maximum
+      // possible length, in bytes, of the input JS string is smaller than the
+      // maxLength (in UTF-8 string bytes).
+      if (str.length * 3 <= maxLength) {
+        // Input string so small it can't possibly exceed maxLength
+      } else if ((lazyUtf8Len ??= utf8Len(str)) > maxLength) {
+        return ctx.issueTooBig(str, 'string', maxLength, lazyUtf8Len)
+      }
+    }
+
+    let lazyGraphLen: number
+
+    const { minGraphemes } = options
+    if (minGraphemes != null) {
+      // Optimization: avoid counting graphemes if the length check already fails
+      if (str.length < minGraphemes) {
+        return ctx.issueTooSmall(str, 'grapheme', minGraphemes, str.length)
+      } else if ((lazyGraphLen ??= graphemeLen(str)) < minGraphemes) {
+        return ctx.issueTooSmall(str, 'grapheme', minGraphemes, lazyGraphLen)
+      }
+    }
+
+    const { maxGraphemes } = options
+    if (maxGraphemes != null) {
+      if ((lazyGraphLen ??= graphemeLen(str)) > maxGraphemes) {
+        return ctx.issueTooBig(str, 'grapheme', maxGraphemes, lazyGraphLen)
+      }
+    }
+
+    if (options.format !== undefined) {
+      try {
+        // @TODO optimize to avoid throw cost (requires re-writing utilities
+        // from @atproto/syntax)
+        assertStringFormat(str, options.format)
+      } catch (err) {
+        const message = err instanceof Error ? err.message : undefined
+        return ctx.issueInvalidFormat(str, options.format, message)
+      }
+    }
+
+    return ctx.success(str as StringSchemaOutput<Options>)
+  }
+}
+
+export function coerceToString(input: unknown): string | null {
+  switch (typeof input) {
+    case 'string':
+      return input
+    case 'object': {
+      if (input == null) return null
+
+      // @NOTE Allow using TokenSchema instances in places expecting strings,
+      // converting them to their string value.
+      if (input instanceof TokenSchema) {
+        return input.toString()
+      }
+
+      if (input instanceof Date) {
+        if (Number.isNaN(input.getTime())) return null
+        return input.toISOString()
+      }
+
+      if (input instanceof URL) {
+        return input.toString()
+      }
+
+      const cid = CID.asCID(input)
+      if (cid) return cid.toString()
+
+      if (input instanceof String) {
+        return input.valueOf()
+      }
+    }
+
+    // falls through
+    default:
+      return null
+  }
+}

package/src/schema/subscription.ts

@@ -0,0 +1,35 @@
+import { Infer } from '../validation.js'
+import { ObjectSchema } from './object.js'
+import { ParamsSchema } from './params.js'
+import { RefSchema } from './ref.js'
+import { TypedUnionSchema } from './typed-union.js'
+
+export type InferSubscriptionParameters<S extends Subscription> =
+  S extends Subscription<any, infer P extends ParamsSchema, any>
+    ? Infer<P>
+    : never
+
+export type InferSubscriptionMessage<S extends Subscription> =
+  S extends Subscription<
+    any,
+    any,
+    infer M extends RefSchema | TypedUnionSchema | ObjectSchema
+  >
+    ? Infer<M>
+    : unknown
+
+export class Subscription<
+  N extends string = any,
+  P extends ParamsSchema = any,
+  M extends undefined | RefSchema | TypedUnionSchema | ObjectSchema = any,
+  E extends undefined | readonly string[] = any,
+> {
+  readonly type = 'subscription' as const
+
+  constructor(
+    readonly nsid: N,
+    readonly parameters: P,
+    readonly message: M,
+    readonly errors: E,
+  ) {}
+}

package/src/schema/token.ts

@@ -0,0 +1,41 @@
+import { ValidationResult, Validator, ValidatorContext } from '../validation.js'
+
+export class TokenSchema<V extends string = any> extends Validator<V> {
+  readonly lexiconType = 'token' as const
+
+  constructor(protected readonly value: V) {
+    super()
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<V> {
+    if (input === this.value) {
+      return ctx.success(this.value)
+    }
+
+    // @NOTE: allow using the token instance itself (but convert to the actual
+    // token value)
+    if (input instanceof TokenSchema && input.value === this.value) {
+      return ctx.success(this.value)
+    }
+
+    if (typeof input !== 'string') {
+      return ctx.issueInvalidType(input, 'token')
+    }
+
+    return ctx.issueInvalidValue(input, [this.value])
+  }
+
+  // When using the TokenSchema instance as data, let's serialize it to the
+  // token value
+
+  toJSON(): string {
+    return this.value
+  }
+
+  toString(): string {
+    return this.value
+  }
+}

package/src/schema/typed-object.ts

@@ -0,0 +1,64 @@
+import { isPlainObject } from '@atproto/lex-data'
+import { $Type, Simplify } from '../core.js'
+import {
+  Infer,
+  ValidationResult,
+  Validator,
+  ValidatorContext,
+} from '../validation.js'
+
+export class TypedObjectSchema<
+  Type extends $Type = any,
+  Schema extends Validator<Record<string, unknown>> = any,
+  Output extends Infer<Schema> & { $type?: Type } = Infer<Schema> & {
+    $type?: Type
+  },
+> extends Validator<Output> {
+  readonly lexiconType = 'object' as const
+
+  constructor(
+    readonly $type: Type,
+    readonly schema: Schema,
+  ) {
+    super()
+  }
+
+  isTypeOf<X extends { $type?: unknown }>(
+    value: X,
+  ): value is X extends { $type?: Type } ? X : never {
+    return value.$type === undefined || 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> {
+    if (!isPlainObject(input)) {
+      return ctx.issueInvalidType(input, 'object')
+    }
+
+    if (
+      '$type' in input &&
+      input.$type !== undefined &&
+      input.$type !== this.$type
+    ) {
+      return ctx.issueInvalidPropertyValue(input, '$type', [this.$type])
+    }
+
+    return ctx.validate(input, this.schema as Validator<Output>)
+  }
+}

package/src/schema/typed-ref.ts

@@ -0,0 +1,68 @@
+import { ValidationResult, Validator, ValidatorContext } from '../validation.js'
+
+// Basically a RecordSchema or TypedObjectSchema
+export type TypedRefSchemaValidator<V extends { $type?: string } = any> =
+  V extends { $type?: infer T extends string }
+    ? { $type: T } & Validator<V & { $type?: T }>
+    : never
+
+export type TypedRefGetter<V extends { $type?: string } = any> =
+  () => TypedRefSchemaValidator<V>
+
+export type TypedRefSchemaOutput<V extends { $type?: string } = any> =
+  V extends { $type?: infer T extends string } ? V & { $type: T } : never
+
+export class TypedRefSchema<
+  V extends { $type?: string } = any,
+> extends Validator<TypedRefSchemaOutput<V>> {
+  #getter: TypedRefGetter<V>
+
+  constructor(getter: TypedRefGetter<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(): TypedRefSchemaValidator<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
+
+    // Cache the resolved schema on the instance
+    Object.defineProperty(this, 'schema', {
+      value,
+      writable: false,
+      enumerable: false,
+      configurable: true,
+    })
+
+    return value
+  }
+
+  get $type(): TypedRefSchemaOutput<V>['$type'] {
+    return this.schema.$type
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<TypedRefSchemaOutput<V>> {
+    const result = ctx.validate(input, this.schema)
+    if (!result.success) return result
+
+    if (result.value.$type !== this.$type) {
+      return ctx.issueInvalidPropertyValue(result.value, '$type', [this.$type])
+    }
+
+    return result as ValidationResult<TypedRefSchemaOutput<V>>
+  }
+}
+
+function throwAlreadyCalled(): never {
+  throw new Error('TypedRefSchema getter called multiple times')
+}

package/src/schema/typed-union.ts

@@ -0,0 +1,106 @@
+import { isPlainObject } from '@atproto/lex-data'
+import { Restricted, UnknownString } from '../core.js'
+import {
+  Infer,
+  ValidationResult,
+  Validator,
+  ValidatorContext,
+} from '../validation.js'
+import { TypedRefSchema, TypedRefSchemaOutput } from './typed-ref.js'
+
+export type TypedRef<T extends { $type?: string }> = TypedRefSchemaOutput<T>
+
+export type TypedObject = { $type: UnknownString } & {
+  // In order to prevent places that expect an open union from accepting an
+  // invalid version of the known typed objects, we need to prevent any other
+  // properties from being present.
+  //
+  // For example, if an open union expects:
+  // ```ts
+  // TypedObject | { $type: 'A'; a: number }
+  // ```
+  // we don't want it to accept:
+  // ```ts
+  // { $type: 'A' }
+  // ```
+  // Which would be the case as `{ $type: 'A' }` is a valid
+  // `TypedObject`. By adding an index signature that forbids any
+  // property, we ensure that only valid known typed objects can be used.
+  [K in string]: Restricted<'Unknown property'>
+}
+
+type TypedRefSchemasToUnion<T extends readonly TypedRefSchema[]> = {
+  [K in keyof T]: Infer<T[K]>
+}[number]
+
+export type TypedUnionSchemaOutput<
+  TypedRefs extends readonly TypedRefSchema[],
+  Closed extends boolean,
+> = Closed extends true
+  ? TypedRefSchemasToUnion<TypedRefs>
+  : TypedRefSchemasToUnion<TypedRefs> | TypedObject
+
+export class TypedUnionSchema<
+  TypedRefs extends readonly TypedRefSchema[] = any,
+  Closed extends boolean = any,
+> extends Validator<TypedUnionSchemaOutput<TypedRefs, Closed>> {
+  readonly lexiconType = 'union' as const
+
+  constructor(
+    protected readonly refs: TypedRefs,
+    public readonly closed: Closed,
+  ) {
+    // @NOTE In order to avoid circular dependency issues, we don't access the
+    // refs's schema (or $type) here. Instead, we access them lazily when first
+    // needed.
+
+    super()
+  }
+
+  protected get refsMap() {
+    const map = new Map<unknown, TypedRefs[number]>()
+    for (const ref of this.refs) map.set(ref.$type, ref)
+
+    // Cache the map on the instance
+    Object.defineProperty(this, 'refsMap', {
+      value: map,
+      writable: false,
+      enumerable: false,
+      configurable: true,
+    })
+
+    return map
+  }
+
+  get $types() {
+    return Array.from(this.refsMap.keys())
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<TypedUnionSchemaOutput<TypedRefs, Closed>> {
+    if (!isPlainObject(input) || !('$type' in input)) {
+      return ctx.issueInvalidType(input, '$typed')
+    }
+
+    const { $type } = input
+
+    const def = this.refsMap.get($type)
+    if (def) {
+      const result = ctx.validate(input, def)
+      return result as ValidationResult<
+        TypedUnionSchemaOutput<TypedRefs, Closed>
+      >
+    }
+
+    if (this.closed) {
+      return ctx.issueInvalidPropertyValue(input, '$type', this.$types)
+    }
+    if (typeof $type !== 'string') {
+      return ctx.issueInvalidPropertyType(input, '$type', 'string')
+    }
+
+    return ctx.success(input as TypedUnionSchemaOutput<TypedRefs, Closed>)
+  }
+}

package/src/schema/union.ts

@@ -0,0 +1,40 @@
+import {
+  Infer,
+  ValidationError,
+  ValidationFailure,
+  ValidationResult,
+  Validator,
+  ValidatorContext,
+} from '../validation.js'
+
+export type UnionSchemaValidators = readonly [Validator, ...Validator[]]
+export type UnionSchemaOutput<V extends readonly Validator[]> = Infer<V[number]>
+
+export class UnionSchema<
+  V extends UnionSchemaValidators = any,
+> extends Validator<UnionSchemaOutput<V>> {
+  constructor(protected readonly validators: V) {
+    super()
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<UnionSchemaOutput<V>> {
+    const failures: ValidationFailure[] = []
+
+    for (const validator of this.validators) {
+      const result = ctx.validate(input, validator)
+      if (result.success) {
+        return result as ValidationResult<UnionSchemaOutput<V>>
+      } else {
+        failures.push(result)
+      }
+    }
+
+    return {
+      success: false,
+      error: ValidationError.fromFailures(failures),
+    }
+  }
+}

package/src/schema/unknown-object.ts

@@ -0,0 +1,20 @@
+import { LexMap, isLexMap } from '@atproto/lex-data'
+import { ValidationResult, Validator, ValidatorContext } from '../validation'
+
+export type { LexMap }
+export type UnknownObjectOutput = LexMap
+
+export class UnknownObjectSchema extends Validator<UnknownObjectOutput> {
+  readonly lexiconType = 'unknown' as const
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<UnknownObjectOutput> {
+    if (isLexMap(input)) {
+      return ctx.success(input)
+    }
+
+    return ctx.issueInvalidType(input, 'unknown')
+  }
+}

package/src/schema/unknown.ts

@@ -0,0 +1,10 @@
+import { ValidationResult, Validator, ValidatorContext } from '../validation'
+
+export class UnknownSchema extends Validator<unknown> {
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<unknown> {
+    return ctx.success(input)
+  }
+}

package/src/schema.ts

@@ -0,0 +1,40 @@
+// Utilities (that depend on *and* are used by schemas)
+export * from './schema/_parameters.js'
+
+// Concrete Types
+export * from './schema/array.js'
+export * from './schema/blob.js'
+export * from './schema/boolean.js'
+export * from './schema/bytes.js'
+export * from './schema/cid.js'
+export * from './schema/dict.js'
+export * from './schema/enum.js'
+export * from './schema/integer.js'
+export * from './schema/literal.js'
+export * from './schema/never.js'
+export * from './schema/null.js'
+export * from './schema/object.js'
+export * from './schema/string.js'
+export * from './schema/unknown-object.js'
+export * from './schema/unknown.js'
+
+// Composite Types
+export * from './schema/custom.js'
+export * from './schema/discriminated-union.js'
+export * from './schema/intersection.js'
+export * from './schema/ref.js'
+export * from './schema/union.js'
+
+// Lexicon specific Types
+export * from './schema/params.js'
+export * from './schema/payload.js'
+export * from './schema/permission-set.js'
+export * from './schema/permission.js'
+export * from './schema/procedure.js'
+export * from './schema/query.js'
+export * from './schema/record.js'
+export * from './schema/subscription.js'
+export * from './schema/token.js'
+export * from './schema/typed-object.js'
+export * from './schema/typed-ref.js'
+export * from './schema/typed-union.js'

package/src/util/array-agg.test.ts

@@ -0,0 +1,41 @@
+import { arrayAgg } from './array-agg.js'
+
+describe('arrayAgg', () => {
+  it('aggregates items based on comparison and aggregation functions', () => {
+    const input = [1, 1, 2, 2, 3, 3, 3]
+    const result = arrayAgg(
+      input,
+      (a, b) => a === b,
+      (items) => ({ value: items[0], count: items.length }),
+    )
+    expect(result).toEqual([
+      { value: 1, count: 2 },
+      { value: 2, count: 2 },
+      { value: 3, count: 3 },
+    ])
+  })
+
+  it('returns an empty array when input is empty', () => {
+    const input: number[] = []
+    const result = arrayAgg(
+      input,
+      (a, b) => a === b,
+      (items) => ({ value: items[0], count: items.length }),
+    )
+    expect(result).toEqual([])
+  })
+
+  it('handles non-consecutive grouping', () => {
+    const input = [1, 2, 1, 2, 3, 1]
+    const result = arrayAgg(
+      input,
+      (a, b) => a === b,
+      (items) => ({ value: items[0], count: items.length }),
+    )
+    expect(result).toEqual([
+      { value: 1, count: 3 },
+      { value: 2, count: 2 },
+      { value: 3, count: 1 },
+    ])
+  })
+})

package/src/util/array-agg.ts

@@ -0,0 +1,43 @@
+/**
+ * Aggregates items in an array based on a comparison function and an aggregation function.
+ *
+ * @param arr - The input array to aggregate.
+ * @param cmp - A comparison function that determines if two items belong to the same group.
+ * @param agg - An aggregation function that combines items in a group into a single item.
+ * @returns An array of aggregated items.
+ * @example
+ * ```ts
+ * const input = [1, 1, 2, 2, 3, 3, 3]
+ * const result = arrayAgg(
+ *   input,
+ *   (a, b) => a === b,
+ *   (items) => { value: items[0], sum: items.reduce((sum, item) => sum + item, 0) },
+ * )
+ * // result is [{ value: 1, sum: 2 }, { value: 2, sum: 4 }, { value: 3, sum: 6 }]
+ * ```
+ */
+export function arrayAgg<T, O>(
+  arr: readonly T[],
+  cmp: (a: T, b: T) => boolean,
+  agg: (items: [T, ...T[]]) => O,
+): O[] {
+  if (arr.length === 0) return []
+
+  const groups: [T, ...T[]][] = [[arr[0]]]
+  const skipped = Array<undefined | boolean>(arr.length)
+
+  outer: for (let i = 1; i < arr.length; i++) {
+    if (skipped[i]) continue
+    const item = arr[i]
+    for (let j = 0; j < groups.length; j++) {
+      if (cmp(item, groups[j][0])) {
+        groups[j].push(item)
+        skipped[i] = true
+        continue outer
+      }
+    }
+    groups.push([item])
+  }
+
+  return groups.map(agg)
+}

package/src/validation/property-key.ts

@@ -0,0 +1 @@
+export type PropertyKey = string | number

package/src/validation/validation-error.ts

@@ -0,0 +1,32 @@
+import { ResultFailure, failureError } from '../core.js'
+import {
+  ValidationIssue,
+  aggregateIssues,
+  stringifyIssue,
+} from './validation-issue.js'
+
+export class ValidationError extends Error {
+  name = 'ValidationError'
+
+  constructor(
+    readonly issues: ValidationIssue[],
+    options?: ErrorOptions,
+  ) {
+    super(issues.map(stringifyIssue).join(', '), options)
+  }
+
+  static fromFailures(
+    failures: ResultFailure<ValidationError>[],
+  ): ValidationError {
+    if (failures.length === 1) return failures[0].error
+    const issues = failures.flatMap(extractFailureIssues)
+    return new ValidationError(aggregateIssues(issues), {
+      // Keep the original errors as the cause chain
+      cause: failures.map(failureError),
+    })
+  }
+}
+
+function extractFailureIssues(result: ResultFailure<ValidationError>) {
+  return result.error.issues
+}