@atproto/lex-schema 0.0.0

package/src/core/string-format.ts

@@ -0,0 +1,124 @@
+import { ensureValidCidString, isLanguage } from '@atproto/lex-data'
+import {
+  ensureValidAtUri,
+  ensureValidDatetime,
+  ensureValidDid,
+  ensureValidHandle,
+  ensureValidNsid,
+  ensureValidRecordKey,
+  ensureValidTid,
+} from '@atproto/syntax'
+
+// Allow (date as Date).toISOString() to be used where datetime format is expected
+declare global {
+  interface Date {
+    toISOString(): `${string}T${string}Z`
+  }
+}
+
+export const STRING_FORMATS = Object.freeze([
+  'datetime',
+  'uri',
+  'at-uri',
+  'did',
+  'handle',
+  'at-identifier',
+  'nsid',
+  'cid',
+  'language',
+  'tid',
+  'record-key',
+] as const)
+
+export type StringFormat = (typeof STRING_FORMATS)[number]
+
+export type Did<M extends string = string> = `did:${M}:${string}`
+export type Uri = `${string}:${string}`
+export type Nsid = `${string}.${string}.${string}`
+/** An ISO 8601 formatted datetime string (YYYY-MM-DDTHH:mm:ss.sssZ) */
+export type Datetime = `${string}T${string}`
+export type Handle = `${string}.${string}`
+export type AtIdentifier = Did | Handle
+export type AtUri = `at://${AtIdentifier}/${Nsid}/${string}`
+
+export type InferStringFormat<F> =
+  //
+  F extends 'datetime'
+    ? Datetime
+    : F extends 'uri'
+      ? Uri
+      : F extends 'at-uri'
+        ? AtUri
+        : F extends 'did'
+          ? Did
+          : F extends 'handle'
+            ? Handle
+            : F extends 'at-identifier'
+              ? AtIdentifier
+              : F extends 'nsid'
+                ? Nsid
+                : string
+
+type AssertFn<T> = <I extends string>(input: I) => asserts input is I & T
+
+// Re-export utility typed as assertion functions so that TypeScript can
+// infer the narrowed type after calling them.
+
+export const assertDid: AssertFn<Did> = ensureValidDid
+export const assertAtUri: AssertFn<AtUri> = ensureValidAtUri
+export const assertNsid: AssertFn<Nsid> = ensureValidNsid
+export const assertTid: AssertFn<string> = ensureValidTid
+export const assertRecordKey: AssertFn<string> = ensureValidRecordKey
+export const assertDatetime: AssertFn<Datetime> = ensureValidDatetime
+export const assertCidString: AssertFn<string> = ensureValidCidString
+export const assertHandle: AssertFn<Handle> = ensureValidHandle
+
+// Export utilities for formats missing from @atproto/syntax
+
+export const assertUri: AssertFn<Uri> = (input) => {
+  if (!/^\w+:(?:\/\/)?[^\s/][^\s]*$/.test(input)) {
+    throw new Error('Invalid URI')
+  }
+}
+export const assertLanguage: AssertFn<string> = (input) => {
+  if (!isLanguage(input)) {
+    throw new Error('Invalid BCP 47 string')
+  }
+}
+export const assertAtIdentifier: AssertFn<AtIdentifier> = (input) => {
+  if (input.startsWith('did:web:') || input.startsWith('did:plc:')) {
+    assertDid(input)
+  } else if (input.startsWith('did:')) {
+    throw new Error('Invalid DID method')
+  } else {
+    try {
+      assertHandle(input)
+    } catch (cause) {
+      throw new Error('Invalid DID or handle', { cause })
+    }
+  }
+}
+
+const formatters = /*#__PURE__*/ new Map<StringFormat, (str: string) => void>([
+  ['datetime', assertDatetime],
+  ['uri', assertUri],
+  ['at-uri', assertAtUri],
+  ['did', assertDid],
+  ['handle', assertHandle],
+  ['at-identifier', assertAtIdentifier],
+  ['nsid', assertNsid],
+  ['cid', assertCidString],
+  ['language', assertLanguage],
+  ['tid', assertTid],
+  ['record-key', assertRecordKey],
+] as const)
+
+export function assertStringFormat<F extends StringFormat>(
+  input: string,
+  format: F,
+): asserts input is InferStringFormat<F> {
+  const assertFn = formatters.get(format)
+  if (assertFn) assertFn(input)
+  // Fool-proof
+  else throw new Error(`Unknown string format: ${format}`)
+}

package/src/core/types.ts

@@ -0,0 +1,22 @@
+/**
+ * Same as {@link string} but prevents TypeScript allowing union types to
+ * be widened to `string` in IDEs.
+ */
+export type UnknownString = string & NonNullable<unknown>
+
+export type Simplify<T> = { [K in keyof T]: T[K] } & NonNullable<unknown>
+
+// @NOTE there is no way to express "array containing at least one P", so we use
+// "array that contains P at first or last position" as a workaround.
+export type ArrayContaining<T, Items = unknown> =
+  | readonly [T, ...Items[]]
+  | readonly [...Items[], T]
+
+declare const __restricted: unique symbol
+/**
+ * A type that represents a value that cannot be used, with a custom
+ * message explaining the restriction.
+ */
+export type Restricted<Message extends string> = typeof __restricted & {
+  [__restricted]: Message
+}

package/src/core.ts

@@ -0,0 +1,5 @@
+export * from './core/$type.js'
+export * from './core/record-key.js'
+export * from './core/result.js'
+export * from './core/string-format.js'
+export * from './core/types.js'

package/src/external.ts

@@ -0,0 +1,365 @@
+import { $Type, $type, Nsid, RecordKey } from './core.js'
+import {
+  ArraySchema,
+  ArraySchemaOptions,
+  BlobSchema,
+  BlobSchemaOptions,
+  BooleanSchema,
+  BooleanSchemaOptions,
+  BytesSchema,
+  BytesSchemaOptions,
+  CidSchema,
+  CustomAssertion,
+  CustomSchema,
+  DictSchema,
+  DiscriminatedUnionSchema,
+  DiscriminatedUnionSchemaVariants,
+  EnumSchema,
+  IntegerSchema,
+  IntegerSchemaOptions,
+  IntersectionSchema,
+  IntersectionSchemaValidators,
+  LiteralSchema,
+  NeverSchema,
+  NullSchema,
+  ObjectSchema,
+  ObjectSchemaOptions,
+  ObjectSchemaProperties,
+  ParamsSchema,
+  ParamsSchemaOptions,
+  ParamsSchemaProperties,
+  Payload,
+  PayloadBody,
+  Permission,
+  PermissionOptions,
+  PermissionSet,
+  PermissionSetOptions,
+  Procedure,
+  Query,
+  RecordSchema,
+  RefSchema,
+  RefSchemaGetter,
+  StringSchema,
+  StringSchemaOptions,
+  Subscription,
+  TokenSchema,
+  TypedObjectSchema,
+  TypedRefGetter,
+  TypedRefSchema,
+  TypedUnionSchema,
+  UnionSchema,
+  UnionSchemaValidators,
+  UnknownObjectOutput,
+  UnknownObjectSchema,
+  UnknownSchema,
+} from './schema.js'
+import { Infer, PropertyKey, Validator } from './validation.js'
+
+export * from './core.js'
+export * from './schema.js'
+export * from './validation.js'
+
+/*@__NO_SIDE_EFFECTS__*/
+export function never() {
+  return new NeverSchema()
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function unknown() {
+  return new UnknownSchema()
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function _null() {
+  return new NullSchema()
+}
+
+export { _null as null }
+
+/*@__NO_SIDE_EFFECTS__*/
+export function literal<const V extends null | string | number | boolean>(
+  value: V,
+) {
+  return new LiteralSchema<V>(value)
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function _enum<const V extends null | string | number | boolean>(
+  value: readonly V[],
+) {
+  return new EnumSchema<V>(value)
+}
+
+// @NOTE "enum" is a reserved keyword in JS/TS
+export { _enum as enum }
+
+/*@__NO_SIDE_EFFECTS__*/
+export function boolean(options: BooleanSchemaOptions = {}) {
+  return new BooleanSchema(options)
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function integer(options: IntegerSchemaOptions = {}) {
+  return new IntegerSchema(options)
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function cidLink() {
+  return new CidSchema()
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function bytes(options: BytesSchemaOptions = {}) {
+  return new BytesSchema(options)
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function blob(options: BlobSchemaOptions = {}) {
+  return new BlobSchema(options)
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function string<
+  const O extends StringSchemaOptions = NonNullable<unknown>,
+>(options: StringSchemaOptions & O = {} as O) {
+  return new StringSchema<O>(options)
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function array<const T>(
+  items: Validator<T>,
+  options: ArraySchemaOptions = {},
+) {
+  return new ArraySchema(items, options)
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function object<
+  const P extends ObjectSchemaProperties,
+  const O extends ObjectSchemaOptions = NonNullable<unknown>,
+>(
+  properties: ObjectSchemaProperties & P,
+  options: ObjectSchemaOptions & O = {} as O,
+) {
+  return new ObjectSchema<P, O>(properties, options)
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function dict<const K extends Validator, const V extends Validator>(
+  key: K,
+  value: V,
+) {
+  return new DictSchema<K, V>(key, value)
+}
+
+// Utility
+export type { UnknownObjectOutput as UnknownObject }
+
+/*@__NO_SIDE_EFFECTS__*/
+export function unknownObject() {
+  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)
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function union<const V extends UnionSchemaValidators>(validators: V) {
+  return new UnionSchema<V>(validators)
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function intersection<const V extends IntersectionSchemaValidators>(
+  validators: V,
+) {
+  return new IntersectionSchema<V>(validators)
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function discriminatedUnion<
+  const Discriminator extends string,
+  const Options extends DiscriminatedUnionSchemaVariants<Discriminator>,
+>(discriminator: Discriminator, variants: Options) {
+  return new DiscriminatedUnionSchema<Discriminator, Options>(
+    discriminator,
+    variants,
+  )
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function token<const N extends Nsid, 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 Nsid,
+  const H extends string,
+  const Schema extends Validator<{ [_ in string]?: unknown }>,
+>(nsid: N, hash: H, schema: Schema): TypedObjectSchema<$Type<N, H>, Schema>
+export function typedObject<const 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<NonNullable<V['$type']>, typeof schema, V>
+/*@__NO_SIDE_EFFECTS__*/
+export function typedObject<
+  const N extends Nsid,
+  const H extends string,
+  const Schema extends Validator<{ [_ in string]?: unknown }>,
+>(nsid: N, hash: H, schema: Schema) {
+  return new TypedObjectSchema<$Type<N, H>, Schema>($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 RecordKey,
+  const T extends Nsid,
+  const S extends Validator<{ [_ in string]?: unknown }>,
+>(
+  key: K,
+  type: AsNsid<T>,
+  schema: S,
+): RecordSchema<K, T, S, Infer<S> & { $type: T }>
+export function record<
+  const K extends RecordKey,
+  const V extends { $type: Nsid },
+>(
+  key: K,
+  type: AsNsid<V['$type']>,
+  schema: Validator<Omit<V, '$type'>>,
+): RecordSchema<K, V['$type'], typeof schema, V>
+/*@__NO_SIDE_EFFECTS__*/
+export function record<
+  const K extends RecordKey,
+  const T extends Nsid,
+  const S extends Validator<{ [_ in string]?: unknown }>,
+>(key: K, type: T, schema: S) {
+  return new RecordSchema<K, T, S, Infer<S> & { $type: T }>(key, type, schema)
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function params<
+  const P extends ParamsSchemaProperties = NonNullable<unknown>,
+  const O extends ParamsSchemaOptions = ParamsSchemaOptions,
+>(properties: P = {} as P, options: ParamsSchemaOptions & O = {} as O) {
+  return new ParamsSchema<P, O>(properties, options)
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function payload<
+  const E extends string | undefined = undefined,
+  const S extends PayloadBody<E> = undefined,
+>(encoding: E = undefined as E, schema: S = undefined as S) {
+  return new Payload<E, S>(encoding, schema)
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+export function query<
+  const N extends Nsid,
+  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 Nsid,
+  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 string,
+  const P extends ParamsSchema,
+  const M extends undefined | RefSchema | TypedUnionSchema | ObjectSchema,
+  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 string,
+  const P extends readonly Permission[],
+  const O extends PermissionSetOptions,
+>(nsid: N, permissions: P, options: PermissionSetOptions & O = {} as O) {
+  return new PermissionSet<N, P, O>(nsid, permissions, options)
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import * as l from './external.js'
+export * from './external.js'
+export { l }

package/src/schema/_parameters.ts

@@ -0,0 +1,26 @@
+import { Infer, Validator } from '../validation.js'
+import { ArraySchema } from './array.js'
+import { BooleanSchema } from './boolean.js'
+import { DictSchema } from './dict.js'
+import { IntegerSchema } from './integer.js'
+import { StringSchema } from './string.js'
+import { UnionSchema } from './union.js'
+
+export type ParamScalar = Infer<typeof paramScalarSchema>
+const paramScalarSchema = new UnionSchema([
+  new BooleanSchema({}),
+  new IntegerSchema({}),
+  new StringSchema({}),
+])
+
+export type Param = Infer<typeof paramSchema>
+export const paramSchema = new UnionSchema([
+  paramScalarSchema,
+  new ArraySchema(paramScalarSchema, {}),
+])
+
+export type Params = { [_: string]: undefined | Param }
+export const paramsSchema = new DictSchema(
+  new StringSchema({}),
+  paramSchema,
+) satisfies Validator<Params>

package/src/schema/array.ts

@@ -0,0 +1,51 @@
+import { ValidationResult, Validator, ValidatorContext } from '../validation.js'
+
+export type ArraySchemaOptions = {
+  minLength?: number
+  maxLength?: number
+}
+
+export class ArraySchema<Item = any> extends Validator<Array<Item>> {
+  readonly lexiconType = 'array' as const
+
+  constructor(
+    readonly items: Validator<Item>,
+    readonly options: ArraySchemaOptions,
+  ) {
+    super()
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<Array<Item>> {
+    if (!Array.isArray(input)) {
+      return ctx.issueInvalidType(input, 'array')
+    }
+
+    const { minLength, maxLength } = this.options
+
+    if (minLength != null && input.length < minLength) {
+      return ctx.issueTooSmall(input, 'array', minLength, input.length)
+    }
+
+    if (maxLength != null && input.length > maxLength) {
+      return ctx.issueTooBig(input, 'array', maxLength, input.length)
+    }
+
+    let copy: undefined | Array<Item>
+
+    for (let i = 0; i < input.length; i++) {
+      const result = ctx.validateChild(input, i, this.items)
+      if (!result.success) return result
+
+      if (result.value !== input[i]) {
+        // Copy on write (but only if we did not already make a copy)
+        copy ??= Array.from(input)
+        copy[i] = result.value
+      }
+    }
+
+    return ctx.success(copy ?? input) as ValidationResult<Array<Item>>
+  }
+}

package/src/schema/blob.ts

@@ -0,0 +1,82 @@
+import {
+  BlobRef,
+  LegacyBlobRef,
+  isBlobRef,
+  isLegacyBlobRef,
+} from '@atproto/lex-data'
+import { ValidationResult, Validator, ValidatorContext } from '../validation.js'
+
+export type BlobSchemaOptions = {
+  /**
+   * Whether to allow legacy blob references format
+   * @see {@link LegacyBlobRef}
+   */
+  allowLegacy?: boolean
+  /**
+   * Whether to enforce strict validation on the blob reference (CID version, codec, hash function)
+   */
+  strict?: boolean
+  /**
+   * List of accepted mime types
+   */
+  accept?: string[]
+  /**
+   * Maximum size in bytes
+   */
+  maxSize?: number
+}
+
+export type { BlobRef, LegacyBlobRef }
+
+export type BlobSchemaOutput<Options> = Options extends { allowLegacy: true }
+  ? BlobRef | LegacyBlobRef
+  : BlobRef
+
+export class BlobSchema<O extends BlobSchemaOptions> extends Validator<
+  BlobSchemaOutput<O>
+> {
+  readonly lexiconType = 'blob' as const
+
+  constructor(readonly options: O) {
+    super()
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<BlobSchemaOutput<O>> {
+    if (!isBlob(input, this.options)) {
+      return ctx.issueInvalidType(input, 'blob')
+    }
+
+    // @NOTE Historically, we did not enforce constraints on blob references
+    // https://github.com/bluesky-social/atproto/blob/4c15fb47cec26060bff2e710e95869a90c9d7fdd/packages/lexicon/src/validators/blob.ts#L5-L19
+
+    // const { accept } = this.options
+    // if (accept && !accept.includes(input.mimeType)) {
+    //   return ctx.issueInvalidValue(input, accept)
+    // }
+
+    // const { maxSize } = this.options
+    // if (maxSize != null && input.size != -1 && input.size > maxSize) {
+    //   return ctx.issueTooBig(input, 'blob', maxSize, input.size)
+    // }
+
+    return ctx.success(input)
+  }
+}
+
+function isBlob<O extends BlobSchemaOptions>(
+  input: unknown,
+  options: O,
+): input is BlobSchemaOutput<O> {
+  if ((input as any)?.$type !== undefined) {
+    return isBlobRef(input, options)
+  }
+
+  if (options.allowLegacy === true) {
+    return isLegacyBlobRef(input)
+  }
+
+  return false
+}

package/src/schema/boolean.ts

@@ -0,0 +1,24 @@
+import { ValidationResult, Validator, ValidatorContext } from '../validation.js'
+
+export type BooleanSchemaOptions = {
+  default?: boolean
+}
+
+export class BooleanSchema extends Validator<boolean> {
+  readonly lexiconType = 'boolean' as const
+
+  constructor(readonly options: BooleanSchemaOptions) {
+    super()
+  }
+
+  override validateInContext(
+    input: unknown = this.options.default,
+    ctx: ValidatorContext,
+  ): ValidationResult<boolean> {
+    if (typeof input === 'boolean') {
+      return ctx.success(input)
+    }
+
+    return ctx.issueInvalidType(input, 'boolean')
+  }
+}