@atproto/lex-schema 0.1.1 → 0.1.3

package/src/helpers.test.ts

@@ -1,4 +1,4 @@
-import { describe, test } from 'vitest'
+import { describe, expect, expectTypeOf, it, test } from 'vitest'
 import * as l from './external.js'
 
 class BinaryValue {
@@ -567,3 +567,128 @@ describe('InferMethodMessage', () => {
     })
   })
 })
+
+describe(l.atUri, () => {
+  describe('string collection', () => {
+    const did = 'did:example:alice'
+
+    it('builds a valid record URI', () => {
+      const uri = l.atUri(did, 'com.ex.foo', 'bar')
+      expect(uri).toBe('at://did:example:alice/com.ex.foo/bar')
+      expectTypeOf(uri).toEqualTypeOf<`at://did:example:alice/com.ex.foo/bar`>()
+    })
+
+    it('validates record key values', () => {
+      expect(() => {
+        // @ts-expect-error
+        l.atUri(did, 'com.ex.foo', '.')
+      }).toThrow()
+      expect(() => {
+        // @ts-expect-error
+        l.atUri(did, 'com.ex.foo', '..')
+      }).toThrow()
+    })
+
+    it('expects a second argument', () => {
+      expect(() => {
+        // @ts-expect-error
+        l.atUri(did, 'com.ex.foo')
+      }).toThrow()
+    })
+  })
+
+  describe('literal', () => {
+    const schema = l.record('literal:bar', 'com.ex.foo', l.object({}))
+    const did = 'did:example:alice'
+
+    it('allows omitting the record key for literal keys', () => {
+      const uri = l.atUri(did, schema)
+      expect(uri).toBe('at://did:example:alice/com.ex.foo/bar')
+      expectTypeOf(uri).toEqualTypeOf<`at://did:example:alice/com.ex.foo/bar`>()
+    })
+
+    it('still allows providing the record key for literal keys', () => {
+      expectTypeOf(
+        l.atUri(did, schema, 'bar'),
+      ).toEqualTypeOf<`at://did:example:alice/com.ex.foo/bar`>()
+    })
+
+    it('validates invalid record keys', () => {
+      expect(() => {
+        // @ts-expect-error
+        l.atUri(did, schema, 'wrong')
+      }).toThrow()
+    })
+  })
+
+  describe('tid', () => {
+    const schema = l.record('tid', 'com.ex.foo', l.object({}))
+    const did = 'did:example:alice'
+
+    it('builds a valid record URI', () => {
+      const uri = l.atUri(did, schema, '3jzfcijpj2z2a')
+      expectTypeOf(
+        uri,
+      ).toEqualTypeOf<`at://did:example:alice/com.ex.foo/3jzfcijpj2z2a`>()
+      expect(uri).toBe('at://did:example:alice/com.ex.foo/3jzfcijpj2z2a')
+    })
+
+    it('expects a second argument for non-literal keys', () => {
+      expect(() => {
+        // @ts-expect-error
+        l.atUri(did, schema)
+      }).toThrow()
+    })
+
+    it('validates the record key value', () => {
+      expect(() => {
+        l.atUri(did, schema, 'invalid-tid')
+      }).toThrow()
+    })
+  })
+
+  describe('any', () => {
+    const schema = l.record('any', 'com.ex.foo', l.object({}))
+    const did = 'did:example:alice'
+
+    it('builds a valid record URI valid keys', () => {
+      const uri = l.atUri(did, schema, 'customKey')
+      expect(uri).toBe('at://did:example:alice/com.ex.foo/customKey')
+      expectTypeOf(
+        uri,
+      ).toEqualTypeOf<`at://did:example:alice/com.ex.foo/customKey`>()
+    })
+
+    it('rejects invalid record key values', () => {
+      expect(() => {
+        // @ts-expect-error
+        l.atUri(did, schema, '.')
+      }).toThrow()
+      expect(() => {
+        // @ts-expect-error
+        l.atUri(did, schema, '..')
+      }).toThrow()
+    })
+
+    it('expects a second argument', () => {
+      expect(() => {
+        // @ts-expect-error
+        l.atUri(did, schema)
+      }).toThrow()
+    })
+
+    describe('edge cases', () => {
+      it('limits the record key to 512 characters', () => {
+        const uri = l.atUri(did, schema, 'a'.repeat(512))
+
+        expect(uri).toBe(`at://did:example:alice/com.ex.foo/${'a'.repeat(512)}`)
+        expectTypeOf(
+          uri,
+        ).toEqualTypeOf<`at://did:example:alice/com.ex.foo/${string}`>()
+        expect(() => {
+          l.atUri(did, schema, 'a'.repeat(513))
+        }).toThrow()
+      })
+    })
+  })
+})

package/src/helpers.ts

@@ -1,11 +1,22 @@
 import { LexErrorData } from '@atproto/lex-data'
-import { InferOutput, Restricted, Schema } from './core.js'
+import {
+  AtIdentifierString,
+  InferOutput,
+  NsidString,
+  RecordKeyValue,
+  Restricted,
+  Schema,
+  assertAtIdentifierString,
+  assertStringFormat,
+} from './core.js'
 import {
   InferPayload,
   InferPayloadBody,
   InferPayloadEncoding,
+  InferRecordKey,
   Procedure,
   Query,
+  RecordSchema,
   Subscription,
   object,
   optional,
@@ -113,3 +124,99 @@ export const lexErrorDataSchema = object({
   // description of the error, appropriate for display to humans
   message: optional(string()),
 }) satisfies Schema<LexErrorData>
+
+/**
+ * Helper function to construct AT Protocol URIs with compile-time & runtime
+ * validation of their components. This function supports different use cases,
+ * including constructing URIs from raw strings or from RecordSchema instances,
+ * ensuring that the resulting URI adheres to the expected format.
+ *
+ * @throws {TypeError} If the arguments do not match the interface
+ * @throws {Error} If AT-URI components are invalid
+ *
+ * @example
+ * ```typescript
+ * import { atUri } from '@atproto/lex'
+ * import { app } from '#/lexicons/index.js'
+ *
+ * // Constructing a URI from raw components
+ * const uri1 = atUri('did:example:123', 'app.bsky.feed.post', 'my-post')
+ *
+ * // Constructing a URI from a RecordSchema instance
+ * const uri2 = atUri('did:example:123', app.bsky.feed.post, 'my-post')
+ *
+ * // Literal rkey can be omitted
+ * const uri3 = atUri('did:example:123', app.bsky.actor.profile) // rkey 'self' is implied
+ *
+ * // Invalid URIs will throw errors
+ * atUri('invalid authority', 'app.bsky.feed.post', 'my-post') // throws
+ * atUri('did:example:123', 'invalid collection', 'my-post') // throws
+ * atUri('did:example:123', 'app.bsky.feed.post', '..') // throws
+ * ```
+ */
+export function atUri<const TAuthority extends AtIdentifierString>(
+  authority: TAuthority,
+): `at://${TAuthority}`
+export function atUri<
+  const TAuthority extends AtIdentifierString,
+  const TCollection extends NsidString,
+  const TRecordKey extends RecordKeyValue,
+>(
+  authority: TAuthority,
+  nsid: TCollection,
+  rkey: TRecordKey extends '..' | '.' ? never : TRecordKey,
+): `at://${TAuthority}/${TCollection}/${TRecordKey}`
+export function atUri<
+  const TAuthority extends AtIdentifierString,
+  const TRecord extends RecordSchema,
+>(
+  authority: TAuthority,
+  record: TRecord['key'] extends `literal:${string}` ? Main<TRecord> : never,
+): `at://${TAuthority}/${TRecord['$type']}/${InferRecordKey<TRecord>}`
+export function atUri<
+  const TAuthority extends AtIdentifierString,
+  const TRecord extends RecordSchema,
+  const TRecordKey extends InferRecordKey<TRecord>,
+>(
+  authority: TAuthority,
+  record: Main<TRecord>,
+  rkey: TRecordKey extends '..' | '.' ? never : TRecordKey,
+): `at://${TAuthority}/${TRecord['$type']}/${TRecordKey}`
+export function atUri(
+  authority: AtIdentifierString,
+  record?: string | Main<RecordSchema>,
+  rkey?: string,
+) {
+  /**
+   * @NOTE because we are encoding potentially untrusted input into a URI, we
+   * validate the input against the AT Protocol constraints, ensuring that no
+   * invalid URIs can be generated.
+   */
+  switch (typeof record) {
+    case 'undefined': {
+      assertAtIdentifierString(authority)
+      return `at://${authority}`
+    }
+
+    case 'string': {
+      if (!rkey) {
+        throw new TypeError('Record key is required when record is a string')
+      }
+      assertAtIdentifierString(authority)
+      assertStringFormat(record, 'nsid')
+      assertStringFormat(rkey, 'record-key')
+      return `at://${authority}/${record}/${rkey}`
+    }
+
+    default: {
+      // @NOTE The use of a schema assumes that the collection ($type) is a
+      // valid NSID that can safely be included in the URI without additional
+      // checks.
+      assertAtIdentifierString(authority)
+      const schema = getMain(record)
+      // @NOTE parsing will apply defaults, so that literal keys will be
+      // properly validated and included in the URI.
+      return `at://${authority}/${schema.$type}/${schema.keySchema.parse(rkey)}`
+    }
+  }
+}

package/src/schema/record.test.ts

@@ -12,7 +12,6 @@ describe('RecordSchema', () => {
       'any',
       'app.bsky.feed.post',
       object({
-        $type: string(),
         text: string(),
       }),
     )
@@ -284,7 +283,6 @@ describe('RecordSchema', () => {
       'any',
       'app.bsky.feed.post',
       object({
-        $type: string(),
         text: string(),
       }),
     )
@@ -320,7 +318,6 @@ describe('RecordSchema', () => {
       'tid',
       'app.bsky.feed.post',
       object({
-        $type: string(),
         text: string(),
       }),
     )
@@ -356,7 +353,6 @@ describe('RecordSchema', () => {
       'nsid',
       'app.bsky.feed.post',
       object({
-        $type: string(),
         text: string(),
       }),
     )
@@ -395,7 +391,6 @@ describe('RecordSchema', () => {
         'literal:self',
         'app.bsky.feed.post',
         object({
-          $type: string(),
           text: string(),
         }),
       )
@@ -426,7 +421,6 @@ describe('RecordSchema', () => {
         'literal:customKey',
         'app.bsky.feed.post',
         object({
-          $type: string(),
           text: string(),
         }),
       )
@@ -453,7 +447,6 @@ describe('RecordSchema', () => {
       'any',
       'app.bsky.feed.post#main',
       object({
-        $type: string(),
         text: string(),
       }),
     )
@@ -488,7 +481,6 @@ describe('RecordSchema', () => {
       'any',
       'app.bsky.feed.post',
       object({
-        $type: string(),
         text: string({ maxLength: 300 }),
         createdAt: string({ format: 'datetime' }),
       }),
@@ -527,7 +519,6 @@ describe('RecordSchema', () => {
       'any',
       'app.bsky.feed.post',
       object({
-        $type: string(),
         text: string(),
       }),
     )
@@ -592,7 +583,6 @@ describe('RecordSchema', () => {
         'any',
         'app.bsky.complex',
         object({
-          $type: string(),
           nested: object({
             deep: object({
               value: string(),
@@ -618,7 +608,6 @@ describe('RecordSchema', () => {
       'any',
       'app.bsky.feed.post',
       object({
-        $type: string(),
         text: string(),
       }),
     )
@@ -639,7 +628,6 @@ describe('RecordSchema', () => {
       'any',
       'app.bsky.feed.post',
       object({
-        $type: string(),
         text: string(),
       }),
     )
@@ -656,7 +644,6 @@ describe('RecordSchema', () => {
       'any',
       'app.bsky.feed.post',
       object({
-        $type: string(),
         text: string(),
         author: string(),
       }),
@@ -682,35 +669,32 @@ describe('RecordSchema', () => {
 
   describe('different record key types', () => {
     it('constructs with key type "any"', () => {
-      const schema = record('any', 'app.bsky.test', object({ $type: string() }))
+      const schema = record('any', 'app.bsky.test', object({}))
       expect(schema.key).toBe('any')
       expect(schema.keySchema).toBeDefined()
     })
 
     it('constructs with key type "tid"', () => {
-      const schema = record('tid', 'app.bsky.test', object({ $type: string() }))
+      const schema = record('tid', 'app.bsky.test', object({}))
       expect(schema.key).toBe('tid')
       expect(schema.keySchema).toBeDefined()
     })
 
     it('constructs with key type "nsid"', () => {
-      const schema = record(
-        'nsid',
-        'app.bsky.test',
-        object({ $type: string() }),
-      )
+      const schema = record('nsid', 'app.bsky.test', object({}))
       expect(schema.key).toBe('nsid')
       expect(schema.keySchema).toBeDefined()
+      expect(schema.keySchema.safeParse('app.bsky.post').success).toBe(true)
+      expect(schema.keySchema.safeParse('invalid-nsid').success).toBe(false)
     })
 
     it('constructs with literal key type', () => {
-      const schema = record(
-        'literal:custom',
-        'app.bsky.test',
-        object({ $type: string() }),
-      )
+      const schema = record('literal:custom', 'app.bsky.test', object({}))
       expect(schema.key).toBe('literal:custom')
       expect(schema.keySchema).toBeDefined()
+      // Applies default value in parse mode
+      expect(schema.keySchema.parse(undefined)).toBe('custom')
+      expect(schema.keySchema.safeParse('not-custom').success).toBe(false)
     })
   })
 
@@ -719,7 +703,6 @@ describe('RecordSchema', () => {
       'any',
       'app.bsky.feed.post',
       object({
-        $type: string(),
         text: string(),
       }),
     )
@@ -755,7 +738,6 @@ describe('RecordSchema', () => {
         'any',
         'app.bsky.feed.post',
         object({
-          $type: string(),
           text: string(),
         }),
       )
@@ -774,7 +756,6 @@ describe('RecordSchema', () => {
         'any',
         'app.bsky.feed.post',
         object({
-          $type: string(),
           text: string(),
         }),
       )
@@ -791,7 +772,6 @@ describe('RecordSchema', () => {
         'any',
         'app.bsky.feed.post#reply123',
         object({
-          $type: string(),
           text: string(),
         }),
       )
@@ -809,7 +789,6 @@ describe('RecordSchema', () => {
       'any',
       'app.bsky.feed.post',
       object({
-        $type: string(),
         text: string(),
       }),
     )

package/src/schema/record.ts

@@ -6,8 +6,8 @@ import {
   InferOutput,
   LexiconRecordKey,
   NsidString,
+  RecordKeyValue,
   Schema,
-  TidString,
   Unknown$TypedObject,
   ValidationContext,
   Validator,
@@ -15,6 +15,7 @@ import {
 import { lazyProperty } from '../util/lazy-property.js'
 import { literal } from './literal.js'
 import { string } from './string.js'
+import { withDefault } from './with-default.js'
 
 /**
  * Infers the record key type from a RecordSchema.
@@ -22,7 +23,7 @@ import { string } from './string.js'
  * @template R - The RecordSchema type
  */
 export type InferRecordKey<R extends RecordSchema> =
-  R extends RecordSchema<infer TKey> ? RecordKeySchemaOutput<TKey> : never
+  R extends RecordSchema<infer TKey> ? RecordKeyValue<TKey> : never
 
 export type TypedRecord<
   TType extends NsidString,
@@ -120,24 +121,16 @@ export class RecordSchema<
 }
 
 export type RecordKeySchemaOutput<Key extends LexiconRecordKey> =
-  Key extends 'any'
-    ? string
-    : Key extends 'tid'
-      ? TidString
-      : Key extends 'nsid'
-        ? NsidString
-        : Key extends `literal:${infer L extends string}`
-          ? L
-          : never
+  RecordKeyValue<Key>
 
 export type RecordKeySchema<Key extends LexiconRecordKey> = Schema<
-  RecordKeySchemaOutput<Key>
+  RecordKeyValue<Key>
 >
 
-const keySchema = string({ minLength: 1 })
+const keySchema = string({ format: 'record-key' })
 const tidSchema = string({ format: 'tid' })
 const nsidSchema = string({ format: 'nsid' })
-const selfLiteralSchema = literal('self')
+const selfLiteralSchema = withDefault(literal('self'), 'self')
 
 function recordKey<Key extends LexiconRecordKey>(
   key: Key,
@@ -147,9 +140,9 @@ function recordKey<Key extends LexiconRecordKey>(
   if (key === 'tid') return tidSchema as any
   if (key === 'nsid') return nsidSchema as any
   if (key.startsWith('literal:')) {
-    const value = key.slice(8) as RecordKeySchemaOutput<Key>
+    const value = key.slice(8) as RecordKeyValue<Key>
     if (value === 'self') return selfLiteralSchema as any
-    return literal(value)
+    return withDefault(literal(value), value)
   }
 
   throw new Error(`Unsupported record key type: ${key}`)

package/src/schema/token.ts

@@ -24,6 +24,10 @@ export class TokenSchema<
     super()
   }
 
+  get $token(): TValue {
+    return this.value
+  }
+
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (input === this.value) {
       return ctx.success(this.value)
@@ -31,7 +35,11 @@ export class TokenSchema<
 
     // @NOTE: allow using the token instance itself (but convert to the actual
     // token value)
-    if (input instanceof TokenSchema && input.value === this.value) {
+    if (
+      ctx.options.mode === 'parse' &&
+      input instanceof TokenSchema &&
+      input.value === this.value
+    ) {
       return ctx.success(this.value)
     }
 

package/src/schema/union.ts

@@ -1,10 +1,10 @@
 import {
   InferInput,
   InferOutput,
+  Issue,
   LexValidationError,
   Schema,
   ValidationContext,
-  ValidationFailure,
   Validator,
 } from '../core.js'
 
@@ -44,16 +44,16 @@ export class UnionSchema<
   }
 
   validateInContext(input: unknown, ctx: ValidationContext) {
-    const failures: ValidationFailure[] = []
+    const issues: Issue[] = []
 
     for (const validator of this.validators) {
       const result = ctx.validate(input, validator)
       if (result.success) return result
 
-      failures.push(result)
+      issues.push(...result.issues)
     }
 
-    return ctx.failure(LexValidationError.fromFailures(failures))
+    return new LexValidationError(issues)
   }
 }