@atproto/lex 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @atproto/lex
 
+## 0.1.3
+
+### Patch Changes
+
+- [#5006](https://github.com/bluesky-social/atproto/pull/5006) [`60721e6`](https://github.com/bluesky-social/atproto/commit/60721e69c8db193eb817c4238ac447505ac855bc) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Fix README
+
+- [#5006](https://github.com/bluesky-social/atproto/pull/5006) [`60721e6`](https://github.com/bluesky-social/atproto/commit/60721e69c8db193eb817c4238ac447505ac855bc) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Update `yargs` depedency
+
+- Updated dependencies [[`60721e6`](https://github.com/bluesky-social/atproto/commit/60721e69c8db193eb817c4238ac447505ac855bc), [`60721e6`](https://github.com/bluesky-social/atproto/commit/60721e69c8db193eb817c4238ac447505ac855bc)]:
+  - @atproto/lex-schema@0.1.2
+  - @atproto/lex-client@0.1.3
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -1,7 +1,3 @@
-> [!IMPORTANT]
->
-> This package is currently in **preview**. The API and features are subject to change before the stable release. See the [Changelog](./CHANGELOG.md) for version history.
-
 Type-safe Lexicon tooling for AT Protocol data.
 
 - Fetch and manage Lexicon schemas, generate TypeScript validators
@@ -54,14 +50,16 @@ const posts = await client.list(app.bsky.feed.post, { limit: 10 })
   - [Type definitions](#type-definitions)
   - [Building data](#building-data)
   - [Validation Helpers](#validation-helpers)
-    - [`$nsid` - Namespace Identifier](#nsid---namespace-identifier)
-    - [`$type` - Type Identifier](#type---type-identifier)
-    - [`$check(data)` - Type Guard](#checkdata---type-guard)
-    - [`$parse(data)` - Parse and Validate](#parsedata---parse-and-validate)
-    - [`$validate(data)` - Validate a value against the schema](#validatedata---validate-a-value-against-the-schema)
-    - [`$safeParse(data, options?)` - Parse a value against a schema and get the resulting value](#safeparsedata-options---parse-a-value-against-a-schema-and-get-the-resulting-value)
-    - [`$build(data)` - Build with Defaults](#builddata---build-with-defaults)
-    - [`$isTypeOf(data)` - Type Discriminator](#istypeofdata---type-discriminator)
+    - [Record / typed-object helpers](#record--typed-object-helpers)
+      - [`$type` - Type Identifier](#type---type-identifier)
+      - [`$build(data)` - Build with Defaults](#builddata---build-with-defaults)
+      - [`$isTypeOf(data)` - Type Discriminator](#istypeofdata---type-discriminator)
+    - [Universal validation helpers](#universal-validation-helpers)
+      - [`$matches(data)` - Type Guard](#matchesdata---type-guard)
+      - [`$assert(data)` - Type-Narrowing Assertion](#assertdata---type-narrowing-assertion)
+      - [`$parse(data)` - Parse and Validate](#parsedata---parse-and-validate)
+      - [`$validate(data)` - Validate a value against the schema](#validatedata---validate-a-value-against-the-schema)
+      - [`$safeParse(data, options?)` - Parse a value against a schema and get the resulting value](#safeparsedata-options---parse-a-value-against-a-schema-and-get-the-resulting-value)
 - [Data Model](#data-model)
   - [Types](#types)
   - [JSON Encoding](#json-encoding)
@@ -120,6 +118,7 @@ const posts = await client.list(app.bsky.feed.post, { limit: 10 })
     - [Packaging Actions as a Library](#packaging-actions-as-a-library)
     - [Best Practices for Actions](#best-practices-for-actions)
   - [Standard Schema Compatibility](#standard-schema-compatibility)
+  - [Validating Generic Schemas with `$check`](#validating-generic-schemas-with-check)
 - [License](#license)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -233,15 +232,16 @@ Options:
 - `--clear` - Clear output directory before generating
 - `--override` - Override existing files (has no effect with --clear)
 - `--no-pretty` - Don't run prettier on generated files (prettier is enabled by default)
-- `--ignore-errors` - How to handle errors when processing input files
-- `--pure-annotations` - Add `/*#__PURE__*/` annotations for tree-shaking tools. Set this to true if you are using generated lexicons in a library
+- `--ignore-errors` - Skip files that fail to parse or compile instead of aborting the build
+- `--ignore-invalid-lexicons` - Skip lexicon files that fail validation instead of exiting with an error
 - `--exclude <patterns...>` - List of strings or regex patterns to exclude lexicon documents by their IDs
 - `--include <patterns...>` - List of strings or regex patterns to include lexicon documents by their IDs
 - `--lib <package>` - Package name of the library to import the lex schema utility "l" from (default: `@atproto/lex`)
-- `--importExt <ext>` - File extension to use for import statements in generated files (default: `.js`). Use `--importExt ""` to generate extension-less imports
-- `--fileExt <ext>` - File extension to use for generated files (default: `.ts`)
-- `--indexFile` - Generate an "index" file that re-exports all root-level namespaces (disabled by default)
-- `--no-defaultExport` - Disable generation of a `default` export of the `main` schema in each schema's namespace file (default exports are enabled by default; see [Tree-Shaking](#tree-shaking))
+- `--import-ext <ext>` - File extension to use for import statements in generated files (default: `.js`). Use `--import-ext ""` to generate extension-less imports
+- `--file-ext <ext>` - File extension to use for generated files (default: `.ts`)
+- `--index-file` - Generate an "index" file that re-exports all root-level namespaces (disabled by default)
+- `--defs-export` - When some definitions conflict with child namespaces, export lexicon definitions under a separate `$defs` namespace (e.g. `com.example.foo.$defs`)
+- `--no-default-export` - Disable generation of a `default` export of the `main` schema in each schema's namespace file (default exports are enabled by default; see [Tree-Shaking](#tree-shaking))
 
 ### Generated Schema Structure
 
@@ -286,11 +286,12 @@ app.bsky.feed.post.$validate(post)
 
 ### Validation Helpers
 
-Each schema provides multiple validation methods:
+Generated namespaces expose a handful of `$`-prefixed helpers bound to the namespace's `main` schema. They come in two groups:
 
-#### `$nsid` - Namespace Identifier
+- [**Universal validation helpers**](#universal-validation-helpers) are available on every schema's `main`: `$matches`, `$assert`, `$check`, `$parse`, `$safeParse`, `$validate`, `$safeValidate` (and `$cast` / `$ifMatches`). These work for records, typed objects, queries, procedures, and subscriptions.
+- [**Record / typed-object helpers**](#record--typed-object-helpers) are only emitted for record and typed-object schemas: `$type`, `$build`, `$isTypeOf`.
 
-Returns the NSID of the schema:
+In addition, every generated namespace file exports a top-level `$nsid` constant containing the NSID of the lexicon document:
 
 ```typescript
 import * as app from './lexicons/app.js'
@@ -298,9 +299,13 @@ import * as app from './lexicons/app.js'
 console.log(app.bsky.feed.defs.$nsid) // 'app.bsky.feed.defs'
 ```
 
-#### `$type` - Type Identifier
+The Schema instance itself (for example `app.bsky.feed.post.main`) also exposes the underlying methods both with and without the `$` prefix (e.g. `main.parse()` and `main.$parse()`).
+
+#### Record / typed-object helpers
 
-Returns the `$type` string of the schema (for record and object schemas):
+##### `$type` - Type Identifier
+
+Returns the `$type` string of the schema (only available on record and typed-object schemas):
 
 ```typescript
 import * as app from './lexicons/app.js'
@@ -309,7 +314,52 @@ console.log(app.bsky.feed.post.$type) // 'app.bsky.feed.post'
 console.log(app.bsky.actor.defs.profileViewBasic.$type) // 'app.bsky.actor.defs#profileViewBasic'
 ```
 
-#### `$check(data)` - Type Guard
+Prefer `$type` over hard-coding the equivalent string literal in your code. The constant is emitted exactly once per schema in the generated namespace file, so every reference reuses the same string instance. Inlining `'app.bsky.feed.post'` everywhere instead leaks the same string into every call site, increases bundle size, and creates a typo-prone source of drift between your code and the schema.
+
+##### `$build(data)` - Build with Defaults
+
+Builds data by adding the `$type` property and properly types the result. This also allows to declare a variable with the correct type without having to explicitly specify it.
+
+```typescript
+import { l } from '@atproto/lex'
+import * as app from './lexicons/app.js'
+
+// The type of the "like" variable will be "app.bsky.feed.like.Main" (no need to explicitly specify the type)
+const like = app.bsky.feed.like.$build({
+  subject: {
+    uri: 'at://did:plc:abc/app.bsky.feed.post/123',
+    cid: 'bafyrei...',
+  },
+  createdAt: l.currentDatetimeString(),
+})
+```
+
+> [!NOTE]
+>
+> `$build()` does not perform validation, and expects properly typed input data - use `$parse()` if you need validation.
+
+##### `$isTypeOf(data)` - Type Discriminator
+
+Discriminates (pre-validated) data based on its `$type` property, without re-validating. This is especially useful when working with union types:
+
+```typescript
+import { l } from '@atproto/lex'
+import * as app from './lexicons/app.js'
+
+declare const data:
+  | app.bsky.feed.post.Main
+  | app.bsky.feed.like.Main
+  | l.Unknown$TypedObject
+
+// Discriminate by $type without re-validating
+if (app.bsky.feed.post.$isTypeOf(data)) {
+  // data is a post
+}
+```
+
+#### Universal validation helpers
+
+##### `$matches(data)` - Type Guard
 
 Returns `true` if data matches the schema, `false` otherwise. Acts as a TypeScript type guard:
 
@@ -317,19 +367,45 @@ Returns `true` if data matches the schema, `false` otherwise. Acts as a TypeScri
 import { l } from '@atproto/lex'
 import * as app from './lexicons/app.js'
 
-const data = {
+const data: unknown = {
   $type: 'app.bsky.feed.post',
   text: 'Hello!',
   createdAt: l.currentDatetimeString(),
 }
 
-if (app.bsky.feed.post.$check(data)) {
+if (app.bsky.feed.post.$matches(data)) {
   // TypeScript knows data is a Post here
   console.log(data.text)
 }
 ```
 
-#### `$parse(data)` - Parse and Validate
+> [!NOTE]
+>
+> Performs validation so [`$isTypeOf`](#istypeofdata---type-discriminator) is preferred for pre-validated & properly typed data.
+
+##### `$assert(data)` - Type-Narrowing Assertion
+
+Throws if `data` does not match the schema. When the schema is statically known (e.g. `app.bsky.feed.post`), TypeScript narrows the type of `data` after the call:
+
+```typescript
+import { l } from '@atproto/lex'
+import * as app from './lexicons/app.js'
+
+const data: unknown = {
+  $type: 'app.bsky.feed.post',
+  text: 'Hello!',
+  createdAt: l.currentDatetimeString(),
+}
+
+app.bsky.feed.post.$assert(data)
+
+// TypeScript now knows data is app.bsky.feed.post.Main
+console.log(data.text)
+```
+
+For library code that operates on a schema parameter whose type cannot be fully expressed, see [Validating Generic Schemas with `$check`](#validating-generic-schemas-with-check).
+
+##### `$parse(data)` - Parse and Validate
 
 Validates and returns typed data, throwing an error if validation fails:
 
@@ -338,11 +414,12 @@ import { l } from '@atproto/lex'
 import * as app from './lexicons/app.js'
 
 try {
-  const post = app.bsky.feed.post.$main.$parse({
+  const post = app.bsky.feed.post.$parse({
     $type: 'app.bsky.feed.post',
     text: 'Hello!',
     createdAt: l.currentDatetimeString(),
   })
+
   // post is now typed and validated
   console.log(post.text)
 } catch (error) {
@@ -354,7 +431,7 @@ try {
 >
 > The `$parse` method will apply defaults defined in the schema for optional fields, as well as data coercion (e.g., CID strings to Cid types). This means that the returned value might be different from the input data if defaults were applied. Use `$validate()` for value validation.
 
-#### `$validate(data)` - Validate a value against the schema
+##### `$validate(data)` - Validate a value against the schema
 
 Validates an existing value against a schema, returning the value itself if, and only if, it already matches the schema (ie. without applying defaults or coercion).
 
@@ -374,7 +451,7 @@ const result = app.bsky.feed.post.$validate(value)
 value === result // true
 ```
 
-#### `$safeParse(data, options?)` - Parse a value against a schema and get the resulting value
+##### `$safeParse(data, options?)` - Parse a value against a schema and get the resulting value
 
 Returns a detailed validation result object without throwing:
 
@@ -405,43 +482,6 @@ app.bsky.feed.post.$safeParse(data) // { strict: true } is the default
 app.bsky.feed.post.$safeParse(data, { strict: false })
 ```
 
-#### `$build(data)` - Build with Defaults
-
-Builds data by adding the `$type` property and properly types the result. Note that `$build()` does not perform validation - use `$parse()` if you need validation:
-
-```typescript
-import { l } from '@atproto/lex'
-import * as app from './lexicons/app.js'
-
-// The type of the "like" variable will be "app.bsky.feed.like.Main"
-const like = app.bsky.feed.like.$build({
-  subject: {
-    uri: 'at://did:plc:abc/app.bsky.feed.post/123',
-    cid: 'bafyrei...',
-  },
-  createdAt: l.currentDatetimeString(),
-})
-```
-
-#### `$isTypeOf(data)` - Type Discriminator
-
-Discriminates (pre-validated) data based on its `$type` property, without re-validating. This is especially useful when working with union types:
-
-```typescript
-import { l } from '@atproto/lex'
-import * as app from './lexicons/app.js'
-
-declare const data:
-  | app.bsky.feed.post.Main
-  | app.bsky.feed.like.Main
-  | l.Unknown$TypedObject
-
-// Discriminate by $type without re-validating
-if (app.bsky.feed.post.$isTypeOf(data)) {
-  // data is a post
-}
-```
-
 ## Data Model
 
 The AT Protocol uses a [data model](https://atproto.com/specs/data-model) that extends JSON with two additional data structures: **CIDs** (content-addressed links) and **bytes** (for raw data). This data model can be encoded either as JSON for XRPC (HTTP API) or as [CBOR](https://dasl.ing/drisl.html) for storage and authentication (see [`@atproto/lex-cbor`](../lex-cbor)).
@@ -710,7 +750,7 @@ console.log(result.cid)
 Options:
 
 - `rkey` - Custom record key (auto-generated if not provided)
-- `validate` - Asks the PDS to validate the record against schema when processing the request
+- `validate` - Tri-state instruction to the PDS. `true` forces server-side schema validation, `false` explicitly disables it, and `undefined` (default) lets the PDS decide (it validates only collections whose schemas it knows)
 - `validateRequest` - Validate the record locally against schema before submitting the request
 - `swapCommit` - CID for optimistic concurrency control
 
@@ -752,8 +792,8 @@ await client.put(app.bsky.actor.profile, {
 Options:
 
 - `rkey` - Record key (required for non-literal keys)
-- `validate` - Validate record against schema before updating (falls back to `validateRequest` option if not specified)
-- `validateRequest` - Alternative way to enable validation (used if `validate` is not specified)
+- `validate` - Tri-state instruction to the PDS. `true` forces server-side schema validation, `false` explicitly disables it, and `undefined` (default) lets the PDS decide (it validates only collections whose schemas it knows)
+- `validateRequest` - Validate the record locally against schema before submitting the request
 - `swapCommit` - Expected repo commit CID
 - `swapRecord` - Expected record CID
 
@@ -785,6 +825,11 @@ for (const record of result.records) {
   console.log(record.uri, record.value.text)
 }
 
+// Records that failed local schema validation are returned separately
+for (const invalid of result.invalid) {
+  console.warn('Invalid record:', invalid)
+}
+
 // Pagination
 if (result.cursor) {
   const nextPage = await client.list(app.bsky.feed.post, {
@@ -794,6 +839,12 @@ if (result.cursor) {
 }
 ```
 
+The result includes:
+
+- `records` - Records that successfully validated against the schema
+- `invalid` - Records returned by the server that failed local schema validation (raw `LexMap` values)
+- `cursor` - Pagination cursor (if more results are available)
+
 #### `client.applyWrites()`
 
 Perform an atomic batch of create, update, and delete operations in a single request.
@@ -830,7 +881,7 @@ for (const result of response.body.results) {
 Options:
 
 - `repo` - Repository identifier (defaults to authenticated user's DID)
-- `validate` - Asks the PDS to validate records against schema
+- `validate` - Tri-state instruction to the PDS. `true` forces server-side schema validation, `false` explicitly disables it, and `undefined` (default) lets the PDS decide (it validates only collections whose schemas it knows)
 - `swapCommit` - CID for optimistic concurrency control
 
 > [!NOTE]
@@ -869,13 +920,23 @@ if (result.success) {
   // Handle success
   console.log(result.body)
 } else {
-  // Handle failure - result is an XrpcFailure
+  // Handle failure - result is an XrpcFailure.
+  //
+  // All XrpcFailure subclasses inherit from XrpcError and share these members:
+  result.error // string error code (e.g. "HandleNotFound", "UpstreamFailure")
+  result.message // string
+  result.shouldRetry() // boolean - whether the error is transient
+
+  if (result.matchesSchemaErrors()) {
+    // Check if the error matches a declared error in the schema.
+    // TypeScript narrows `result.error` to one of the method's declared error codes.
+    result.error // "HandleNotFound"
+  }
+
+  // Branch on the specific error class to access additional members:
   if (result instanceof XrpcResponseError) {
     // The server responded with an error status code (4xx or 5xx).
     // This is used for all error responses, whether or not they have a valid XRPC error payload.
-
-    result.error // string (e.g. "HandleNotFound", "AuthenticationRequired", "UpstreamFailure", etc.)
-    result.message // string
     result.response.status // number
     result.response.headers // Headers
     result.payload // undefined | { body: unknown; encoding: string }
@@ -885,25 +946,11 @@ if (result.success) {
   } else if (result instanceof XrpcInvalidResponseError) {
     // The response was truly invalid (3xx redirect, malformed JSON, schema mismatch, etc.).
     // This is a more specific error for responses that are not processable.
-
-    result.error // "UpstreamFailure"
-    result.message // string
     result.response.status // number
     result.response.headers // Headers
     result.payload // undefined | { body: unknown; encoding: string }
   } else if (result instanceof XrpcInternalError) {
     // Something went wrong on the client side (network error, etc.)
-    result.error // "InternalServerError"
-    result.message // string
-  }
-
-  // All XrpcFailure types have these properties:
-  result.shouldRetry() // boolean - whether the error is transient
-
-  if (result.matchesSchemaErrors()) {
-    // Check if the error matches a declared error in the schema.
-    // TypeScript knows this is a declared error for the method.
-    result.error // "HandleNotFound"
   }
 }
 ```
@@ -1041,9 +1088,9 @@ import {
   isLanguageString, // Validate language tags (e.g., 'en', 'pt-BR')
 
   // Low-level JSON encoding helpers
-  parseLexLink, // { $link: string } → Cid
+  parseLexLink, // { $link: string } → Cid | undefined
   encodeLexLink, // Cid → { $link: string }
-  parseLexBytes, // { $bytes: string } → Uint8Array
+  parseLexBytes, // { $bytes: string } → Uint8Array | undefined
   encodeLexBytes, // Uint8Array → { $bytes: string }
 } from '@atproto/lex'
 
@@ -1313,7 +1360,7 @@ An `Action` is a function with this signature:
 type Action<Input, Output> = (
   client: Client,
   input: Input,
-  options: CallOptions,
+  options: ActionOptions,
 ) => Output | Promise<Output>
 ```
 
@@ -1321,7 +1368,7 @@ Actions receive:
 
 - `client` - The Client instance (to make XRPC calls)
 - `input` - The input data for the action
-- `options` - Call options (signal)
+- `options` - `ActionOptions` (currently just `{ signal?: AbortSignal }`)
 
 #### Using Actions
 
@@ -1636,10 +1683,10 @@ export const updateProfile: Action<ProfileUpdate, void> = async (
         },
       })
 
-      const current = app.bsky.actor.profile.main.validate(res.body.record)
+      const current = app.bsky.actor.profile.$safeValidate(res.body.record)
 
       // Merge updates with current profile (if valid)
-      const updated = app.bsky.actor.profile.main.build({
+      const updated = app.bsky.actor.profile.$build({
         ...(current.success ? current.value : undefined),
         ...updates,
       })
@@ -1744,6 +1791,26 @@ if ('value' in result) {
 
 When validated through the Standard Schema interface, schemas operate in "parse" mode, meaning transformations like defaults and coercions are applied to the output.
 
+### Validating Generic Schemas with `$check`
+
+`$check(data)` is the non-narrowing counterpart to [`$assert(data)`](#assertdata---type-narrowing-assertion): both throw when `data` does not match the schema, but `$check` does not refine the static type of its argument.
+
+`$check` is rarely needed in application code — prefer `$assert`. It is intended for library-style code that takes a schema as a generic parameter, where TypeScript cannot satisfy the assertion-signature requirement and `$assert` produces the following error:
+
+> 'schema' needs an explicit type annotation.
+> Assertions require every name in the call target to be declared with an explicit type annotation. `ts(2775)`
+
+In that situation, switch to `$check`:
+
+```typescript
+import type { Schema } from '@atproto/lex'
+
+function ensureMatches<S extends Schema>(schema: S, data: unknown) {
+  // schema.$assert(data) // ❌ ts(2775): needs an explicit type annotation
+  schema.$check(data) // ✅ throws on invalid, no type narrowing
+}
+```
+
 ## License
 
 MIT or Apache2

package/bin/lex

@@ -69,37 +69,37 @@ yargs(hideBin(process.argv))
           describe:
             'package name of the library to import the lex schema utility "l" from',
         },
-        importExt: {
+        'import-ext': {
           type: 'string',
           default: '.js',
           describe:
             'file extension to use for import statements in generated files (e.g. ".ts", ".mts", ".cts"). Use --import-ext "" to generate extension-less imports.',
         },
-        fileExt: {
+        'file-ext': {
           type: 'string',
           default: '.ts',
           describe:
             'file extension to use for generated files (e.g. ".ts", ".mts", ".cts")',
         },
-        indexFile: {
+        'index-file': {
           type: 'boolean',
           default: false,
           describe:
             'generate an "index.<fileExt>" file that exports all root-level namespaces',
         },
-        defsExport: {
+        'defs-export': {
           type: 'boolean',
           default: false,
           describe:
             'when some definitions conflict with child namespaces, this option allows to export lexicon definitions under a separate $defs namespace (e.g. com.example.foo.$defs)',
         },
-        defaultExport: {
+        'default-export': {
           type: 'boolean',
           default: true,
           describe:
             'whether to generate a default export for the "main" lexicon definition schema in the parent namespace file',
         },
-        ignoreInvalidLexicons: {
+        'ignore-invalid-lexicons': {
           type: 'boolean',
           default: false,
           describe:
@@ -159,4 +159,6 @@ yargs(hideBin(process.argv))
       })
     },
   )
+  .strictCommands()
+  .demandCommand(1)
   .parseAsync()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "engines": {
     "node": ">=22"
   },
@@ -36,13 +36,13 @@
   },
   "dependencies": {
     "tslib": "^2.8.1",
-    "yargs": "^17.0.0",
+    "yargs": "^18.0.0",
     "@atproto/lex-builder": "^0.1.2",
-    "@atproto/lex-client": "^0.1.2",
+    "@atproto/lex-client": "^0.1.3",
     "@atproto/lex-data": "^0.1.1",
     "@atproto/lex-json": "^0.1.0",
     "@atproto/lex-installer": "^0.1.0",
-    "@atproto/lex-schema": "^0.1.1"
+    "@atproto/lex-schema": "^0.1.2"
   },
   "devDependencies": {
     "@types/yargs": "^17.0.33",