@atproto/lex 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# @atproto/lex
+
+## 0.0.5
+
+### Patch Changes
+
+- [#4390](https://github.com/bluesky-social/atproto/pull/4390) [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Rework object validation logic to work without `options` argument
+
+- [#4390](https://github.com/bluesky-social/atproto/pull/4390) [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Replace use of `CID` with `Cid`
+
+- [#4390](https://github.com/bluesky-social/atproto/pull/4390) [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Rename schema methods `validate`, `check` and `maybe` to `safeParse`, `matches` and `ifMatches` respectively.
+
+- [#4397](https://github.com/bluesky-social/atproto/pull/4397) [`688f9d6`](https://github.com/bluesky-social/atproto/commit/688f9d67597ba96d6e9c4a4aec4d394d42f4cbf4) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add `CHANGELOG.md` to npm package
+
+- [#4398](https://github.com/bluesky-social/atproto/pull/4398) [`a17d2e8`](https://github.com/bluesky-social/atproto/commit/a17d2e8a59ceb00fa8197642e0767fcc776d5b70) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add `ignoreInvalidLexicons` option when building lexicon schemas
+
+- [#4390](https://github.com/bluesky-social/atproto/pull/4390) [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add `default` option to `const` and `enum` schemas
+
+- Updated dependencies [[`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba), [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba), [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba), [`2d13d05`](https://github.com/bluesky-social/atproto/commit/2d13d05ab06576703742b1b638d2f243b6b2915f), [`d396de0`](https://github.com/bluesky-social/atproto/commit/d396de016d1d55d08cfad1dabd3ffd9eaeea76ea), [`0f2fc65`](https://github.com/bluesky-social/atproto/commit/0f2fc6592f0c89d26ac7a2ef70b12cbd15a18d05), [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba), [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba), [`a487ab8`](https://github.com/bluesky-social/atproto/commit/a487ab8afe8f18d00662e666049be8d28de2b57e), [`a487ab8`](https://github.com/bluesky-social/atproto/commit/a487ab8afe8f18d00662e666049be8d28de2b57e), [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba), [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba), [`a487ab8`](https://github.com/bluesky-social/atproto/commit/a487ab8afe8f18d00662e666049be8d28de2b57e), [`a487ab8`](https://github.com/bluesky-social/atproto/commit/a487ab8afe8f18d00662e666049be8d28de2b57e), [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba), [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba), [`bcae2b7`](https://github.com/bluesky-social/atproto/commit/bcae2b77b68da6dc2ec202651c8bf41fd5769f69), [`bcae2b7`](https://github.com/bluesky-social/atproto/commit/bcae2b77b68da6dc2ec202651c8bf41fd5769f69), [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba), [`a487ab8`](https://github.com/bluesky-social/atproto/commit/a487ab8afe8f18d00662e666049be8d28de2b57e), [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba), [`9f87ff3`](https://github.com/bluesky-social/atproto/commit/9f87ff3aa60090c8c38b6ce400cba6ceff5cd2e9), [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba), [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba), [`688f9d6`](https://github.com/bluesky-social/atproto/commit/688f9d67597ba96d6e9c4a4aec4d394d42f4cbf4), [`a17d2e8`](https://github.com/bluesky-social/atproto/commit/a17d2e8a59ceb00fa8197642e0767fcc776d5b70), [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba), [`1d445af`](https://github.com/bluesky-social/atproto/commit/1d445af2a7fc27eca5a45869b29266e6a2a7f3ba)]:
+  - @atproto/lex-schema@0.0.3
+  - @atproto/lex-installer@0.0.5
+  - @atproto/lex-builder@0.0.5
+  - @atproto/lex-client@0.0.3
+
+## 0.0.4
+
+### Patch Changes
+
+- [#4380](https://github.com/bluesky-social/atproto/pull/4380) [`23c271f`](https://github.com/bluesky-social/atproto/commit/23c271fcac27f090727e2f835697d4733784bdb4) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Fix description of `--allowLegacyBlobs` argument
+
+- [#4380](https://github.com/bluesky-social/atproto/pull/4380) [`23c271f`](https://github.com/bluesky-social/atproto/commit/23c271fcac27f090727e2f835697d4733784bdb4) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Remove `--build`/`--no-build` argument from the `install` command
+
+- [#4380](https://github.com/bluesky-social/atproto/pull/4380) [`23c271f`](https://github.com/bluesky-social/atproto/commit/23c271fcac27f090727e2f835697d4733784bdb4) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add ability to configure file extenstion and import file extension in `lex build`
+
+- Updated dependencies [[`23c271f`](https://github.com/bluesky-social/atproto/commit/23c271fcac27f090727e2f835697d4733784bdb4), [`23c271f`](https://github.com/bluesky-social/atproto/commit/23c271fcac27f090727e2f835697d4733784bdb4), [`23c271f`](https://github.com/bluesky-social/atproto/commit/23c271fcac27f090727e2f835697d4733784bdb4)]:
+  - @atproto/lex-schema@0.0.2
+  - @atproto/lex-builder@0.0.4
+  - @atproto/lex-installer@0.0.4
+  - @atproto/lex-client@0.0.2
+
+## 0.0.3
+
+### Patch Changes
+
+- [#4374](https://github.com/bluesky-social/atproto/pull/4374) [`5ffd612`](https://github.com/bluesky-social/atproto/commit/5ffd6129909071e979c30f31266119865ab582b6) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add missing files from package.json
+
+- Updated dependencies []:
+  - @atproto/lex-builder@0.0.3
+  - @atproto/lex-installer@0.0.3
+  - @atproto/lex-client@0.0.1
+
+## 0.0.2
+
+### Patch Changes
+
+- [#4372](https://github.com/bluesky-social/atproto/pull/4372) [`7456f53`](https://github.com/bluesky-social/atproto/commit/7456f53e45fb3eef2f3bbdf2513da2d8ab078d80) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Fix error when running `install` command
+
+- Updated dependencies [[`7456f53`](https://github.com/bluesky-social/atproto/commit/7456f53e45fb3eef2f3bbdf2513da2d8ab078d80)]:
+  - @atproto/lex-builder@0.0.2
+  - @atproto/lex-client@0.0.1
+  - @atproto/lex-installer@0.0.2
+
+## 0.0.1
+
+### Patch Changes
+
+- [#4371](https://github.com/bluesky-social/atproto/pull/4371) [`46550d6`](https://github.com/bluesky-social/atproto/commit/46550d6c1ffb298f57d54eb1904067b2df5a40af) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Release
+
+- Updated dependencies [[`46550d6`](https://github.com/bluesky-social/atproto/commit/46550d6c1ffb298f57d54eb1904067b2df5a40af)]:
+  - @atproto/lex-builder@0.0.1
+  - @atproto/lex-client@0.0.1
+  - @atproto/lex-installer@0.0.1
+  - @atproto/lex-schema@0.0.1

package/README.md

@@ -1,6 +1,6 @@
 # @atproto/lex
 
-Type-safe Lexicon tooling for creating great API clients.
+Type-safe Lexicon tooling for creating great API clients. See the [Changelog](./CHANGELOG.md) for version history.
 
 ```bash
 npm install -g @atproto/lex
@@ -11,6 +11,10 @@ lex --help
 - Generate TypeScript client and data validators
 - Handle common tasks like OAuth
 
+> [!IMPORTANT]
+>
+> This package is currently in **preview**. The API and features are subject to change before the stable release.
+
 **What is this?**
 
 Working directly with XRPC endpoints requires manually tracking schema definitions, validation data structures, and managing authentication. `@atproto/lex` automates this by:
@@ -94,16 +98,35 @@ This creates:
 Make sure to commit the `lexicons.json` manifest and the `lexicons/` directory containing the JSON files to version control.
 
 ```bash
-echo "./src/lexicons" >> .gitignore
 git add lexicons.json lexicons/
 git commit -m "Install Lexicons"
 ```
 
+**3. Build TypeScript schemas**
+
+Generate TypeScript schemas from the installed Lexicons:
+
+```bash
+lex build
+```
+
+This generates TypeScript files in `./src/lexicons` (by default) with type-safe validation, type guards, and builder utilities.
+
+> [!TIP]
+>
+> If you wish to customize the output location or any other build options, pass the appropriate flags to the `lex build` command. See the [TypeScript Schemas](#typescript-schemas) section for available options.
+
 > [!NOTE]
 >
-> The generated TypeScript files don't need to be committed to version control. Instead, they can be pre-built during your project's build step or post-install step. See [Workflow Integration](#workflow-integration) for details.
+> The generated TypeScript files don't need to be committed to version control. Instead, they can be generated during your project's build step. See [Workflow Integration](#workflow-integration) for details.
+>
+> To avoid committing generated files, add the output directory to your `.gitignore`:
+>
+> ```bash
+> echo "./src/lexicons" >> .gitignore
+> ```
 
-**3. Use in your code**
+**4. Use in your code**
 
 ```typescript
 import { Client } from '@atproto/lex'
@@ -118,10 +141,6 @@ const response = await client.call(app.bsky.actor.getProfile, {
 })
 ```
 
-> [!TIP]
->
-> If you wish to customize the output location, or any other options, you can run the `lex build` command separately. For that purpose, make sure to use the `--no-build` flag when installing lexicons to skip the automatic build step.
-
 ## Lexicon Schemas
 
 The `lex install` command fetches Lexicon schemas from the Atmosphere network and manages them locally (in the `lexicons/` directory by default). It also updates the `lexicons.json` manifest file to track installed Lexicons and their versions.
@@ -147,15 +166,13 @@ Options:
 
 - `--manifest <path>` - Path to lexicons.json manifest file (default: `./lexicons.json`)
 - `--no-save` - Don't update lexicons.json with installed lexicons (save is enabled by default)
-- `--no-build` - Skip building TypeScript lexicon schema files after installation (build is enabled by default)
 - `--update` - Update all installed lexicons to their latest versions by re-resolving and re-installing them
 - `--ci` - Error if the installed lexicons do not match the CIDs in the lexicons.json manifest
 - `--lexicons <dir>` - Directory containing lexicon JSON files (default: `./lexicons`)
-- `--out <dir>` - Output directory for generated TS files (default: `./src/lexicons`)
 
 ## TypeScript Schemas
 
-The `lex install` command automatically builds TypeScript schemas after installing Lexicon JSON files. You can also run the build step separately using the `lex build` command. These generated schemas provide type-safe validation, type guards, and builder utilities for working with AT Protocol data structures.
+After installing Lexicon JSON files, use the `lex build` command to generate TypeScript schemas. These generated schemas provide type-safe validation, type guards, and builder utilities for working with AT Protocol data structures.
 
 ```bash
 lex build --lexicons ./lexicons --out ./src/lexicons
@@ -173,7 +190,9 @@ Options:
 - `--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`)
-- `--allowLegacyBlobs` - Allow generating schemas that accept legacy blob references (disabled by default; enabling this might cause compatibility issues with records created a long time ago)
+- `--allowLegacyBlobs` - Allow generating schemas that accept legacy blob references (disabled by default; enable this if you encounter issues while processing records created a long time ago)
+- `--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`)
 
 ### Generated Schema Structure
 
@@ -745,16 +764,19 @@ Add these scripts to your `package.json`:
 ```json
 {
   "scripts": {
-    "lex:update": "lex install --update --save",
-    "prebuild": "lex install --ci"
+    "update-lexicons": "lex install --update --save",
+    "postinstall": "lex install --ci",
+    "prebuild": "lex build",
+    "build": "# Your build command here"
   }
 }
 ```
 
 This ensures that:
 
-1. Lexicons are installed/verified before every build.
-2. You can easily update lexicons with `npm run lex:update` or `pnpm lex:update`.
+1. Lexicons are verified against the manifest after every `npm install` or `pnpm install`.
+2. TypeScript schemas are built before your project is built.
+3. You can easily update lexicons with `npm run update-lexicons` or `pnpm update-lexicons`.
 
 ### Tree-Shaking
 
@@ -775,7 +797,7 @@ For library authors, use `--pure-annotations` when building:
 lex build --pure-annotations
 ```
 
-This will make the generated code more tree-shakeable from places that import your library.
+This will make the generated code more easily tree-shakeable from places that import your library.
 
 ### Custom Headers
 
@@ -800,8 +822,11 @@ All methods support these base options:
 ```typescript
 type CallOptions = {
   signal?: AbortSignal // Abort the request
-  headers?: HeadersInit // Custom request headers
+  headers?: HeadersInit // Additional request headers
   service?: Service // Override service proxy for this request
+  labelers?: Iterable<Did> // Additional labelers for this request
+  validateRequest?: boolean // Set to "true" to enable request schema validation
+  validateResponse?: boolean // Set to "false" to skip response schema validation
 }
 ```
 

package/bin/lex

@@ -80,7 +80,25 @@ yargs(hideBin(process.argv))
           type: 'boolean',
           default: false,
           describe:
-            'allow generating schemas that accept legacy blob references (disabled by default; enabling this might cause compatibility issues with records created a long time ago)',
+            'generate schemas that accept legacy blob references (disabled by default; enable this if you encounter issues while processing records created a long time ago)',
+        },
+        importExt: {
+          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: {
+          type: 'string',
+          default: '.ts',
+          describe:
+            'file extension to use for generated files (e.g. ".ts", ".mts", ".cts")',
+        },
+        ignoreInvalidLexicons: {
+          type: 'boolean',
+          default: false,
+          describe:
+            'skip over invalid lexicon files instead of exiting with an error',
         },
       })
     },
@@ -105,12 +123,6 @@ yargs(hideBin(process.argv))
           describe:
             'Updates lexicons.json with installed lexicons (use --no-save to disable)',
         },
-        build: {
-          type: 'boolean',
-          default: true,
-          describe:
-            'automatically build TypeScript lexicon schema files after installation (use --no-build to disable)',
-        },
         update: {
           type: 'boolean',
           default: false,
@@ -129,12 +141,6 @@ yargs(hideBin(process.argv))
           default: './lexicons',
           describe: 'directory containing lexicon JSON files',
         },
-        out: {
-          type: 'string',
-          demandOption: true,
-          default: './src/lexicons',
-          describe: 'output directory for generated TS files',
-        },
       })
     },
     async (argv) => {
@@ -146,18 +152,6 @@ yargs(hideBin(process.argv))
         lexicons: argv.lexicons,
         manifest: argv.manifest,
       })
-
-      if (argv.build) {
-        await build({
-          lexicons: argv.lexicons,
-          out: argv.out,
-          clear: true,
-          pretty: true,
-          pureAnnotations: true,
-          ignoreErrors: false,
-          lib: '@atproto/lex',
-        })
-      }
     },
   )
   .parseAsync()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "license": "MIT",
   "description": "Lexicon tooling for AT",
   "keywords": [
@@ -18,7 +18,8 @@
     "./index.cjs",
     "./index.mjs",
     "./index.d.ts",
-    "./bin"
+    "./bin",
+    "./CHANGELOG.md"
   ],
   "bin": {
     "ts-lex": "./bin/lex",
@@ -37,10 +38,10 @@
   },
   "dependencies": {
     "yargs": "^17.0.0",
-    "@atproto/lex-builder": "0.0.3",
-    "@atproto/lex-client": "0.0.1",
-    "@atproto/lex-installer": "0.0.3",
-    "@atproto/lex-schema": "0.0.1"
+    "@atproto/lex-builder": "0.0.5",
+    "@atproto/lex-client": "0.0.3",
+    "@atproto/lex-installer": "0.0.5",
+    "@atproto/lex-schema": "0.0.3"
   },
   "devDependencies": {
     "@types/yargs": "^17.0.33",