@atproto/lexicon 0.0.3 → 0.1.0

package/dist/util.d.ts

@@ -2,5 +2,5 @@ import { Lexicons } from './lexicons';
 import { LexUserType, LexRefVariant, ValidationResult } from './types';
 export declare function toLexUri(str: string, baseUri?: string): string;
 export declare function validateOneOf(lexicons: Lexicons, path: string, def: LexRefVariant | LexUserType, value: unknown, mustBeObj?: boolean): ValidationResult;
-export declare function assertValidOneOf(lexicons: Lexicons, path: string, def: LexRefVariant | LexUserType, value: unknown, mustBeObj?: boolean): void;
+export declare function assertValidOneOf(lexicons: Lexicons, path: string, def: LexRefVariant | LexUserType, value: unknown, mustBeObj?: boolean): unknown;
 export declare function toConcreteTypes(lexicons: Lexicons, def: LexRefVariant | LexUserType): LexUserType[];

package/dist/validation.d.ts

@@ -1,6 +1,7 @@
 import { Lexicons } from './lexicons';
-import { LexRecord, LexXrpcProcedure, LexXrpcQuery } from './types';
-export declare function assertValidRecord(lexicons: Lexicons, def: LexRecord, value: unknown): void;
-export declare function assertValidXrpcParams(lexicons: Lexicons, def: LexXrpcProcedure | LexXrpcQuery, value: unknown): void;
-export declare function assertValidXrpcInput(lexicons: Lexicons, def: LexXrpcProcedure, value: unknown): void;
-export declare function assertValidXrpcOutput(lexicons: Lexicons, def: LexXrpcProcedure | LexXrpcQuery, value: unknown): void;
+import { LexRecord, LexXrpcProcedure, LexXrpcQuery, LexXrpcSubscription } from './types';
+export declare function assertValidRecord(lexicons: Lexicons, def: LexRecord, value: unknown): unknown;
+export declare function assertValidXrpcParams(lexicons: Lexicons, def: LexXrpcProcedure | LexXrpcQuery | LexXrpcSubscription, value: unknown): unknown;
+export declare function assertValidXrpcInput(lexicons: Lexicons, def: LexXrpcProcedure, value: unknown): unknown;
+export declare function assertValidXrpcOutput(lexicons: Lexicons, def: LexXrpcProcedure | LexXrpcQuery, value: unknown): unknown;
+export declare function assertValidXrpcMessage(lexicons: Lexicons, def: LexXrpcSubscription, value: unknown): unknown;

package/dist/validators/blob.d.ts

@@ -1,6 +1,3 @@
 import { Lexicons } from '../lexicons';
 import { LexUserType, ValidationResult } from '../types';
 export declare function blob(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;
-export declare function image(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;
-export declare function video(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;
-export declare function audio(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;

package/dist/validators/complex.d.ts

@@ -1,5 +1,5 @@
 import { Lexicons } from '../lexicons';
-import { LexUserType, ValidationResult } from '../types';
+import { LexArray, LexUserType, ValidationResult } from '../types';
 export declare function validate(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;
-export declare function array(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;
+export declare function array(lexicons: Lexicons, path: string, def: LexArray, value: unknown): ValidationResult;
 export declare function object(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;

package/dist/validators/formats.d.ts

@@ -0,0 +1,9 @@
+import { ValidationResult } from '../types';
+export declare function datetime(path: string, value: string): ValidationResult;
+export declare function uri(path: string, value: string): ValidationResult;
+export declare function atUri(path: string, value: string): ValidationResult;
+export declare function did(path: string, value: string): ValidationResult;
+export declare function handle(path: string, value: string): ValidationResult;
+export declare function atIdentifier(path: string, value: string): ValidationResult;
+export declare function nsid(path: string, value: string): ValidationResult;
+export declare function cid(path: string, value: string): ValidationResult;

package/dist/validators/primitives.d.ts

@@ -2,8 +2,9 @@ import { Lexicons } from '../lexicons';
 import { LexUserType, ValidationResult } from '../types';
 export declare function validate(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;
 export declare function boolean(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;
-export declare function number(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;
+export declare function float(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;
 export declare function integer(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;
 export declare function string(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;
-export declare function datetime(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;
+export declare function bytes(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;
+export declare function cidLink(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;
 export declare function unknown(lexicons: Lexicons, path: string, def: LexUserType, value: unknown): ValidationResult;

package/dist/validators/xrpc.d.ts

@@ -1,3 +1,3 @@
 import { Lexicons } from '../lexicons';
 import { LexXrpcParameters, ValidationResult } from '../types';
-export declare function params(lexicons: Lexicons, path: string, def: LexXrpcParameters, value: unknown): ValidationResult;
+export declare function params(lexicons: Lexicons, path: string, def: LexXrpcParameters, val: unknown): ValidationResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lexicon",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "main": "dist/index.js",
   "scripts": {
     "test": "jest",
@@ -19,8 +19,12 @@
   },
   "license": "MIT",
   "dependencies": {
+    "@atproto/common-web": "*",
+    "@atproto/identifier": "*",
     "@atproto/nsid": "*",
+    "@atproto/uri": "*",
     "iso-datestring-validator": "^2.2.2",
+    "multiformats": "^9.6.4",
     "zod": "^3.14.2"
   }
 }

package/src/blob-refs.ts

@@ -0,0 +1,70 @@
+import { check, ipldToJson, schema } from '@atproto/common-web'
+import { CID } from 'multiformats/cid'
+import { z } from 'zod'
+
+export const typedJsonBlobRef = z
+  .object({
+    $type: z.literal('blob'),
+    ref: schema.cid,
+    mimeType: z.string(),
+    size: z.number(),
+  })
+  .strict()
+export type TypedJsonBlobRef = z.infer<typeof typedJsonBlobRef>
+
+export const untypedJsonBlobRef = z
+  .object({
+    cid: z.string(),
+    mimeType: z.string(),
+  })
+  .strict()
+export type UntypedJsonBlobRef = z.infer<typeof untypedJsonBlobRef>
+
+export const jsonBlobRef = z.union([typedJsonBlobRef, untypedJsonBlobRef])
+export type JsonBlobRef = z.infer<typeof jsonBlobRef>
+
+export class BlobRef {
+  public original: JsonBlobRef
+
+  constructor(
+    public ref: CID,
+    public mimeType: string,
+    public size: number,
+    original?: JsonBlobRef,
+  ) {
+    this.original = original ?? {
+      $type: 'blob',
+      ref,
+      mimeType,
+      size,
+    }
+  }
+
+  static asBlobRef(obj: unknown): BlobRef | null {
+    if (check.is(obj, jsonBlobRef)) {
+      return BlobRef.fromJsonRef(obj)
+    }
+    return null
+  }
+
+  static fromJsonRef(json: JsonBlobRef): BlobRef {
+    if (check.is(json, typedJsonBlobRef)) {
+      return new BlobRef(json.ref, json.mimeType, json.size)
+    } else {
+      return new BlobRef(CID.parse(json.cid), json.mimeType, -1, json)
+    }
+  }
+
+  ipld(): TypedJsonBlobRef {
+    return {
+      $type: 'blob',
+      ref: this.ref,
+      mimeType: this.mimeType,
+      size: this.size,
+    }
+  }
+
+  toJSON() {
+    return ipldToJson(this.ipld())
+  }
+}

package/src/index.ts

@@ -1,2 +1,4 @@
 export * from './types'
 export * from './lexicons'
+export * from './blob-refs'
+export * from './serialize'

package/src/lexicons.ts

@@ -13,12 +13,14 @@ import {
   ValidationError,
   isObj,
   hasProp,
+  LexXrpcSubscription,
 } from './types'
 import {
   assertValidRecord,
   assertValidXrpcParams,
   assertValidXrpcInput,
   assertValidXrpcOutput,
+  assertValidXrpcMessage,
 } from './validation'
 import { toLexUri } from './util'
 import * as ComplexValidators from './validators/complex'
@@ -158,7 +160,7 @@ export class Lexicons {
         `Invalid $type: must be ${lexUri}, got ${$type}`,
       )
     }
-    assertValidRecord(this, def as LexRecord, value)
+    return assertValidRecord(this, def as LexRecord, value)
   }
 
   /**
@@ -166,8 +168,16 @@ export class Lexicons {
    */
   assertValidXrpcParams(lexUri: string, value: unknown) {
     lexUri = toLexUri(lexUri)
-    const def = this.getDefOrThrow(lexUri, ['query', 'procedure'])
-    assertValidXrpcParams(this, def as LexXrpcProcedure | LexXrpcQuery, value)
+    const def = this.getDefOrThrow(lexUri, [
+      'query',
+      'procedure',
+      'subscription',
+    ])
+    return assertValidXrpcParams(
+      this,
+      def as LexXrpcProcedure | LexXrpcQuery | LexXrpcSubscription,
+      value,
+    )
   }
 
   /**
@@ -176,7 +186,7 @@ export class Lexicons {
   assertValidXrpcInput(lexUri: string, value: unknown) {
     lexUri = toLexUri(lexUri)
     const def = this.getDefOrThrow(lexUri, ['procedure'])
-    assertValidXrpcInput(this, def as LexXrpcProcedure, value)
+    return assertValidXrpcInput(this, def as LexXrpcProcedure, value)
   }
 
   /**
@@ -185,7 +195,28 @@ export class Lexicons {
   assertValidXrpcOutput(lexUri: string, value: unknown) {
     lexUri = toLexUri(lexUri)
     const def = this.getDefOrThrow(lexUri, ['query', 'procedure'])
-    assertValidXrpcOutput(this, def as LexXrpcProcedure | LexXrpcQuery, value)
+    return assertValidXrpcOutput(
+      this,
+      def as LexXrpcProcedure | LexXrpcQuery,
+      value,
+    )
+  }
+
+  /**
+   * Validate xrpc subscription message and throw on any error.
+   */
+  assertValidXrpcMessage<T = unknown>(lexUri: string, value: unknown): T {
+    lexUri = toLexUri(lexUri)
+    const def = this.getDefOrThrow(lexUri, ['subscription'])
+    return assertValidXrpcMessage(this, def as LexXrpcSubscription, value) as T
+  }
+
+  /**
+   * Resolve a lex uri given a ref
+   */
+  resolveLexUri(lexUri: string, ref: string) {
+    lexUri = toLexUri(lexUri)
+    return toLexUri(ref, lexUri)
   }
 }
 

package/src/serialize.ts

@@ -0,0 +1,93 @@
+import {
+  check,
+  IpldValue,
+  ipldToJson,
+  jsonToIpld,
+  JsonValue,
+} from '@atproto/common-web'
+import { CID } from 'multiformats/cid'
+import { BlobRef, jsonBlobRef } from './blob-refs'
+
+export type LexValue =
+  | IpldValue
+  | BlobRef
+  | Array<LexValue>
+  | { [key: string]: LexValue }
+
+export type RepoRecord = Record<string, LexValue>
+
+// @NOTE avoiding use of check.is() here only because it makes
+// these implementations slow, and they often live in hot paths.
+
+export const lexToIpld = (val: LexValue): IpldValue => {
+  // walk arrays
+  if (Array.isArray(val)) {
+    return val.map((item) => lexToIpld(item))
+  }
+  // objects
+  if (val && typeof val === 'object') {
+    // convert blobs, leaving the original encoding so that we don't change CIDs on re-encode
+    if (val instanceof BlobRef) {
+      return val.original
+    }
+    // retain cids & bytes
+    if (CID.asCID(val) || val instanceof Uint8Array) {
+      return val
+    }
+    // walk plain objects
+    const toReturn = {}
+    for (const key of Object.keys(val)) {
+      toReturn[key] = lexToIpld(val[key])
+    }
+    return toReturn
+  }
+  // pass through
+  return val
+}
+
+export const ipldToLex = (val: IpldValue): LexValue => {
+  // map arrays
+  if (Array.isArray(val)) {
+    return val.map((item) => ipldToLex(item))
+  }
+  // objects
+  if (val && typeof val === 'object') {
+    // convert blobs, using hints to avoid expensive is() check
+    if (
+      (val['$type'] === 'blob' ||
+        (typeof val['cid'] === 'string' &&
+          typeof val['mimeType'] === 'string')) &&
+      check.is(val, jsonBlobRef)
+    ) {
+      return BlobRef.fromJsonRef(val)
+    }
+    // retain cids, bytes
+    if (CID.asCID(val) || val instanceof Uint8Array) {
+      return val
+    }
+    // map plain objects
+    const toReturn = {}
+    for (const key of Object.keys(val)) {
+      toReturn[key] = ipldToLex(val[key])
+    }
+    return toReturn
+  }
+  // pass through
+  return val
+}
+
+export const lexToJson = (val: LexValue): JsonValue => {
+  return ipldToJson(lexToIpld(val))
+}
+
+export const stringifyLex = (val: LexValue): string => {
+  return JSON.stringify(lexToJson(val))
+}
+
+export const jsonToLex = (val: JsonValue): LexValue => {
+  return ipldToLex(jsonToIpld(val))
+}
+
+export const jsonStringToLex = (val: string): LexValue => {
+  return jsonToLex(JSON.parse(val))
+}

package/src/types.ts

@@ -12,8 +12,8 @@ export const lexBoolean = z.object({
 })
 export type LexBoolean = z.infer<typeof lexBoolean>
 
-export const lexNumber = z.object({
-  type: z.literal('number'),
+export const lexFloat = z.object({
+  type: z.literal('float'),
   description: z.string().optional(),
   default: z.number().optional(),
   minimum: z.number().optional(),
@@ -21,7 +21,7 @@ export const lexNumber = z.object({
   enum: z.number().array().optional(),
   const: z.number().optional(),
 })
-export type LexNumber = z.infer<typeof lexNumber>
+export type LexFloat = z.infer<typeof lexFloat>
 
 export const lexInteger = z.object({
   type: z.literal('integer'),
@@ -34,24 +34,33 @@ export const lexInteger = z.object({
 })
 export type LexInteger = z.infer<typeof lexInteger>
 
+export const lexStringFormat = z.enum([
+  'datetime',
+  'uri',
+  'at-uri',
+  'did',
+  'handle',
+  'at-identifier',
+  'nsid',
+  'cid',
+])
+export type LexStringFormat = z.infer<typeof lexStringFormat>
+
 export const lexString = z.object({
   type: z.literal('string'),
+  format: lexStringFormat.optional(),
   description: z.string().optional(),
   default: z.string().optional(),
   minLength: z.number().int().optional(),
   maxLength: z.number().int().optional(),
+  minGraphemes: z.number().int().optional(),
+  maxGraphemes: 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(),
@@ -60,14 +69,33 @@ export type LexUnknown = z.infer<typeof lexUnknown>
 
 export const lexPrimitive = z.union([
   lexBoolean,
-  lexNumber,
+  lexFloat,
   lexInteger,
   lexString,
-  lexDatetime,
   lexUnknown,
 ])
 export type LexPrimitive = z.infer<typeof lexPrimitive>
 
+// ipld types
+// =
+
+export const lexBytes = z.object({
+  type: z.literal('bytes'),
+  description: z.string().optional(),
+  maxLength: z.number().optional(),
+  minLength: z.number().optional(),
+})
+export type LexBytes = z.infer<typeof lexBytes>
+
+export const lexCidLink = z.object({
+  type: z.literal('cid-link'),
+  description: z.string().optional(),
+})
+export type LexCidLink = z.infer<typeof lexCidLink>
+
+export const lexIpldType = z.union([lexBytes, lexCidLink])
+export type LexIpldType = z.infer<typeof lexIpldType>
+
 // references
 // =
 
@@ -100,51 +128,25 @@ export const lexBlob = z.object({
 })
 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]),
+  items: z.union([lexPrimitive, lexIpldType, lexBlob, lexRefVariant]),
   minLength: z.number().int().optional(),
   maxLength: z.number().int().optional(),
 })
 export type LexArray = z.infer<typeof lexArray>
 
+export const lexPrimitiveArray = lexArray.merge(
+  z.object({
+    items: lexPrimitive,
+  }),
+)
+export type LexPrimitiveArray = z.infer<typeof lexPrimitiveArray>
+
 export const lexToken = z.object({
   type: z.literal('token'),
   description: z.string().optional(),
@@ -155,8 +157,11 @@ export const lexObject = z.object({
   type: z.literal('object'),
   description: z.string().optional(),
   required: z.string().array().optional(),
+  nullable: z.string().array().optional(),
   properties: z
-    .record(z.union([lexRefVariant, lexArray, lexBlobVariant, lexPrimitive]))
+    .record(
+      z.union([lexRefVariant, lexIpldType, lexArray, lexBlob, lexPrimitive]),
+    )
     .optional(),
 })
 export type LexObject = z.infer<typeof lexObject>
@@ -168,7 +173,7 @@ export const lexXrpcParameters = z.object({
   type: z.literal('params'),
   description: z.string().optional(),
   required: z.string().array().optional(),
-  properties: z.record(lexPrimitive),
+  properties: z.record(z.union([lexPrimitive, lexPrimitiveArray])),
 })
 export type LexXrpcParameters = z.infer<typeof lexXrpcParameters>
 
@@ -179,6 +184,14 @@ export const lexXrpcBody = z.object({
 })
 export type LexXrpcBody = z.infer<typeof lexXrpcBody>
 
+export const lexXrpcSubscriptionMessage = z.object({
+  description: z.string().optional(),
+  schema: z.union([lexRefVariant, lexObject]).optional(),
+})
+export type LexXrpcSubscriptionMessage = z.infer<
+  typeof lexXrpcSubscriptionMessage
+>
+
 export const lexXrpcError = z.object({
   name: z.string(),
   description: z.string().optional(),
@@ -204,6 +217,16 @@ export const lexXrpcProcedure = z.object({
 })
 export type LexXrpcProcedure = z.infer<typeof lexXrpcProcedure>
 
+export const lexXrpcSubscription = z.object({
+  type: z.literal('subscription'),
+  description: z.string().optional(),
+  parameters: lexXrpcParameters.optional(),
+  message: lexXrpcSubscriptionMessage.optional(),
+  infos: lexXrpcError.array().optional(),
+  errors: lexXrpcError.array().optional(),
+})
+export type LexXrpcSubscription = z.infer<typeof lexXrpcSubscription>
+
 // database
 // =
 
@@ -223,21 +246,20 @@ export const lexUserType = z.union([
 
   lexXrpcQuery,
   lexXrpcProcedure,
+  lexXrpcSubscription,
 
   lexBlob,
-  lexImage,
-  lexVideo,
-  lexAudio,
 
   lexArray,
   lexToken,
   lexObject,
 
   lexBoolean,
-  lexNumber,
+  lexFloat,
   lexInteger,
   lexString,
-  lexDatetime,
+  lexBytes,
+  lexCidLink,
   lexUnknown,
 ])
 export type LexUserType = z.infer<typeof lexUserType>
@@ -259,11 +281,12 @@ export const lexiconDoc = z
         defId !== 'main' &&
         (def.type === 'record' ||
           def.type === 'procedure' ||
-          def.type === 'query')
+          def.type === 'query' ||
+          def.type === 'subscription')
       ) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
-          message: `Records, procedures, and queries must be the main definition.`,
+          message: `Records, procedures, queries, and subscriptions must be the main definition.`,
         })
       }
     }
@@ -308,10 +331,15 @@ export class LexiconDocMalformedError extends Error {
   }
 }
 
-export interface ValidationResult {
-  success: boolean
-  error?: ValidationError
-}
+export type ValidationResult =
+  | {
+      success: true
+      value: unknown
+    }
+  | {
+      success: false
+      error: ValidationError
+    }
 
 export class ValidationError extends Error {}
 export class InvalidLexiconError extends Error {}

package/src/util.ts

@@ -49,7 +49,7 @@ export function validateOneOf(
           ),
         }
       }
-      return { success: true }
+      return { success: true, value }
     } else {
       concreteDefs = toConcreteTypes(lexicons, {
         type: 'ref',
@@ -88,9 +88,8 @@ export function assertValidOneOf(
   mustBeObj = false,
 ) {
   const res = validateOneOf(lexicons, path, def, value, mustBeObj)
-  if (!res.success) {
-    throw res.error
-  }
+  if (!res.success) throw res.error
+  return res.value
 }
 
 export function toConcreteTypes(