@tsonic/express 10.0.37 → 10.0.39

package/README.md

@@ -6,6 +6,12 @@ This package is part of Tsonic: https://tsonic.org.
 
 Use this package to write Express-like apps in TypeScript and compile them to native binaries with `tsonic`.
 
+The project surface should be `@tsonic/js`. `@tsonic/express` remains a normal imported package, but its public API is JS-facing:
+
+- `Date`, `Uint8Array`, `number`
+- `Record<string, ...>` and arrays
+- no CLR collection/runtime types in the TS-facing contract
+
 ## Prerequisites
 
 - Install the .NET 10 SDK (required by Tsonic): https://dotnet.microsoft.com/download
@@ -15,7 +21,7 @@ Use this package to write Express-like apps in TypeScript and compile them to na
 
 ```bash
 mkdir my-api && cd my-api
-npx --yes tsonic@latest init
+npx --yes tsonic@latest init --surface @tsonic/js
 
 # Install Express runtime + bindings (installs required ASP.NET Core deps too)
 npx --yes tsonic@latest add npm @tsonic/express

package/docs/deviations.md

@@ -2,6 +2,8 @@
 
 This package reflects the `express-clr` runtime behavior.
 
+The TS-facing contract is JS-native even though the runtime implementation is CLR-backed. That means some deviations are about runtime semantics, not about leaking CLR types into authored TypeScript.
+
 Authoritative deviations live in:
 
 - `../express-clr/docs/deviations.md`
@@ -16,5 +18,6 @@ Key current items:
 6. Cookie signing/signed-cookie behavior is best-effort, not a full `cookie-parser` edge-case clone.
 7. Handler dispatch in runtime is reflection-free; unsupported delegate signatures are ignored instead of reflection invocation.
 8. Runtime JSON support is reflection-free and guarantees primitives, dictionaries, arrays/lists, and `JsonElement`/`JsonDocument` shapes. Arbitrary CLR object/anonymous-object reflection serialization is intentionally not provided.
+9. Public package types intentionally use JS-native shapes (`Date`, `Uint8Array`, `Record<string, ...>`, `number`, `Promise<...>`) even when the runtime uses validated CLR backing types internally.
 
 Deviations should shrink over time and are validated through the runtime test matrix in `express-clr`.

package/docs/generation.md

@@ -2,6 +2,12 @@
 
 This repository publishes generated TypeScript bindings for `express-clr`.
 
+The generated package is intentionally JS-facing:
+
+- JS-surface ambient types come from `@tsonic/js`
+- `@tsonic/express` stays a normal package
+- generated `.d.ts` must not leak CLR collection/runtime types
+
 ## Prerequisites
 
 - `../express-clr` exists and is built in `Release`.
@@ -28,8 +34,10 @@ Equivalent script:
 2. Cleans `versions/<major>/` generated output.
 3. Builds `tsbindgen` in `Release`.
 4. Generates bindings from `express-clr` assembly.
-5. Copies `README.md` and `LICENSE`.
-6. Prunes output to package-focused files:
+5. Post-processes the generated declarations into a JS-native surface.
+6. Syncs package metadata and runtime package version.
+7. Copies `README.md` and `LICENSE`.
+8. Prunes output to package-focused files:
    - `index.d.ts`
    - `index.js`
    - `index/bindings.json`
@@ -39,6 +47,8 @@ Equivalent script:
    - `README.md`
    - `LICENSE`
 
+Post-processing is not optional. It is part of the contract: the published package must expose JS-native types (`Date`, `Uint8Array`, `Record<string, ...>`, `number`, `Promise<...>`) rather than raw CLR/tsbindgen internals.
+
 ## Environment Overrides
 
 - `DOTNET_HOME`

package/docs/release.md

@@ -5,16 +5,31 @@ This repo publishes one package per .NET major under `versions/<major>/`.
 ## .NET 10 Release Steps
 
 1. Ensure `express-clr` changes are merged and pulled to `main`.
-2. Regenerate bindings:
+2. Run the publish gate:
+
+```bash
+npm run selftest
+```
+
+This gate must pass before publish. It covers:
+
+- `dotnet test` in `express-clr`
+- `dotnet pack` in `express-clr`
+- regeneration in this repo
+- README/doc checks
+- generated-surface contract checks
+- JS-surface E2E from `tsonic init --surface @tsonic/js`
+
+3. Regenerate bindings if needed:
 
 ```bash
 npm run generate:10
 ```
 
-3. Review generated diffs in `versions/10/`.
-4. Update `versions/10/package.json` version if needed.
-5. Validate package metadata and README.
-6. Publish:
+4. Review generated diffs in `versions/10/`.
+5. Update `versions/10/package.json` version if needed.
+6. Validate package metadata and README.
+7. Publish:
 
 ```bash
 npm run publish:10
@@ -35,3 +50,4 @@ npm i @tsonic/express@10
 
 - Runtime behavior changes belong to `express-clr`.
 - This repo should only contain generated API/package-facing artifacts and docs.
+- JS-surface correctness is part of the publish contract, not a best-effort property.

package/families.json

@@ -47,5 +47,12 @@
     "minArity": 1,
     "maxArity": 6,
     "isDelegate": false
+  },
+  "Tsonic.Runtime.Union": {
+    "stem": "Union",
+    "namespace": "Tsonic.Runtime",
+    "minArity": 2,
+    "maxArity": 8,
+    "isDelegate": false
   }
 }