@atproto/lex-builder 0.1.1 → 0.1.3

package/src/lex-def-builder.ts

@@ -15,6 +15,7 @@ import {
   LexiconError,
   LexiconIndexer,
   LexiconInteger,
+  LexiconMessage,
   LexiconObject,
   LexiconParameters,
   LexiconPayload,
@@ -50,15 +51,6 @@ export type LexDefBuilderOptions = RefResolverOptions & {
    * @default '@atproto/lex-schema'
    */
   lib?: string
-  /**
-   * Whether to add `#__PURE__` annotations to function calls.
-   *
-   * These annotations help bundlers with tree-shaking by marking
-   * side-effect-free function calls.
-   *
-   * @default false
-   */
-  pureAnnotations?: boolean
 }
 
 /**
@@ -86,10 +78,6 @@ export class LexDefBuilder {
     this.refResolver = new RefResolver(doc, file, indexer, options)
   }
 
-  private pure(code: string) {
-    return this.options.pureAnnotations ? markPure(code) : code
-  }
-
   async build() {
     this.file.addVariableStatement({
       declarationKind: VariableDeclarationKind.Const,
@@ -160,7 +148,7 @@ export class LexDefBuilder {
   private async addPermissionSet(hash: string, def: LexiconPermissionSet) {
     const permission = def.permissions.map((def) => {
       const options = stringifyOptions(def, undefined, ['resource', 'type'])
-      return this.pure(
+      return markPure(
         `l.permission(${JSON.stringify(def.resource)}, ${options})`,
       )
     })
@@ -173,134 +161,175 @@ export class LexDefBuilder {
     ] satisfies (keyof l.PermissionSetOptions)[])
 
     await this.addSchema(hash, def, {
-      schema: this.pure(
+      schema: markPure(
         `l.permissionSet($nsid, [${permission.join(',')}], ${options})`,
       ),
     })
   }
 
-  private async addProcedure(hash: string, def: LexiconProcedure) {
-    if (hash !== 'main') {
-      throw new Error(`Definition ${hash} cannot be of type ${def.type}`)
-    }
+  private async addParameters(parameters?: LexiconParameters): Promise<string> {
+    const varName = '$params'
+
+    this.addUtils({
+      [varName]: await this.compileParamsSchema(parameters),
+    })
 
     // @TODO Build the types instead of using an inferred type.
+    this.file.addTypeAlias({
+      isExported: true,
+      name: '$Params',
+      type: `l.InferOutput<typeof ${varName}>`,
+      docs: compileDocs(parameters?.description),
+    })
+
+    return varName
+  }
+
+  private async addInput(input?: LexiconPayload): Promise<string> {
+    const varName = '$input'
 
-    // Declare each piece of the method as its own top-level exported const
-    // *before* `main`, so consumers that import a single helper (e.g.
-    // `$lxm`) only pull in that subtree rather than the whole procedure.
-    // `main.parameters` etc. would otherwise pin `main` in the module graph.
     this.addUtils({
-      $lxm: '$nsid',
-      $params: await this.compileParamsSchema(def.parameters),
-      $input: await this.compilePayload(def.input),
-      $output: await this.compilePayload(def.output),
+      [varName]: await this.compilePayload(input),
     })
 
-    const ref = await this.addSchema(hash, def, {
-      schema: this.pure(
-        `l.procedure($nsid, $params, $input, $output${formatErrorsArg(await this.compileErrors(def.errors))})`,
-      ),
+    // @TODO Build the types instead of using an inferred type.
+    this.file.addTypeAlias({
+      isExported: true,
+      name: '$Input<B = l.BinaryData>',
+      type: `l.InferPayload<typeof ${varName}, B>`,
+      docs: compileDocs(input?.description),
+    })
+
+    this.file.addTypeAlias({
+      isExported: true,
+      name: '$InputBody<B = l.BinaryData>',
+      type: `l.InferPayloadBody<typeof ${varName}, B>`,
+      docs: compileDocs(input?.description),
     })
 
-    this.addMethodTypeUtils(ref, def)
+    return varName
   }
 
-  private async addQuery(hash: string, def: LexiconQuery) {
-    if (hash !== 'main') {
-      throw new Error(`Definition ${hash} cannot be of type ${def.type}`)
-    }
+  private async addOutput(output?: LexiconPayload): Promise<string> {
+    const varName = '$output'
+
+    this.addUtils({
+      [varName]: await this.compilePayload(output),
+    })
 
     // @TODO Build the types instead of using an inferred type.
+    this.file.addTypeAlias({
+      isExported: true,
+      name: '$Output<B = l.BinaryData>',
+      type: `l.InferPayload<typeof ${varName}, B>`,
+      docs: compileDocs(output?.description),
+    })
+
+    this.file.addTypeAlias({
+      isExported: true,
+      name: '$OutputBody<B = l.BinaryData>',
+      type: `l.InferPayloadBody<typeof ${varName}, B>`,
+      docs: compileDocs(output?.description),
+    })
+
+    return varName
+  }
+
+  private async addMessage(message?: LexiconMessage) {
+    const varName = '$message'
 
     this.addUtils({
-      $lxm: '$nsid',
-      $params: await this.compileParamsSchema(def.parameters),
-      $output: await this.compilePayload(def.output),
+      [varName]: await this.compileBodySchema(message?.schema),
     })
 
-    const ref = await this.addSchema(hash, def, {
-      schema: this.pure(
-        `l.query($nsid, $params, $output${formatErrorsArg(await this.compileErrors(def.errors))})`,
-      ),
+    // @TODO Build the types instead of using an inferred type.
+    this.file.addTypeAlias({
+      isExported: true,
+      name: '$Message',
+      type: `l.InferOutput<typeof ${varName}>`,
+      docs: compileDocs(message?.description),
     })
 
-    this.addMethodTypeUtils(ref, def)
+    return varName
   }
 
-  private async addSubscription(hash: string, def: LexiconSubscription) {
+  private async addProcedure(hash: string, def: LexiconProcedure) {
     if (hash !== 'main') {
       throw new Error(`Definition ${hash} cannot be of type ${def.type}`)
     }
 
-    // @TODO Build the types instead of using an inferred type.
+    // Declare each piece of the method as its own top-level exported const
+    // *before* `main`. This allows to export those pieces individually instead
+    // of "extracting" them from the "main" definition as below, which is bad
+    // for tree-shaking.
+    //
+    // export const $params = main.params`
 
-    this.addUtils({
-      $lxm: '$nsid',
-      $params: await this.compileParamsSchema(def.parameters),
-      $message: await this.compileBodySchema(def.message?.schema),
-    })
+    const paramsVar = await this.addParameters(def.parameters)
+    const inputVar = await this.addInput(def.input)
+    const outputVar = await this.addOutput(def.output)
 
-    const ref = await this.addSchema(hash, def, {
-      schema: this.pure(
-        `l.subscription($nsid, $params, $message${formatErrorsArg(await this.compileErrors(def.errors))})`,
+    await this.addSchema(hash, def, {
+      schema: markPure(
+        `l.procedure($nsid, ${paramsVar}, ${inputVar}, ${outputVar}${formatErrorsArg(await this.compileErrors(def.errors))})`,
       ),
     })
 
-    this.addMethodTypeUtils(ref, def)
+    this.addUtils({
+      $lxm: '$nsid',
+    })
   }
 
-  addMethodTypeUtils(
-    ref: ResolvedRef,
-    def: LexiconProcedure | LexiconQuery | LexiconSubscription,
-  ) {
-    this.file.addTypeAlias({
-      isExported: true,
-      name: '$Params',
-      type: `l.InferMethodParams<typeof ${ref.varName}>`,
-      docs: compileDocs(def.parameters?.description),
+  private async addQuery(hash: string, def: LexiconQuery) {
+    if (hash !== 'main') {
+      throw new Error(`Definition ${hash} cannot be of type ${def.type}`)
+    }
+
+    // Declare each piece of the method as its own top-level exported const
+    // *before* `main`. This allows to export those pieces individually instead
+    // of "extracting" them from the "main" definition as below, which is bad
+    // for tree-shaking:
+    //
+    // export const $params = main.params
+
+    const paramsVar = await this.addParameters(def.parameters)
+    const outputVar = await this.addOutput(def.output)
+
+    await this.addSchema(hash, def, {
+      schema: markPure(
+        `l.query($nsid, ${paramsVar}, ${outputVar}${formatErrorsArg(await this.compileErrors(def.errors))})`,
+      ),
     })
 
-    if (def.type === 'procedure') {
-      this.file.addTypeAlias({
-        isExported: true,
-        name: '$Input<B = l.BinaryData>',
-        type: `l.InferMethodInput<typeof ${ref.varName}, B>`,
-        docs: compileDocs(def.input?.description),
-      })
+    this.addUtils({
+      $lxm: '$nsid',
+    })
+  }
 
-      this.file.addTypeAlias({
-        isExported: true,
-        name: '$InputBody<B = l.BinaryData>',
-        type: `l.InferMethodInputBody<typeof ${ref.varName}, B>`,
-        docs: compileDocs(def.input?.description),
-      })
+  private async addSubscription(hash: string, def: LexiconSubscription) {
+    if (hash !== 'main') {
+      throw new Error(`Definition ${hash} cannot be of type ${def.type}`)
     }
 
-    if (def.type === 'procedure' || def.type === 'query') {
-      this.file.addTypeAlias({
-        isExported: true,
-        name: '$Output<B = l.BinaryData>',
-        type: `l.InferMethodOutput<typeof ${ref.varName}, B>`,
-        docs: compileDocs(def.output?.description),
-      })
+    // Declare each piece of the method as its own top-level exported const
+    // *before* `main`. This allows to export those pieces individually instead
+    // of "extracting" them from the "main" definition as below, which is bad
+    // for tree-shaking.
+    //
+    // export const $params = main.params`
 
-      this.file.addTypeAlias({
-        isExported: true,
-        name: '$OutputBody<B = l.BinaryData>',
-        type: `l.InferMethodOutputBody<typeof ${ref.varName}, B>`,
-        docs: compileDocs(def.output?.description),
-      })
-    }
+    const paramsVar = await this.addParameters(def.parameters)
+    const messageVar = await this.addMessage(def.message)
 
-    if (def.type === 'subscription') {
-      this.file.addTypeAlias({
-        isExported: true,
-        name: '$Message',
-        type: `l.InferSubscriptionMessage<typeof ${ref.varName}>`,
-        docs: compileDocs(def.message?.description),
-      })
-    }
+    await this.addSchema(hash, def, {
+      schema: markPure(
+        `l.subscription($nsid, ${paramsVar}, ${messageVar}${formatErrorsArg(await this.compileErrors(def.errors))})`,
+      ),
+    })
+
+    this.addUtils({
+      $lxm: '$nsid',
+    })
   }
 
   private async addRecord(hash: string, def: LexiconRecord) {
@@ -317,7 +346,7 @@ export class LexDefBuilder {
     await this.addSchema(hash, def, {
       type: `{ ${properties.join(';')} }`,
       schema: (ref) =>
-        this.pure(
+        markPure(
           `l.record<${key}, ${ref.typeName}>(${key}, $nsid, ${objectSchema})`,
         ),
       objectUtils: true,
@@ -334,7 +363,7 @@ export class LexDefBuilder {
     await this.addSchema(hash, def, {
       type: `{ ${properties.join(';')} }`,
       schema: (ref) =>
-        this.pure(
+        markPure(
           `l.typedObject<${ref.typeName}>($nsid, ${JSON.stringify(hash)}, ${objectSchema})`,
         ),
       objectUtils: true,
@@ -344,7 +373,7 @@ export class LexDefBuilder {
 
   private async addToken(hash: string, def: LexiconToken) {
     await this.addSchema(hash, def, {
-      schema: this.pure(`l.token($nsid, ${JSON.stringify(hash)})`),
+      schema: markPure(`l.token($nsid, ${JSON.stringify(hash)})`),
       type: JSON.stringify(l.$type(this.doc.id, hash)),
       validationUtils: true,
     })
@@ -366,9 +395,7 @@ export class LexDefBuilder {
       // @NOTE Not using compileArraySchema to allow specifying the generic
       // parameter to l.array<>.
       schema: (ref) =>
-        this.pure(
-          `l.array<${ref.typeName}[number]>(${itemSchema}, ${options})`,
-        ),
+        markPure(`l.array<${ref.typeName}[number]>(${itemSchema}, ${options})`),
       validationUtils: true,
     })
   }
@@ -439,9 +466,9 @@ export class LexDefBuilder {
 
     if (hash === 'main' && objectUtils) {
       this.addUtils({
+        $type: `$nsid`,
         $isTypeOf: markPure(`${ref.varName}.isTypeOf.bind(${ref.varName})`),
         $build: markPure(`${ref.varName}.build.bind(${ref.varName})`),
-        $type: `${ref.varName}.$type`,
       })
     }
 
@@ -465,20 +492,20 @@ export class LexDefBuilder {
   }
 
   private async compilePayload(def: LexiconPayload | undefined) {
-    if (!def) return this.pure(`l.payload()`)
+    if (!def) return markPure(`l.payload()`)
 
     // Special case for JSON object payloads
     if (def.encoding === 'application/json' && def.schema?.type === 'object') {
       const properties = await this.compilePropertiesSchemas(def.schema)
-      return this.pure(`l.jsonPayload({${properties.join(',')}})`)
+      return markPure(`l.jsonPayload({${properties.join(',')}})`)
     }
 
     const encodedEncoding = JSON.stringify(def.encoding)
     if (def.schema) {
       const bodySchema = await this.compileBodySchema(def.schema)
-      return this.pure(`l.payload(${encodedEncoding}, ${bodySchema})`)
+      return markPure(`l.payload(${encodedEncoding}, ${bodySchema})`)
     } else {
-      return this.pure(`l.payload(${encodedEncoding})`)
+      return markPure(`l.payload(${encodedEncoding})`)
     }
   }
 
@@ -491,10 +518,10 @@ export class LexDefBuilder {
   }
 
   private async compileParamsSchema(def: undefined | LexiconParameters) {
-    if (!def) return this.pure(`l.params()`)
+    if (!def) return markPure(`l.params()`)
 
     const properties = await this.compilePropertiesSchemas(def)
-    return this.pure(
+    return markPure(
       properties.length === 0
         ? `l.params()`
         : `l.params({${properties.join(',')}})`,
@@ -508,7 +535,7 @@ export class LexDefBuilder {
 
   private async compileObjectSchema(def: LexiconObject): Promise<string> {
     const properties = await this.compilePropertiesSchemas(def)
-    return this.pure(`l.object({${properties.join(',')}})`)
+    return markPure(`l.object({${properties.join(',')}})`)
   }
 
   private async compilePropertiesSchemas(options: {
@@ -558,11 +585,11 @@ export class LexDefBuilder {
     let schema = await this.compileContainedSchema(def)
 
     if (isNullable) {
-      schema = this.pure(`l.nullable(${schema})`)
+      schema = markPure(`l.nullable(${schema})`)
     }
 
     if (!isRequired) {
-      schema = this.pure(`l.optional(${schema})`)
+      schema = markPure(`l.optional(${schema})`)
     }
 
     return `${JSON.stringify(key)}:${schema}`
@@ -654,7 +681,7 @@ export class LexDefBuilder {
       'minLength',
       'maxLength',
     ] satisfies (keyof l.ArraySchemaOptions)[])
-    return this.pure(`l.array(${itemSchema}, ${options})`)
+    return markPure(`l.array(${itemSchema}, ${options})`)
   }
 
   private async compileArrayType(def: LexiconArray): Promise<string> {
@@ -662,7 +689,7 @@ export class LexDefBuilder {
   }
 
   private async compileUnknownSchema(_def: LexiconUnknown): Promise<string> {
-    return this.pure(`l.lexMap()`)
+    return markPure(`l.lexMap()`)
   }
 
   private async compileUnknownType(_def: LexiconUnknown): Promise<string> {
@@ -672,9 +699,7 @@ export class LexDefBuilder {
   private withDefault(schema: string, defaultValue: unknown) {
     if (defaultValue === undefined) return schema
 
-    return this.pure(
-      `l.withDefault(${schema}, ${JSON.stringify(defaultValue)})`,
-    )
+    return markPure(`l.withDefault(${schema}, ${JSON.stringify(defaultValue)})`)
   }
 
   private async compileBooleanSchema(def: LexiconBoolean): Promise<string> {
@@ -686,7 +711,7 @@ export class LexDefBuilder {
 
     if (hasConst(def)) return this.compileConstSchema(def)
 
-    return this.withDefault(this.pure(`l.boolean()`), def.default)
+    return this.withDefault(markPure(`l.boolean()`), def.default)
   }
 
   private async compileBooleanType(def: LexiconBoolean): Promise<string> {
@@ -717,7 +742,7 @@ export class LexDefBuilder {
       'minimum',
     ] satisfies (keyof l.IntegerSchemaOptions)[])
 
-    return this.withDefault(this.pure(`l.integer(${options})`), def.default)
+    return this.withDefault(markPure(`l.integer(${options})`), def.default)
   }
 
   private async compileIntegerType(def: LexiconInteger): Promise<string> {
@@ -769,7 +794,7 @@ export class LexDefBuilder {
       : undefined
 
     return this.withDefault(
-      this.pure(`l.string${generic ? `<${generic}>` : ''}(${options})`),
+      markPure(`l.string${generic ? `<${generic}>` : ''}(${options})`),
       def.default,
     )
   }
@@ -822,7 +847,7 @@ export class LexDefBuilder {
       'minLength',
       'maxLength',
     ] satisfies (keyof l.BytesSchemaOptions)[])
-    return this.pure(`l.bytes(${options})`)
+    return markPure(`l.bytes(${options})`)
   }
 
   private async compileBytesType(_def: LexiconBytes): Promise<string> {
@@ -834,7 +859,7 @@ export class LexDefBuilder {
       'maxSize',
       'accept',
     ] satisfies (keyof l.BlobSchemaOptions)[])
-    return this.pure(`l.blob(${options})`)
+    return markPure(`l.blob(${options})`)
   }
 
   private async compileBlobType(_def: LexiconBlob): Promise<string> {
@@ -842,7 +867,7 @@ export class LexDefBuilder {
   }
 
   private async compileCidLinkSchema(_def: LexiconCid): Promise<string> {
-    return this.pure(`l.cid()`)
+    return markPure(`l.cid()`)
   }
 
   private async compileCidLinkType(_def: LexiconCid): Promise<string> {
@@ -853,7 +878,7 @@ export class LexDefBuilder {
     const { varName, typeName } = await this.refResolver.resolve(def.ref)
     // @NOTE "as any" is needed in schemas with circular refs as TypeScript
     // cannot infer the type of a value that depends on its initializer type
-    return this.pure(`l.ref<${typeName}>((() => ${varName}) as any)`)
+    return markPure(`l.ref<${typeName}>((() => ${varName}) as any)`)
   }
 
   private async compileRefType(def: LexiconRef): Promise<string> {
@@ -863,7 +888,7 @@ export class LexDefBuilder {
 
   private async compileRefUnionSchema(def: LexiconRefUnion): Promise<string> {
     if (def.refs.length === 0 && def.closed) {
-      return this.pure(`l.never()`)
+      return markPure(`l.never()`)
     }
 
     const refs = await Promise.all(
@@ -871,13 +896,11 @@ export class LexDefBuilder {
         const { varName, typeName } = await this.refResolver.resolve(ref)
         // @NOTE "as any" is needed in schemas with circular refs as TypeScript
         // cannot infer the type of a value that depends on its initializer type
-        return this.pure(`l.typedRef<${typeName}>((() => ${varName}) as any)`)
+        return markPure(`l.typedRef<${typeName}>((() => ${varName}) as any)`)
       }),
     )
 
-    return this.pure(
-      `l.typedUnion([${refs.join(',')}], ${def.closed ?? false})`,
-    )
+    return markPure(`l.typedUnion([${refs.join(',')}], ${def.closed ?? false})`)
   }
 
   private async compileRefUnionType(def: LexiconRefUnion): Promise<string> {
@@ -895,10 +918,10 @@ export class LexDefBuilder {
     T extends null | number | string | boolean,
   >(def: { const: T; enum?: readonly T[]; default?: T }): Promise<string> {
     if (hasEnum(def) && !def.enum.includes(def.const)) {
-      return this.pure(`l.never()`)
+      return markPure(`l.never()`)
     }
 
-    const result = this.pure(`l.literal(${JSON.stringify(def.const)})`)
+    const result = markPure(`l.literal(${JSON.stringify(def.const)})`)
 
     return this.withDefault(result, def.default)
   }
@@ -917,13 +940,13 @@ export class LexDefBuilder {
     default?: T
   }): Promise<string> {
     if (def.enum.length === 0) {
-      return this.pure(`l.never()`)
+      return markPure(`l.never()`)
     }
 
     const result =
       def.enum.length === 1
-        ? this.pure(`l.literal(${JSON.stringify(def.enum[0])})`)
-        : this.pure(`l.enum(${JSON.stringify(def.enum)})`)
+        ? markPure(`l.literal(${JSON.stringify(def.enum[0])})`)
+        : markPure(`l.enum(${JSON.stringify(def.enum)})`)
 
     return this.withDefault(result, def.default)
   }

package/tsconfig.build.json

@@ -8,6 +8,6 @@
     "target": "ES2023",
     "rootDir": "./src",
     "outDir": "./dist",
-    "types": ["node"]
-  }
+    "types": ["node"],
+  },
 }

package/tsconfig.json

@@ -2,6 +2,6 @@
   "include": [],
   "references": [
     { "path": "./tsconfig.build.json" },
-    { "path": "./tsconfig.tests.json" }
-  ]
+    { "path": "./tsconfig.tests.json" },
+  ],
 }

package/tsconfig.tests.json

@@ -4,6 +4,5 @@
   "compilerOptions": {
     "noImplicitAny": true,
     "rootDir": "./",
-    "baseUrl": "./"
-  }
+  },
 }