@atproto/lexicon 0.0.1

package/src/types.ts

@@ -0,0 +1,318 @@
+import { z } from 'zod'
+import { NSID } from '@atproto/nsid'
+
+// primitives
+// =
+
+export const lexBoolean = z.object({
+  type: z.literal('boolean'),
+  description: z.string().optional(),
+  default: z.boolean().optional(),
+  const: z.boolean().optional(),
+})
+export type LexBoolean = z.infer<typeof lexBoolean>
+
+export const lexNumber = z.object({
+  type: z.literal('number'),
+  description: z.string().optional(),
+  default: z.number().optional(),
+  minimum: z.number().optional(),
+  maximum: z.number().optional(),
+  enum: z.number().array().optional(),
+  const: z.number().optional(),
+})
+export type LexNumber = z.infer<typeof lexNumber>
+
+export const lexInteger = z.object({
+  type: z.literal('integer'),
+  description: z.string().optional(),
+  default: z.number().int().optional(),
+  minimum: z.number().int().optional(),
+  maximum: z.number().int().optional(),
+  enum: z.number().int().array().optional(),
+  const: z.number().int().optional(),
+})
+export type LexInteger = z.infer<typeof lexInteger>
+
+export const lexString = z.object({
+  type: z.literal('string'),
+  description: z.string().optional(),
+  default: z.string().optional(),
+  minLength: z.number().int().optional(),
+  maxLength: z.number().int().optional(),
+  enum: z.string().array().optional(),
+  const: z.string().optional(),
+  knownValues: z.string().array().optional(),
+})
+export type LexString = z.infer<typeof lexString>
+
+export const lexDatetime = z.object({
+  type: z.literal('datetime'),
+  description: z.string().optional(),
+})
+export type LexDatetime = z.infer<typeof lexDatetime>
+
+export const lexUnknown = z.object({
+  type: z.literal('unknown'),
+  description: z.string().optional(),
+})
+export type LexUnknown = z.infer<typeof lexUnknown>
+
+export const lexPrimitive = z.union([
+  lexBoolean,
+  lexNumber,
+  lexInteger,
+  lexString,
+  lexDatetime,
+  lexUnknown,
+])
+export type LexPrimitive = z.infer<typeof lexPrimitive>
+
+// references
+// =
+
+export const lexRef = z.object({
+  type: z.literal('ref'),
+  description: z.string().optional(),
+  ref: z.string(),
+})
+export type LexRef = z.infer<typeof lexRef>
+
+export const lexRefUnion = z.object({
+  type: z.literal('union'),
+  description: z.string().optional(),
+  refs: z.string().array(),
+  closed: z.boolean().optional(),
+})
+export type LexRefUnion = z.infer<typeof lexRefUnion>
+
+export const lexRefVariant = z.union([lexRef, lexRefUnion])
+export type LexRefVariant = z.infer<typeof lexRefVariant>
+
+// blobs
+// =
+
+export const lexBlob = z.object({
+  type: z.literal('blob'),
+  description: z.string().optional(),
+  accept: z.string().array().optional(),
+  maxSize: z.number().optional(),
+})
+export type LexBlob = z.infer<typeof lexBlob>
+
+export const lexImage = z.object({
+  type: z.literal('image'),
+  description: z.string().optional(),
+  accept: z.string().array().optional(),
+  maxSize: z.number().optional(),
+  maxWidth: z.number().int().optional(),
+  maxHeight: z.number().int().optional(),
+})
+export type LexImage = z.infer<typeof lexImage>
+
+export const lexVideo = z.object({
+  type: z.literal('video'),
+  description: z.string().optional(),
+  accept: z.string().array().optional(),
+  maxSize: z.number().optional(),
+  maxWidth: z.number().int().optional(),
+  maxHeight: z.number().int().optional(),
+  maxLength: z.number().int().optional(),
+})
+export type LexVideo = z.infer<typeof lexVideo>
+
+export const lexAudio = z.object({
+  type: z.literal('audio'),
+  description: z.string().optional(),
+  accept: z.string().array().optional(),
+  maxSize: z.number().optional(),
+  maxLength: z.number().int().optional(),
+})
+export type LexAudio = z.infer<typeof lexAudio>
+
+export const lexBlobVariant = z.union([lexBlob, lexImage, lexVideo, lexAudio])
+export type LexBlobVariant = z.infer<typeof lexBlobVariant>
+
+// complex types
+// =
+
+export const lexArray = z.object({
+  type: z.literal('array'),
+  description: z.string().optional(),
+  items: z.union([lexPrimitive, lexBlobVariant, lexRefVariant]),
+  minLength: z.number().int().optional(),
+  maxLength: z.number().int().optional(),
+})
+export type LexArray = z.infer<typeof lexArray>
+
+export const lexToken = z.object({
+  type: z.literal('token'),
+  description: z.string().optional(),
+})
+export type LexToken = z.infer<typeof lexToken>
+
+export const lexObject = z.object({
+  type: z.literal('object'),
+  description: z.string().optional(),
+  required: z.string().array().optional(),
+  properties: z
+    .record(z.union([lexRefVariant, lexArray, lexBlobVariant, lexPrimitive]))
+    .optional(),
+})
+export type LexObject = z.infer<typeof lexObject>
+
+// xrpc
+// =
+
+export const lexXrpcParameters = z.object({
+  type: z.literal('params'),
+  description: z.string().optional(),
+  required: z.string().array().optional(),
+  properties: z.record(lexPrimitive),
+})
+export type LexXrpcParameters = z.infer<typeof lexXrpcParameters>
+
+export const lexXrpcBody = z.object({
+  description: z.string().optional(),
+  encoding: z.string(),
+  schema: z.union([lexRefVariant, lexObject]).optional(),
+})
+export type LexXrpcBody = z.infer<typeof lexXrpcBody>
+
+export const lexXrpcError = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+})
+export type LexXrpcError = z.infer<typeof lexXrpcError>
+
+export const lexXrpcQuery = z.object({
+  type: z.literal('query'),
+  description: z.string().optional(),
+  parameters: lexXrpcParameters.optional(),
+  output: lexXrpcBody.optional(),
+  errors: lexXrpcError.array().optional(),
+})
+export type LexXrpcQuery = z.infer<typeof lexXrpcQuery>
+
+export const lexXrpcProcedure = z.object({
+  type: z.literal('procedure'),
+  description: z.string().optional(),
+  parameters: lexXrpcParameters.optional(),
+  input: lexXrpcBody.optional(),
+  output: lexXrpcBody.optional(),
+  errors: lexXrpcError.array().optional(),
+})
+export type LexXrpcProcedure = z.infer<typeof lexXrpcProcedure>
+
+// database
+// =
+
+export const lexRecord = z.object({
+  type: z.literal('record'),
+  description: z.string().optional(),
+  key: z.string().optional(),
+  record: lexObject,
+})
+export type LexRecord = z.infer<typeof lexRecord>
+
+// core
+// =
+
+export const lexUserType = z.union([
+  lexRecord,
+
+  lexXrpcQuery,
+  lexXrpcProcedure,
+
+  lexBlob,
+  lexImage,
+  lexVideo,
+  lexAudio,
+
+  lexArray,
+  lexToken,
+  lexObject,
+
+  lexBoolean,
+  lexNumber,
+  lexInteger,
+  lexString,
+  lexDatetime,
+  lexUnknown,
+])
+export type LexUserType = z.infer<typeof lexUserType>
+
+export const lexiconDoc = z
+  .object({
+    lexicon: z.literal(1),
+    id: z.string().refine((v: string) => NSID.isValid(v), {
+      message: 'Must be a valid NSID',
+    }),
+    revision: z.number().optional(),
+    description: z.string().optional(),
+    defs: z.record(lexUserType),
+  })
+  .superRefine((doc: LexiconDoc, ctx) => {
+    for (const defId in doc.defs) {
+      const def = doc.defs[defId]
+      if (
+        defId !== 'main' &&
+        (def.type === 'record' ||
+          def.type === 'procedure' ||
+          def.type === 'query')
+      ) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Records, procedures, and queries must be the main definition.`,
+        })
+      }
+    }
+  })
+export type LexiconDoc = z.infer<typeof lexiconDoc>
+
+// helpers
+// =
+
+export function isValidLexiconDoc(v: unknown): v is LexiconDoc {
+  return lexiconDoc.safeParse(v).success
+}
+
+export function isObj(obj: unknown): obj is Record<string, unknown> {
+  return !!obj && typeof obj === 'object'
+}
+
+export function hasProp<K extends PropertyKey>(
+  data: object,
+  prop: K,
+): data is Record<K, unknown> {
+  return prop in data
+}
+
+export const discriminatedObject = z.object({ $type: z.string() })
+export type DiscriminatedObject = z.infer<typeof discriminatedObject>
+export function isDiscriminatedObject(
+  value: unknown,
+): value is DiscriminatedObject {
+  return discriminatedObject.safeParse(value).success
+}
+
+export class LexiconDocMalformedError extends Error {
+  constructor(
+    message: string,
+    public schemaDef: unknown,
+    public issues?: z.ZodIssue[],
+  ) {
+    super(message)
+    this.schemaDef = schemaDef
+    this.issues = issues
+  }
+}
+
+export interface ValidationResult {
+  success: boolean
+  error?: ValidationError
+}
+
+export class ValidationError extends Error {}
+export class InvalidLexiconError extends Error {}
+export class LexiconDefNotFoundError extends Error {}

package/src/util.ts

@@ -0,0 +1,107 @@
+import { Lexicons } from './lexicons'
+import * as ComplexValidators from './validators/complex'
+import {
+  LexUserType,
+  LexRefVariant,
+  ValidationError,
+  ValidationResult,
+  isDiscriminatedObject,
+} from './types'
+
+export function toLexUri(str: string, baseUri?: string): string {
+  if (str.startsWith('lex:')) {
+    return str
+  }
+  if (str.startsWith('#')) {
+    if (!baseUri) {
+      throw new Error(`Unable to resolve uri without anchor: ${str}`)
+    }
+    return `${baseUri}${str}`
+  }
+  return `lex:${str}`
+}
+
+export function validateOneOf(
+  lexicons: Lexicons,
+  path: string,
+  def: LexRefVariant | LexUserType,
+  value: unknown,
+  mustBeObj = false, // this is the only type constraint we need currently (used by xrpc body schema validators)
+): ValidationResult {
+  let error
+
+  let concreteDefs
+  if (def.type === 'union') {
+    if (!isDiscriminatedObject(value)) {
+      return {
+        success: false,
+        error: new ValidationError(
+          `${path} must be an object which includes the "$type" property`,
+        ),
+      }
+    }
+    if (!def.refs.includes(toLexUri(value.$type))) {
+      if (def.closed) {
+        return {
+          success: false,
+          error: new ValidationError(
+            `${path} $type must be one of ${def.refs.join(', ')}`,
+          ),
+        }
+      }
+      return { success: true }
+    } else {
+      concreteDefs = toConcreteTypes(lexicons, {
+        type: 'ref',
+        ref: value.$type,
+      })
+    }
+  } else {
+    concreteDefs = toConcreteTypes(lexicons, def)
+  }
+
+  for (const concreteDef of concreteDefs) {
+    const result = mustBeObj
+      ? ComplexValidators.object(lexicons, path, concreteDef, value)
+      : ComplexValidators.validate(lexicons, path, concreteDef, value)
+    if (result.success) {
+      return result
+    }
+    error ??= result.error
+  }
+  if (concreteDefs.length > 1) {
+    return {
+      success: false,
+      error: new ValidationError(
+        `${path} did not match any of the expected definitions`,
+      ),
+    }
+  }
+  return { success: false, error }
+}
+
+export function assertValidOneOf(
+  lexicons: Lexicons,
+  path: string,
+  def: LexRefVariant | LexUserType,
+  value: unknown,
+  mustBeObj = false,
+) {
+  const res = validateOneOf(lexicons, path, def, value, mustBeObj)
+  if (!res.success) {
+    throw res.error
+  }
+}
+
+export function toConcreteTypes(
+  lexicons: Lexicons,
+  def: LexRefVariant | LexUserType,
+): LexUserType[] {
+  if (def.type === 'ref') {
+    return [lexicons.getDefOrThrow(def.ref)]
+  } else if (def.type === 'union') {
+    return def.refs.map((ref) => lexicons.getDefOrThrow(ref)).flat()
+  } else {
+    return [def]
+  }
+}

package/src/validation.ts

@@ -0,0 +1,48 @@
+import { Lexicons } from './lexicons'
+import { LexRecord, LexXrpcProcedure, LexXrpcQuery } from './types'
+import { assertValidOneOf } from './util'
+
+import * as ComplexValidators from './validators/complex'
+import * as XrpcValidators from './validators/xrpc'
+
+export function assertValidRecord(
+  lexicons: Lexicons,
+  def: LexRecord,
+  value: unknown,
+) {
+  const res = ComplexValidators.object(lexicons, 'Record', def.record, value)
+  if (!res.success) throw res.error
+}
+
+export function assertValidXrpcParams(
+  lexicons: Lexicons,
+  def: LexXrpcProcedure | LexXrpcQuery,
+  value: unknown,
+) {
+  if (def.parameters) {
+    const res = XrpcValidators.params(lexicons, 'Params', def.parameters, value)
+    if (!res.success) throw res.error
+  }
+}
+
+export function assertValidXrpcInput(
+  lexicons: Lexicons,
+  def: LexXrpcProcedure,
+  value: unknown,
+) {
+  if (def.input?.schema) {
+    // loop: all input schema definitions
+    assertValidOneOf(lexicons, 'Input', def.input.schema, value, true)
+  }
+}
+
+export function assertValidXrpcOutput(
+  lexicons: Lexicons,
+  def: LexXrpcProcedure | LexXrpcQuery,
+  value: unknown,
+) {
+  if (def.output?.schema) {
+    // loop: all output schema definitions
+    assertValidOneOf(lexicons, 'Output', def.output.schema, value, true)
+  }
+}

package/src/validators/blob.ts

@@ -0,0 +1,57 @@
+import { Lexicons } from '../lexicons'
+import { LexUserType, ValidationResult, ValidationError } from '../types'
+import { isObj, hasProp } from '../types'
+
+export function blob(
+  lexicons: Lexicons,
+  path: string,
+  def: LexUserType,
+  value: unknown,
+): ValidationResult {
+  if (!isObj(value)) {
+    return {
+      success: false,
+      error: new ValidationError(`${path} should be an object`),
+    }
+  }
+  if (!hasProp(value, 'cid') || typeof value.cid !== 'string') {
+    return {
+      success: false,
+      error: new ValidationError(`${path}/cid should be a string`),
+    }
+  }
+  if (!hasProp(value, 'mimeType') || typeof value.mimeType !== 'string') {
+    return {
+      success: false,
+      error: new ValidationError(`${path}/mimeType should be a string`),
+    }
+  }
+  return { success: true }
+}
+
+export function image(
+  lexicons: Lexicons,
+  path: string,
+  def: LexUserType,
+  value: unknown,
+): ValidationResult {
+  return blob(lexicons, path, def, value)
+}
+
+export function video(
+  lexicons: Lexicons,
+  path: string,
+  def: LexUserType,
+  value: unknown,
+): ValidationResult {
+  return blob(lexicons, path, def, value)
+}
+
+export function audio(
+  lexicons: Lexicons,
+  path: string,
+  def: LexUserType,
+  value: unknown,
+): ValidationResult {
+  return blob(lexicons, path, def, value)
+}

package/src/validators/complex.ts

@@ -0,0 +1,152 @@
+import { Lexicons } from '../lexicons'
+import {
+  LexArray,
+  LexObject,
+  LexUserType,
+  ValidationResult,
+  ValidationError,
+} from '../types'
+import { validateOneOf } from '../util'
+
+import * as Primitives from './primitives'
+import * as Blob from './blob'
+
+export function validate(
+  lexicons: Lexicons,
+  path: string,
+  def: LexUserType,
+  value: unknown,
+): ValidationResult {
+  switch (def.type) {
+    case 'boolean':
+      return Primitives.boolean(lexicons, path, def, value)
+    case 'number':
+      return Primitives.number(lexicons, path, def, value)
+    case 'integer':
+      return Primitives.integer(lexicons, path, def, value)
+    case 'string':
+      return Primitives.string(lexicons, path, def, value)
+    case 'datetime':
+      return Primitives.datetime(lexicons, path, def, value)
+    case 'unknown':
+      return Primitives.unknown(lexicons, path, def, value)
+    case 'object':
+      return object(lexicons, path, def, value)
+    case 'array':
+      return array(lexicons, path, def, value)
+    case 'blob':
+      return Blob.blob(lexicons, path, def, value)
+    case 'image':
+      return Blob.image(lexicons, path, def, value)
+    case 'video':
+      return Blob.video(lexicons, path, def, value)
+    case 'audio':
+      return Blob.audio(lexicons, path, def, value)
+    default:
+      return {
+        success: false,
+        error: new ValidationError(`Unexpected lexicon type: ${def.type}`),
+      }
+  }
+}
+
+export function array(
+  lexicons: Lexicons,
+  path: string,
+  def: LexUserType,
+  value: unknown,
+): ValidationResult {
+  def = def as LexArray
+
+  // type
+  if (!Array.isArray(value)) {
+    return {
+      success: false,
+      error: new ValidationError(`${path} must be an array`),
+    }
+  }
+
+  // maxLength
+  if (typeof def.maxLength === 'number') {
+    if ((value as Array<unknown>).length > def.maxLength) {
+      return {
+        success: false,
+        error: new ValidationError(
+          `${path} must not have more than ${def.maxLength} elements`,
+        ),
+      }
+    }
+  }
+
+  // minLength
+  if (typeof def.minLength === 'number') {
+    if ((value as Array<unknown>).length < def.minLength) {
+      return {
+        success: false,
+        error: new ValidationError(
+          `${path} must not have fewer than ${def.minLength} elements`,
+        ),
+      }
+    }
+  }
+
+  // items
+  const itemsDef = def.items
+  for (let i = 0; i < (value as Array<unknown>).length; i++) {
+    const itemValue = value[i]
+    const itemPath = `${path}/${i}`
+    const res = validateOneOf(lexicons, itemPath, itemsDef, itemValue)
+    if (!res.success) {
+      return res
+    }
+  }
+
+  return { success: true }
+}
+
+export function object(
+  lexicons: Lexicons,
+  path: string,
+  def: LexUserType,
+  value: unknown,
+): ValidationResult {
+  def = def as LexObject
+
+  // type
+  if (!value || typeof value !== 'object') {
+    return {
+      success: false,
+      error: new ValidationError(`${path} must be an object`),
+    }
+  }
+
+  // required
+  if (Array.isArray(def.required)) {
+    for (const key of def.required) {
+      if (!(key in value)) {
+        return {
+          success: false,
+          error: new ValidationError(`${path} must have the property "${key}"`),
+        }
+      }
+    }
+  }
+
+  // properties
+  if (typeof def.properties === 'object') {
+    for (const key in def.properties) {
+      const propValue = value[key]
+      if (typeof propValue === 'undefined') {
+        continue // skip- if required, will have already failed
+      }
+      const propDef = def.properties[key]
+      const propPath = `${path}/${key}`
+      const res = validateOneOf(lexicons, propPath, propDef, propValue)
+      if (!res.success) {
+        return res
+      }
+    }
+  }
+
+  return { success: true }
+}