@atproto/lex-cli 0.5.7 → 0.6.0

package/src/codegen/client.ts

@@ -9,9 +9,9 @@ import { NSID } from '@atproto/syntax'
 import { GeneratedAPI } from '../types'
 import { gen, lexiconsTs, utilTs } from './common'
 import {
+  genCommonImports,
   genImports,
-  genObjHelpers,
-  genObject,
+  genRecord,
   genUserType,
   genXrpcInput,
   genXrpcOutput,
@@ -70,9 +70,9 @@ const indexTs = (
       { name: 'FetchHandler' },
       { name: 'FetchHandlerOptions' },
     ])
-    //= import {schemas} from './lexicons'
+    //= import {schemas} from './lexicons.js'
     file
-      .addImportDeclaration({ moduleSpecifier: './lexicons' })
+      .addImportDeclaration({ moduleSpecifier: './lexicons.js' })
       .addNamedImports([{ name: 'schemas' }])
     //= import {CID} from 'multiformats/cid'
     file
@@ -81,9 +81,14 @@ const indexTs = (
       })
       .addNamedImports([{ name: 'CID' }])
 
+    //= import {OmitKey} from './util.js'
+    file
+      .addImportDeclaration({ moduleSpecifier: `./util.js` })
+      .addNamedImports([{ name: 'OmitKey' }, { name: 'Un$Typed' }])
+
     // generate type imports and re-exports
     for (const lexicon of lexiconDocs) {
-      const moduleSpecifier = `./types/${lexicon.id.split('.').join('/')}`
+      const moduleSpecifier = `./types/${lexicon.id.split('.').join('/')}.js`
       file
         .addImportDeclaration({ moduleSpecifier })
         .setNamespaceImport(toTitleCase(lexicon.id))
@@ -312,7 +317,7 @@ function genRecordCls(file: SourceFile, nsid: string, lexRecord: LexRecord) {
     })
     method.addParameter({
       name: 'params',
-      type: `Omit<${toTitleCase(ATP_METHODS.list)}.QueryParams, "collection">`,
+      type: `OmitKey<${toTitleCase(ATP_METHODS.list)}.QueryParams, "collection">`,
     })
     method.setBodyText(
       [
@@ -330,7 +335,7 @@ function genRecordCls(file: SourceFile, nsid: string, lexRecord: LexRecord) {
     })
     method.addParameter({
       name: 'params',
-      type: `Omit<${toTitleCase(ATP_METHODS.get)}.QueryParams, "collection">`,
+      type: `OmitKey<${toTitleCase(ATP_METHODS.get)}.QueryParams, "collection">`,
     })
     method.setBodyText(
       [
@@ -348,13 +353,13 @@ function genRecordCls(file: SourceFile, nsid: string, lexRecord: LexRecord) {
     })
     method.addParameter({
       name: 'params',
-      type: `Omit<${toTitleCase(
+      type: `OmitKey<${toTitleCase(
         ATP_METHODS.create,
       )}.InputSchema, "collection" | "record">`,
     })
     method.addParameter({
       name: 'record',
-      type: `${typeModule}.Record`,
+      type: `Un$Typed<${typeModule}.Record>`,
     })
     method.addParameter({
       name: 'headers?',
@@ -365,8 +370,8 @@ function genRecordCls(file: SourceFile, nsid: string, lexRecord: LexRecord) {
       : ''
     method.setBodyText(
       [
-        `record.$type = '${nsid}'`,
-        `const res = await this._client.call('${ATP_METHODS.create}', undefined, { collection: '${nsid}', ${maybeRkeyPart}...params, record }, {encoding: 'application/json', headers })`,
+        `const collection = '${nsid}'`,
+        `const res = await this._client.call('${ATP_METHODS.create}', undefined, { collection, ${maybeRkeyPart}...params, record: { ...record, $type: collection} }, {encoding: 'application/json', headers })`,
         `return res.data`,
       ].join('\n'),
     )
@@ -380,7 +385,7 @@ function genRecordCls(file: SourceFile, nsid: string, lexRecord: LexRecord) {
   //   })
   //   method.addParameter({
   //     name: 'params',
-  //     type: `Omit<${toTitleCase(ATP_METHODS.put)}.InputSchema, "collection" | "record">`,
+  //     type: `OmitKey<${toTitleCase(ATP_METHODS.put)}.InputSchema, "collection" | "record">`,
   //   })
   //   method.addParameter({
   //     name: 'record',
@@ -407,7 +412,7 @@ function genRecordCls(file: SourceFile, nsid: string, lexRecord: LexRecord) {
     })
     method.addParameter({
       name: 'params',
-      type: `Omit<${toTitleCase(
+      type: `OmitKey<${toTitleCase(
         ATP_METHODS.delete,
       )}.InputSchema, "collection">`,
     })
@@ -429,8 +434,6 @@ const lexiconTs = (project, lexicons: Lexicons, lexiconDoc: LexiconDoc) =>
     project,
     `/types/${lexiconDoc.id.split('.').join('/')}.ts`,
     async (file) => {
-      const imports: Set<string> = new Set()
-
       const main = lexiconDoc.defs.main
       if (
         main?.type === 'query' ||
@@ -446,37 +449,10 @@ const lexiconTs = (project, lexicons: Lexicons, lexiconDoc: LexiconDoc) =>
           { name: 'XRPCError' },
         ])
       }
-      //= import {ValidationResult, BlobRef} from '@atproto/lexicon'
-      file
-        .addImportDeclaration({
-          moduleSpecifier: '@atproto/lexicon',
-        })
-        .addNamedImports([{ name: 'ValidationResult' }, { name: 'BlobRef' }])
-      //= import {isObj, hasProp} from '../../util.ts'
-      file
-        .addImportDeclaration({
-          moduleSpecifier: `${lexiconDoc.id
-            .split('.')
-            .map((_str) => '..')
-            .join('/')}/util`,
-        })
-        .addNamedImports([{ name: 'isObj' }, { name: 'hasProp' }])
-      //= import {lexicons} from '../../lexicons.ts'
-      file
-        .addImportDeclaration({
-          moduleSpecifier: `${lexiconDoc.id
-            .split('.')
-            .map((_str) => '..')
-            .join('/')}/lexicons`,
-        })
-        .addNamedImports([{ name: 'lexicons' }])
-      //= import {CID} from 'multiformats/cid'
-      file
-        .addImportDeclaration({
-          moduleSpecifier: 'multiformats/cid',
-        })
-        .addNamedImports([{ name: 'CID' }])
 
+      genCommonImports(file, lexiconDoc.id)
+
+      const imports: Set<string> = new Set()
       for (const defId in lexiconDoc.defs) {
         const def = lexiconDoc.defs[defId]
         const lexUri = `${lexiconDoc.id}#${defId}`
@@ -489,7 +465,7 @@ const lexiconTs = (project, lexicons: Lexicons, lexiconDoc: LexiconDoc) =>
           } else if (def.type === 'subscription') {
             continue
           } else if (def.type === 'record') {
-            genClientRecord(file, imports, lexicons, lexUri)
+            genRecord(file, imports, lexicons, lexUri)
           } else {
             genUserType(file, imports, lexicons, lexUri)
           }
@@ -586,17 +562,3 @@ function genClientXrpcCommon(
       : ['return e'],
   })
 }
-
-function genClientRecord(
-  file: SourceFile,
-  imports: Set<string>,
-  lexicons: Lexicons,
-  lexUri: string,
-) {
-  const def = lexicons.getDefOrThrow(lexUri, ['record'])
-
-  //= export interface Record {...}
-  genObject(file, imports, lexUri, def.record, 'Record')
-  //= export function isRecord(v: unknown): v is Record {...}
-  genObjHelpers(file, lexUri, 'Record')
-}

package/src/codegen/common.ts

@@ -1,28 +1,133 @@
-import { format } from 'prettier'
+import { Options as PrettierOptions, format } from 'prettier'
 import { Project, SourceFile, VariableDeclarationKind } from 'ts-morph'
 import { LexiconDoc } from '@atproto/lexicon'
 import { GeneratedFile } from '../types'
 
-const PRETTIER_OPTS = {
+const PRETTIER_OPTS: PrettierOptions = {
   parser: 'typescript',
   tabWidth: 2,
   semi: false,
   singleQuote: true,
-  trailingComma: 'all' as const,
+  trailingComma: 'all',
 }
 
 export const utilTs = (project) =>
   gen(project, '/util.ts', async (file) => {
     file.replaceWithText(`
-export function isObj(v: unknown): v is Record<string, unknown> {
-  return typeof v === 'object' && v !== null
+import { ValidationResult } from '@atproto/lexicon'
+
+export type OmitKey<T, K extends keyof T> = {
+  [K2 in keyof T as K2 extends K ? never : K2]: T[K2]
+}
+
+export type $Typed<V, T extends string = string> = V & { $type: T }
+export type Un$Typed<V extends { $type?: string }> = OmitKey<V, '$type'>
+
+export type $Type<Id extends string, Hash extends string> = Hash extends 'main'
+  ? Id
+  : \`\${Id}#\${Hash}\`
+
+function isObject<V>(v: V): v is V & object {
+  return v != null && typeof v === 'object'
+}
+
+function is$type<Id extends string, Hash extends string>(
+  $type: unknown,
+  id: Id,
+  hash: Hash,
+): $type is $Type<Id, Hash> {
+  return hash === 'main'
+    ? $type === id
+    : // $type === \`\${id}#\${hash}\`
+      typeof $type === 'string' &&
+        $type.length === id.length + 1 + hash.length &&
+        $type.charCodeAt(id.length) === 35 /* '#' */ &&
+        $type.startsWith(id) &&
+        $type.endsWith(hash)
+}
+${
+  /**
+   * The construct below allows to properly distinguish open unions. Consider
+   * the following example:
+   *
+   * ```ts
+   * type Foo = { $type?: $Type<'foo', 'main'>; foo: string }
+   * type Bar = { $type?: $Type<'bar', 'main'>; bar: string }
+   * type OpenFooBarUnion = $Typed<Foo> | $Typed<Bar> | { $type: string }
+   * ```
+   *
+   * In the context of lexicons, when there is a open union as shown above, the
+   * if `$type` if either `foo` or `bar`, then the object IS of type `Foo` or
+   * `Bar`.
+   *
+   * ```ts
+   * declare const obj1: OpenFooBarUnion
+   * if (is$typed(obj1, 'foo', 'main')) {
+   *   obj1.$type // $Type<'foo', 'main'>
+   *   obj1.foo // string
+   * }
+   * ```
+   *
+   * Similarly, if an object is of type `unknown`, then the `is$typed` function
+   * should only return assurance about the `$type` property, which is what it
+   * actually checks:
+   *
+   * ```ts
+   * declare const obj2: unknown
+   * if (is$typed(obj2, 'foo', 'main')) {
+   *  obj2.$type // $Type<'foo', 'main'>
+   *  // @ts-expect-error
+   *  obj2.foo
+   * }
+   * ```
+   *
+   * The construct bellow is what makes these two scenarios possible.
+   */
+  ''
 }
+export type $TypedObject<V, Id extends string, Hash extends string> = V extends {
+  $type: $Type<Id, Hash>
+}
+  ? V
+  : V extends { $type?: string }
+    ? V extends { $type?: infer T extends $Type<Id, Hash> }
+      ? V & { $type: T }
+      : never
+    : V & { $type: $Type<Id, Hash> }
+
+export function is$typed<V, Id extends string, Hash extends string>(
+  v: V,
+  id: Id,
+  hash: Hash,
+): v is $TypedObject<V, Id, Hash> {
+  return isObject(v) && '$type' in v && is$type(v.$type, id, hash)
+}
+
+export function maybe$typed<V, Id extends string, Hash extends string>(
+  v: V,
+  id: Id,
+  hash: Hash,
+): v is V & object & { $type?: $Type<Id, Hash> } {
+  return (
+    isObject(v) &&
+    ('$type' in v
+      ? v.$type === undefined || is$type(v.$type, id, hash)
+      : true)
+  )
+}
+
+export type Validator<R = unknown> = (v: unknown) => ValidationResult<R>
+export type ValidatorParam<V extends Validator> =
+  V extends Validator<infer R> ? R : never
 
-export function hasProp<K extends PropertyKey>(
-  data: object,
-  prop: K,
-): data is Record<K, unknown> {
-  return prop in data
+/**
+ * Utility function that allows to convert a "validate*" utility function into a
+ * type predicate.
+ */
+export function asPredicate<V extends Validator>(validate: V) {
+  return function <T>(v: T): v is T & ValidatorParam<V> {
+    return validate(v).success
+  }
 }
 `)
   })
@@ -41,7 +146,23 @@ export const lexiconsTs = (project, lexicons: LexiconDoc[]) =>
       .addImportDeclaration({
         moduleSpecifier: '@atproto/lexicon',
       })
-      .addNamedImports([{ name: 'LexiconDoc' }, { name: 'Lexicons' }])
+      .addNamedImports([
+        { name: 'LexiconDoc' },
+        { name: 'Lexicons' },
+        { name: 'ValidationError' },
+        { name: 'ValidationResult' },
+      ])
+
+    //= import {is$typed, maybe$typed, $Typed} from './util'
+    file
+      .addImportDeclaration({
+        moduleSpecifier: './util.js',
+      })
+      .addNamedImports([
+        { name: '$Typed' },
+        { name: 'is$typed' },
+        { name: 'maybe$typed' },
+      ])
 
     //= export const schemaDict = {...} as const satisfies Record<string, LexiconDoc>
     file.addVariableStatement({
@@ -66,14 +187,14 @@ export const lexiconsTs = (project, lexicons: LexiconDoc[]) =>
       ],
     })
 
-    //= export const schemas = Object.values(schemaDict)
+    //= export const schemas = Object.values(schemaDict) satisfies LexiconDoc[]
     file.addVariableStatement({
       isExported: true,
       declarationKind: VariableDeclarationKind.Const,
       declarations: [
         {
           name: 'schemas',
-          initializer: 'Object.values(schemaDict)',
+          initializer: 'Object.values(schemaDict) satisfies LexiconDoc[]',
         },
       ],
     })
@@ -91,6 +212,44 @@ export const lexiconsTs = (project, lexicons: LexiconDoc[]) =>
       ],
     })
 
+    file.addFunction({
+      isExported: true,
+      name: 'validate',
+      overloads: [
+        {
+          typeParameters: ['T extends { $type: string }'],
+          parameters: [
+            { name: 'v', type: 'unknown' },
+            { name: 'id', type: 'string' },
+            { name: 'hash', type: 'string' },
+            { name: 'requiredType', type: 'true' },
+          ],
+          returnType: 'ValidationResult<T>',
+        },
+        {
+          typeParameters: ['T extends { $type?: string }'],
+          parameters: [
+            { name: 'v', type: 'unknown' },
+            { name: 'id', type: 'string' },
+            { name: 'hash', type: 'string' },
+            { name: 'requiredType', type: 'false', hasQuestionToken: true },
+          ],
+          returnType: 'ValidationResult<T>',
+        },
+      ],
+      parameters: [
+        { name: 'v', type: 'unknown' },
+        { name: 'id', type: 'string' },
+        { name: 'hash', type: 'string' },
+        { name: 'requiredType', type: 'boolean', hasQuestionToken: true },
+      ],
+      statements: [
+        // If $type is present, make sure it is valid before validating the rest of the object
+        'return (requiredType ? is$typed : maybe$typed)(v, id, hash) ? lexicons.validate(`${id}#${hash}`, v) : { success: false, error: new ValidationError(`Must be an object with "${hash === \'main\' ? id : `${id}#${hash}`}" $type property`) }',
+      ],
+      returnType: 'ValidationResult',
+    })
+
     //= export const ids = {...}
     file.addVariableStatement({
       isExported: true,
@@ -98,14 +257,11 @@ export const lexiconsTs = (project, lexicons: LexiconDoc[]) =>
       declarations: [
         {
           name: 'ids',
-          initializer: JSON.stringify(
-            lexicons.reduce((acc, cur) => {
-              return {
-                ...acc,
-                [nsidToEnum(cur.id)]: cur.id,
-              }
-            }, {}),
-          ),
+          initializer: `{${lexicons
+            .map(
+              (lex) => `\n  ${nsidToEnum(lex.id)}: ${JSON.stringify(lex.id)},`,
+            )
+            .join('')}\n} as const`,
         },
       ],
     })
@@ -118,12 +274,11 @@ export async function gen(
 ): Promise<GeneratedFile> {
   const file = project.createSourceFile(path)
   await gen(file)
-  file.saveSync()
-  const src = project.getFileSystem().readFileSync(path)
-  return {
-    path: path,
-    content: `${banner()}${await format(src, PRETTIER_OPTS)}`,
-  }
+  await file.save() // Save in the "in memory" file system
+  const src = `${banner()}${file.getFullText()}`
+  const content = await format(src, PRETTIER_OPTS)
+
+  return { path, content }
 }
 
 function banner() {