From 70319054b5ae6dc09ed44499a6ef5481095a7a9f Mon Sep 17 00:00:00 2001 From: Dave Thompson Date: Tue, 25 Aug 2026 07:41:48 -0400 Subject: [PATCH 1/2] chore(release): prepare v0.2.5 Generated by GPT-5.6 Terra via OpenCode under supervision of @3leapsdave Co-Authored-By: GPT-5.6 Terra Role: devlead Committer-of-Record: Dave Thompson [@3leapsdave] --- .gitignore | 2 +- CHANGELOG.md | 17 ++++- Cargo.lock | 14 ++-- Cargo.toml | 12 +-- Makefile | 6 +- RELEASE_CHECKLIST.md | 4 +- RELEASE_NOTES.md | 46 ++++++----- VERSION | 2 +- .../typescript/npm/darwin-arm64/package.json | 2 +- .../npm/linux-arm64-gnu/package.json | 2 +- .../typescript/npm/linux-x64-gnu/package.json | 2 +- .../npm/linux-x64-musl/package.json | 2 +- .../npm/win32-x64-msvc/package.json | 2 +- bindings/typescript/package-lock.json | 76 +++++++++++++++++++ bindings/typescript/package.json | 12 +-- crates/ipcprims-schema/src/lib.rs | 10 ++- docs/guides/schema-registry.md | 8 +- docs/releases/v0.2.5.md | 26 +++++++ scripts/check-version.sh | 20 +++++ 19 files changed, 206 insertions(+), 59 deletions(-) create mode 100644 bindings/typescript/package-lock.json create mode 100644 docs/releases/v0.2.5.md diff --git a/.gitignore b/.gitignore index 7f6d7b1..60c0c2b 100644 --- a/.gitignore +++ b/.gitignore @@ -89,7 +89,7 @@ yarn-debug.log* yarn-error.log* # Root-level npm lockfile (repo tooling only) -package-lock.json +/package-lock.json # NAPI-RS build artifacts bindings/typescript/target/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 18261bb..5f225dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,20 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm ## [Unreleased] +## [0.2.5] — 2026-08-25 + +Patch release for TypeScript package interoperability and SchemaRegistry guidance. + +### Changed + +- **TypeScript package exports**: the package now provides explicit CommonJS and ESM entrypoints with matching declarations, including ESM named imports. +- **SchemaRegistry documentation**: added configuration, strict-mode, directory-loading, peer-integration, and TypeScript usage guidance. + +### Compatibility + +- CommonJS `require()` support remains available. The TypeScript package continues to require Node.js 20+. +- No wire format, peer transport, or SchemaRegistry runtime behavior changed in this release. + ## [0.2.4] — 2026-08-21 Patch release for a compatible Rust lockfile refresh, including `h2` 0.4.18 on the schema HTTP resolver path. @@ -228,7 +242,8 @@ First functional release. Transport, framing, schema validation, peer management - Transitive dependency duplication: `getrandom` (0.2 + 0.3) and `windows-sys` (0.60 + 0.61) via `jsonschema` dependency tree. No functional impact; tracked for supply chain awareness. - `cbindgen.toml` is present as a placeholder; the `ffi/` crate does not exist yet. Shipped in v0.1.1. -[Unreleased]: https://github.com/3leaps/ipcprims/compare/v0.2.4...HEAD +[Unreleased]: https://github.com/3leaps/ipcprims/compare/v0.2.5...HEAD +[0.2.5]: https://github.com/3leaps/ipcprims/compare/v0.2.4...v0.2.5 [0.2.4]: https://github.com/3leaps/ipcprims/compare/v0.2.3...v0.2.4 [0.2.3]: https://github.com/3leaps/ipcprims/compare/v0.2.2...v0.2.3 [0.2.2]: https://github.com/3leaps/ipcprims/compare/v0.2.1...v0.2.2 diff --git a/Cargo.lock b/Cargo.lock index cbe4701..1de31a1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -775,7 +775,7 @@ dependencies = [ [[package]] name = "ipcprims" -version = "0.2.4" +version = "0.2.5" dependencies = [ "clap", "comfy-table", @@ -794,7 +794,7 @@ dependencies = [ [[package]] name = "ipcprims-ffi" -version = "0.2.4" +version = "0.2.5" dependencies = [ "ipcprims-frame", "ipcprims-peer", @@ -804,7 +804,7 @@ dependencies = [ [[package]] name = "ipcprims-frame" -version = "0.2.4" +version = "0.2.5" dependencies = [ "bytes", "futures-util", @@ -817,7 +817,7 @@ dependencies = [ [[package]] name = "ipcprims-napi" -version = "0.2.4" +version = "0.2.5" dependencies = [ "ipcprims-frame", "ipcprims-peer", @@ -832,7 +832,7 @@ dependencies = [ [[package]] name = "ipcprims-peer" -version = "0.2.4" +version = "0.2.5" dependencies = [ "bytes", "futures-core", @@ -850,7 +850,7 @@ dependencies = [ [[package]] name = "ipcprims-schema" -version = "0.2.4" +version = "0.2.5" dependencies = [ "ipcprims-frame", "jsonschema", @@ -861,7 +861,7 @@ dependencies = [ [[package]] name = "ipcprims-transport" -version = "0.2.4" +version = "0.2.5" dependencies = [ "bytes", "libc", diff --git a/Cargo.toml b/Cargo.toml index 2366bb5..28e2c53 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,7 +11,7 @@ members = [ ] [workspace.package] -version = "0.2.4" +version = "0.2.5" edition = "2021" rust-version = "1.88.0" license = "MIT OR Apache-2.0" @@ -23,11 +23,11 @@ categories = ["os", "network-programming"] [workspace.dependencies] # Internal dependencies -ipcprims-transport = { version = "0.2.4", path = "crates/ipcprims-transport" } -ipcprims-frame = { version = "0.2.4", path = "crates/ipcprims-frame" } -ipcprims-schema = { version = "0.2.4", path = "crates/ipcprims-schema" } -ipcprims-peer = { version = "0.2.4", path = "crates/ipcprims-peer" } -ipcprims-ffi = { version = "0.2.4", path = "crates/ipcprims-ffi" } +ipcprims-transport = { version = "0.2.5", path = "crates/ipcprims-transport" } +ipcprims-frame = { version = "0.2.5", path = "crates/ipcprims-frame" } +ipcprims-schema = { version = "0.2.5", path = "crates/ipcprims-schema" } +ipcprims-peer = { version = "0.2.5", path = "crates/ipcprims-peer" } +ipcprims-ffi = { version = "0.2.5", path = "crates/ipcprims-ffi" } # Core bytes = "1" diff --git a/Makefile b/Makefile index 84d879c..77c6366 100644 --- a/Makefile +++ b/Makefile @@ -507,7 +507,7 @@ version-set: ## Set explicit version (V=X.Y.Z) @echo "$(V)" > $(VERSION_FILE) @echo "Version set to $(V)" -version-sync: ## Sync VERSION file to Cargo.toml and package.json +version-sync: ## Sync VERSION file to Cargo.toml and TypeScript package manifests @ver=$$(cat $(VERSION_FILE)); \ if command -v cargo-set-version >/dev/null 2>&1; then \ cargo set-version --workspace "$$ver"; \ @@ -530,6 +530,10 @@ version-sync: ## Sync VERSION file to Cargo.toml and package.json fi; \ done; \ echo "[ok] Synced $$ts_root/npm/*/package.json to $$ver"; \ + if [ -f "$$ts_root/package-lock.json" ]; then \ + (cd "$$ts_root" && npm install --package-lock-only --ignore-scripts); \ + echo "[ok] Synced $$ts_root/package-lock.json to $$ver"; \ + fi; \ fi version-check: ## Validate version consistency across files diff --git a/RELEASE_CHECKLIST.md b/RELEASE_CHECKLIST.md index 0e73aa2..7e99f60 100644 --- a/RELEASE_CHECKLIST.md +++ b/RELEASE_CHECKLIST.md @@ -15,7 +15,7 @@ This document walks maintainers through the build/sign/upload flow for each ipcp - [ ] Update `VERSION` file with new semver (e.g., `0.2.0`) - [ ] Sync version to all manifests: `make version-sync` - - Syncs `Cargo.toml` workspace, `Cargo.lock`, and all `bindings/typescript` `package.json` files + - Syncs the `Cargo.toml` workspace, `Cargo.lock`, TypeScript package manifests, and `bindings/typescript/package-lock.json` - **Do not skip**: version drift between `VERSION` and `Cargo.toml` is a hard failure in `make prepush` - [ ] Update `CHANGELOG.md` (move Unreleased section to new version heading) - **Do not skip footer links**: add `[X.Y.Z]` compare link and re-anchor `[Unreleased]` to compare from the new tag to `HEAD` @@ -29,7 +29,7 @@ This document walks maintainers through the build/sign/upload flow for each ipcp 1. Working tree clean check 2. `make prepush` — fmt, clippy, tests, cargo-deny, **version consistency** - 3. `make version-check` — full consistency: `VERSION`, `Cargo.toml`, all TypeScript packages + 3. `make version-check` — full consistency: `VERSION`, `Cargo.toml`, TypeScript package manifests, and the TypeScript package lockfile 4. Release notes exist at `docs/releases/vX.Y.Z.md` 5. Local/remote sync (no unpushed or unpulled commits) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index a1608cd..40ad907 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -6,6 +6,28 @@ --- +## v0.2.5 — 2026-08-25 + +Patch release for TypeScript package interoperability and SchemaRegistry guidance. + +### Highlights + +- **CommonJS and ESM entrypoints**: `@3leaps/ipcprims` now exposes explicit conditional exports with matching declaration files. ESM consumers can use named imports while CommonJS `require()` remains supported. +- **SchemaRegistry guide**: new documentation covers configuration defaults, strict-mode behavior, safe directory loading, Rust peer integration, CLI validation, and standalone TypeScript validation. + +### Compatibility + +- **Node.js**: the TypeScript package continues to require Node.js 20+. +- **Runtime behavior**: no wire format, peer transport, or SchemaRegistry runtime behavior changed. + +### Known Issues + +- **NAPI-RS major update deferred**: `@napi-rs/cli` 3.x and Rust `napi`/`napi-derive` 3.x remain on 2.x. + +Full release details: [docs/releases/v0.2.5.md](docs/releases/v0.2.5.md) + +--- + ## v0.2.4 — 2026-08-21 Patch release for a compatible Rust lockfile refresh, including `h2` 0.4.18 on the schema HTTP resolver path. @@ -55,27 +77,3 @@ Fast-follow release for dependency hygiene, MSRV alignment, and TypeScript runti - **Transitive dep duplication**: `getrandom` (0.2 + 0.3) and `hashbrown` (0.16 + 0.17) remain via the current `jsonschema`/HTTP/TLS graph. No functional impact. Full release details: [docs/releases/v0.2.3.md](docs/releases/v0.2.3.md) - ---- - -## v0.2.2 — 2026-07-06 - -**Breaking wire change for token-authenticated peers:** token-bearing handshakes now encode `auth_token` as bytes rather than a UTF-8 string. No-auth peers remain compatible because the field is omitted, but older token-authenticated peers that send string tokens fail closed. Upgrade both sides together when using token auth. - -This release adds the async TypeScript peer surface and hardens auth-token handling across Rust, C FFI, Go, and TypeScript bindings. - -### Highlights - -- **TypeScript async peer API**: `AsyncPeer`, `AsyncListener`, async receives, async channel receivers, and promise-based send/ping/shutdown are now backed by the Rust async peer implementation. -- **Opaque token bytes**: Auth tokens now cross the Rust handshake, C ABI, Go bindings, and TypeScript bindings as byte buffers instead of strings. -- **Zeroizing ownership**: ipcprims-owned token buffers use zeroizing storage; FFI token retrieval returns caller-owned bytes that must be released with the dedicated zeroizing token free function. -- **Explicit server retrieval**: Server peers expose a distinct no-token state and clear stored token material after retrieval. -- **Binding examples**: Go and TypeScript examples use constant-time comparison patterns with clean length-mismatch rejection before treating a peer as authenticated. - -### Compatibility - -- **Cross-version token-authenticated peers**: No known deployed cross-version token-authenticated peers exist for this release window; consumers using token auth should upgrade both sides together. - -Full release details: [docs/releases/v0.2.2.md](docs/releases/v0.2.2.md) - ---- diff --git a/VERSION b/VERSION index abd4105..3a4036f 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.2.4 +0.2.5 diff --git a/bindings/typescript/npm/darwin-arm64/package.json b/bindings/typescript/npm/darwin-arm64/package.json index 5e4f6b7..7681098 100644 --- a/bindings/typescript/npm/darwin-arm64/package.json +++ b/bindings/typescript/npm/darwin-arm64/package.json @@ -1,6 +1,6 @@ { "name": "@3leaps/ipcprims-darwin-arm64", - "version": "0.2.4", + "version": "0.2.5", "repository": { "type": "git", "url": "git+https://github.com/3leaps/ipcprims.git", diff --git a/bindings/typescript/npm/linux-arm64-gnu/package.json b/bindings/typescript/npm/linux-arm64-gnu/package.json index be1dbf9..2aaf328 100644 --- a/bindings/typescript/npm/linux-arm64-gnu/package.json +++ b/bindings/typescript/npm/linux-arm64-gnu/package.json @@ -1,6 +1,6 @@ { "name": "@3leaps/ipcprims-linux-arm64-gnu", - "version": "0.2.4", + "version": "0.2.5", "repository": { "type": "git", "url": "git+https://github.com/3leaps/ipcprims.git", diff --git a/bindings/typescript/npm/linux-x64-gnu/package.json b/bindings/typescript/npm/linux-x64-gnu/package.json index f70727b..f67624f 100644 --- a/bindings/typescript/npm/linux-x64-gnu/package.json +++ b/bindings/typescript/npm/linux-x64-gnu/package.json @@ -1,6 +1,6 @@ { "name": "@3leaps/ipcprims-linux-x64-gnu", - "version": "0.2.4", + "version": "0.2.5", "repository": { "type": "git", "url": "git+https://github.com/3leaps/ipcprims.git", diff --git a/bindings/typescript/npm/linux-x64-musl/package.json b/bindings/typescript/npm/linux-x64-musl/package.json index d740882..439fdce 100644 --- a/bindings/typescript/npm/linux-x64-musl/package.json +++ b/bindings/typescript/npm/linux-x64-musl/package.json @@ -1,6 +1,6 @@ { "name": "@3leaps/ipcprims-linux-x64-musl", - "version": "0.2.4", + "version": "0.2.5", "repository": { "type": "git", "url": "git+https://github.com/3leaps/ipcprims.git", diff --git a/bindings/typescript/npm/win32-x64-msvc/package.json b/bindings/typescript/npm/win32-x64-msvc/package.json index 52af523..be16b63 100644 --- a/bindings/typescript/npm/win32-x64-msvc/package.json +++ b/bindings/typescript/npm/win32-x64-msvc/package.json @@ -1,6 +1,6 @@ { "name": "@3leaps/ipcprims-win32-x64-msvc", - "version": "0.2.4", + "version": "0.2.5", "repository": { "type": "git", "url": "git+https://github.com/3leaps/ipcprims.git", diff --git a/bindings/typescript/package-lock.json b/bindings/typescript/package-lock.json new file mode 100644 index 0000000..45451a4 --- /dev/null +++ b/bindings/typescript/package-lock.json @@ -0,0 +1,76 @@ +{ + "name": "@3leaps/ipcprims", + "version": "0.2.5", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "@3leaps/ipcprims", + "version": "0.2.5", + "license": "MIT OR Apache-2.0", + "devDependencies": { + "@napi-rs/cli": "^2.18.4", + "@types/node": "^20.19.43", + "typescript": "^6.0.3" + }, + "engines": { + "node": ">=20" + }, + "optionalDependencies": { + "@3leaps/ipcprims-darwin-arm64": "0.2.5", + "@3leaps/ipcprims-linux-arm64-gnu": "0.2.5", + "@3leaps/ipcprims-linux-x64-gnu": "0.2.5", + "@3leaps/ipcprims-linux-x64-musl": "0.2.5", + "@3leaps/ipcprims-win32-x64-msvc": "0.2.5" + } + }, + "node_modules/@napi-rs/cli": { + "version": "2.18.4", + "resolved": "https://registry.npmjs.org/@napi-rs/cli/-/cli-2.18.4.tgz", + "integrity": "sha512-SgJeA4df9DE2iAEpr3M2H0OKl/yjtg1BnRI5/JyowS71tUWhrfSu2LT0V3vlHET+g1hBVlrO60PmEXwUEKp8Mg==", + "dev": true, + "license": "MIT", + "bin": { + "napi": "scripts/index.js" + }, + "engines": { + "node": ">= 10" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/Brooooooklyn" + } + }, + "node_modules/@types/node": { + "version": "20.19.43", + "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.43.tgz", + "integrity": "sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA==", + "dev": true, + "license": "MIT", + "dependencies": { + "undici-types": "~6.21.0" + } + }, + "node_modules/typescript": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz", + "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/undici-types": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", + "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", + "dev": true, + "license": "MIT" + } + } +} diff --git a/bindings/typescript/package.json b/bindings/typescript/package.json index a13c988..b3c8807 100644 --- a/bindings/typescript/package.json +++ b/bindings/typescript/package.json @@ -1,6 +1,6 @@ { "name": "@3leaps/ipcprims", - "version": "0.2.4", + "version": "0.2.5", "description": "TypeScript bindings for ipcprims via Node-API", "license": "MIT OR Apache-2.0", "repository": { @@ -77,11 +77,11 @@ "typecheck": "tsc --noEmit && tsc -p tsconfig.consumer.json" }, "optionalDependencies": { - "@3leaps/ipcprims-linux-x64-gnu": "0.2.4", - "@3leaps/ipcprims-linux-x64-musl": "0.2.4", - "@3leaps/ipcprims-linux-arm64-gnu": "0.2.4", - "@3leaps/ipcprims-darwin-arm64": "0.2.4", - "@3leaps/ipcprims-win32-x64-msvc": "0.2.4" + "@3leaps/ipcprims-linux-x64-gnu": "0.2.5", + "@3leaps/ipcprims-linux-x64-musl": "0.2.5", + "@3leaps/ipcprims-linux-arm64-gnu": "0.2.5", + "@3leaps/ipcprims-darwin-arm64": "0.2.5", + "@3leaps/ipcprims-win32-x64-msvc": "0.2.5" }, "devDependencies": { "@napi-rs/cli": "^2.18.4", diff --git a/crates/ipcprims-schema/src/lib.rs b/crates/ipcprims-schema/src/lib.rs index ddddf9d..657f19f 100644 --- a/crates/ipcprims-schema/src/lib.rs +++ b/crates/ipcprims-schema/src/lib.rs @@ -1,4 +1,12 @@ -#![doc = include_str!("../../../docs/guides/schema-registry.md")] +//! Optional JSON Schema validation at the IPC transport boundary. +//! +//! Validate messages against JSON Schema 2020-12 at the frame level. +//! Applications that do not attach a registry perform no schema validation. +//! +//! See the [Schema Registry Guide] for configuration, directory loading, and +//! peer integration details. +//! +//! [Schema Registry Guide]: https://github.com/3leaps/ipcprims/blob/main/docs/guides/schema-registry.md pub mod config; pub mod error; diff --git a/docs/guides/schema-registry.md b/docs/guides/schema-registry.md index 508a8da..7783ae2 100644 --- a/docs/guides/schema-registry.md +++ b/docs/guides/schema-registry.md @@ -27,7 +27,7 @@ Add the schema crate directly when validation is needed: ```toml [dependencies] -ipcprims-schema = "0.2.4" +ipcprims-schema = "0.2.5" ``` Create a registry, then register JSON Schema text or a parsed @@ -157,15 +157,15 @@ configuration functions. ```toml [dependencies] -ipcprims-peer = { version = "0.2.4", features = ["schema"] } -ipcprims-schema = "0.2.4" +ipcprims-peer = { version = "0.2.5", features = ["schema"] } +ipcprims-schema = "0.2.5" ``` Add the `async` feature when using `AsyncPeerListener` or `async_connect_with_config`: ```toml -ipcprims-peer = { version = "0.2.4", features = ["schema", "async"] } +ipcprims-peer = { version = "0.2.5", features = ["schema", "async"] } ``` Create the registry with `Arc::new`, then pass a clone to diff --git a/docs/releases/v0.2.5.md b/docs/releases/v0.2.5.md new file mode 100644 index 0000000..75a2167 --- /dev/null +++ b/docs/releases/v0.2.5.md @@ -0,0 +1,26 @@ +# ipcprims v0.2.5 + +> Released: 2026-08-25 + +Patch release for TypeScript package interoperability and SchemaRegistry guidance. + +## Highlights + +- **Dual CommonJS/ESM package surface**: `@3leaps/ipcprims` provides explicit conditional exports and matching declaration files. ESM consumers can use named imports, while CommonJS `require()` remains supported. +- **SchemaRegistry guide**: documents configuration defaults, strict-mode behavior, bounded directory loading, peer integration, CLI validation, and standalone TypeScript validation. + +## Compatibility + +- **Node.js**: the TypeScript package continues to require Node.js 20+. +- **CommonJS**: existing `require()` consumers remain supported. +- **Protocol behavior**: no wire format, peer transport, or SchemaRegistry runtime behavior changed. + +## Deferred + +- **NAPI-RS major line**: `@napi-rs/cli` 3.x and Rust `napi`/`napi-derive` 3.x remain deferred. + +## Verification + +- `make prepush` +- `make release-check` +- `make version-check` diff --git a/scripts/check-version.sh b/scripts/check-version.sh index 919486f..acc7952 100755 --- a/scripts/check-version.sh +++ b/scripts/check-version.sh @@ -178,6 +178,26 @@ if [[ -f "$TS_ROOT/package.json" ]]; then fi fi done + + # Keep the committed npm lockfile aligned with the published package version. + if [[ -f "$TS_ROOT/package-lock.json" ]]; then + LOCK_VERSION=$(grep '"version"' "$TS_ROOT/package-lock.json" | head -1 | sed 's/.*"\([0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*\)".*/\1/') + if [[ "$LOCK_VERSION" == "$VERSION_FROM_FILE" ]]; then + ok " typescript/package-lock.json: $LOCK_VERSION" + else + error " typescript/package-lock.json: $LOCK_VERSION (expected $VERSION_FROM_FILE)" + TS_FAILED+=("bindings/typescript/package-lock.json") + fi + + while IFS= read -r line; do + dep_ver=$(echo "$line" | sed 's/.*": "\([0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*\)".*/\1/') + dep_name=$(echo "$line" | sed 's/.*"\(@3leaps\/[^" ]*\)".*/\1/') + if [[ "$dep_ver" != "$VERSION_FROM_FILE" ]]; then + error " lockfile optionalDependency $dep_name: $dep_ver (expected $VERSION_FROM_FILE)" + TS_FAILED+=("package-lock/$dep_name") + fi + done < <(grep '@3leaps/ipcprims-' "$TS_ROOT/package-lock.json") + fi fi if [[ ${#TS_FAILED[@]} -gt 0 ]]; then From 73058b65f579c6ca647cd107e7015223f1310143 Mon Sep 17 00:00:00 2001 From: Dave Thompson Date: Tue, 25 Aug 2026 07:56:16 -0400 Subject: [PATCH 2/2] docs(readme): document TypeScript module usage Generated by GPT-5.6 Terra via OpenCode under supervision of @3leapsdave Co-Authored-By: GPT-5.6 Terra Role: devlead Committer-of-Record: Dave Thompson [@3leapsdave] --- README.md | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 08f7176..e7e3d79 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ You're building software where multiple processes need to communicate locally - **Cross-platform**: Unix domain sockets on Linux/macOS and Windows named pipes. - **Sync + Async (Tokio)**: Blocking sync API plus Tokio-native async API behind `async` feature flag. Windows sync named pipes use overlapped I/O for timeout enforcement; Windows async named pipes are also supported. - **Library-first**: Embed directly in Rust, Go, Python, or TypeScript. CLI is a diagnostic/demo tool. +- **TypeScript module flexibility**: ESM named imports and CommonJS `require()` from a single Node-API package (Node.js 20+). ### Framed-by-Default: The Core Difference @@ -132,6 +133,39 @@ async fn main() -> Result<(), Box> { } ``` +### As a TypeScript Library (ESM) + +The package supports ESM named imports and CommonJS `require()` from the same +install. Node.js 20+ required. + +```ts +import { AsyncListener, AsyncPeer, COMMAND } from "@3leaps/ipcprims"; + +const listener = AsyncListener.bind("/tmp/ipcprims.sock", { + channels: [COMMAND], +}); + +const accepted = listener.accept(); +const client = await AsyncPeer.connect("/tmp/ipcprims.sock", [COMMAND]); +const server = await accepted; + +await server.send(COMMAND, Buffer.from("hello")); +const frame = await client.recvAsync(); + +client.close(); +server.close(); +await listener.close(); +``` + +CommonJS consumers keep working unchanged: + +```js +const { Peer, COMMAND } = require("@3leaps/ipcprims"); +``` + +See the [TypeScript binding guide](bindings/typescript/README.md) for async +receivers, auth-token handling, and SchemaRegistry usage. + ### As a CLI ```bash @@ -227,7 +261,7 @@ The module follows sibling-repo layout conventions with `include/` (generated he ### TypeScript bindings -TypeScript bindings scaffold is provided at `bindings/typescript` using Node-API (`ipcprims-napi`). +The `@3leaps/ipcprims` package (Node-API) ships an explicit dual CommonJS/ESM surface with matching declaration files. ESM consumers can use named imports (`import { AsyncPeer, COMMAND } from "@3leaps/ipcprims"`) while CommonJS `require()` remains fully supported from the same package — no separate package or build step. Requires Node.js 20+. See the [TypeScript binding guide](bindings/typescript/README.md) for async peer, auth-token, and SchemaRegistry usage. ## Platform Support