@tsonic/express 10.0.22 → 10.0.24

package/README.md

@@ -33,6 +33,7 @@ export function main(): void {
 
   app.listen(3000);
 }
+
 EOF
 
 npm run dev
@@ -55,6 +56,7 @@ export function main(): void {
 
   app.listen(3000);
 }
+
 ```
 
 ## Basic API Surface
@@ -66,6 +68,7 @@ import { express } from "@tsonic/express/index.js";
 
 const app = express.create();
 const router = express.Router();
+
 ```
 
 ### Routing
@@ -75,10 +78,11 @@ Common verbs:
 ```ts
 app.get("/health", (_req, res) => res.send("ok"));
 app.post("/items", (req, res) => res.json(req.body));
-app.put("/items/:id", (req, res) => res.send(req.params["id"]));
+app.put("/items/:id", (req, res) => res.send(req.param("id")));
 app.delete("/items/:id", (_req, res) => res.sendStatus(204));
 app.patch("/items/:id", (_req, res) => res.sendStatus(204));
 app.all("/anything", (_req, res) => res.send("matched"));
+
 ```
 
 ### Middleware
@@ -88,12 +92,13 @@ app.use((req, _res, next) => {
   // Do something with req
   next();
 });
+
 ```
 
 Error middleware:
 
 ```ts
-app.use((err, _req, res, _next) => {
+app.useError((err, _req, res, _next) => {
   res.status(500).json({ error: `${err}` });
 });
 ```
@@ -122,12 +127,14 @@ app.use(express.json());
 app.use(express.urlencoded());
 app.use(express.text());
 app.use(express.raw());
+
 ```
 
 ### Static files
 
 ```ts
 app.use(express.static("./public"));
+
 ```
 
 ### Listen / close
@@ -135,6 +142,7 @@ app.use(express.static("./public"));
 ```ts
 const server = app.listen(3000);
 server.close();
+
 ```
 
 ## Advanced docs
@@ -152,3 +160,5 @@ This repo is versioned by runtime major:
 ## License
 
 MIT
+
+

package/docs/advanced.md

@@ -0,0 +1,109 @@
+# Advanced usage (`@tsonic/express`)
+
+This doc covers patterns that go beyond “hello world”.
+
+For known compatibility gaps vs Express/Node, see `docs/deviations.md`.
+
+## Routers
+
+Use routers to structure your app:
+
+```ts
+import { express } from "@tsonic/express/index.js";
+
+export function main(): void {
+  const app = express.create();
+
+  const api = express.Router();
+  api.get("/health", (_req, res) => res.send("ok"));
+
+  app.use("/api", api);
+  app.listen(3000);
+}
+```
+
+## Middleware ordering
+
+Middlewares run in the order you register them:
+
+```ts
+app.use((req, _res, next) => {
+  // pre
+  next();
+  // post
+});
+```
+
+## Error middleware
+
+Error handlers have `(err, req, res, next)` shape:
+
+```ts
+app.useError((err, _req, res, _next) => {
+  res.status(500).json({ error: `${err}` });
+});
+```
+
+## Handler return types (sync vs async)
+
+Handlers can be synchronous:
+
+```ts
+app.get("/", (_req, res) => {
+  res.send("ok");
+});
+```
+
+Or `async`:
+
+```ts
+app.get("/slow", async (_req, res) => {
+  // await something
+  res.send("done");
+});
+```
+
+## Body parsing options
+
+The built-in body parsers return request handlers:
+
+```ts
+app.use(express.json());
+app.use(express.urlencoded());
+app.use(express.text());
+app.use(express.raw());
+```
+
+Most options types are exported from `@tsonic/express/index.js`:
+
+```ts
+import { express, JsonOptions } from "@tsonic/express/index.js";
+
+const json = new JsonOptions();
+// set options here
+app.use(express.json(json));
+```
+
+## Static files
+
+```ts
+app.use(express.static("./public"));
+```
+
+## Response helpers
+
+Common response patterns:
+
+```ts
+res.status(200).json({ ok: true });
+res.sendStatus(204);
+res.redirect("/login");
+res.set("x-powered-by", "tsonic");
+```
+
+## Cookies
+
+```ts
+res.cookie("sid", "abc123");
+res.clearCookie("sid");
+```

package/docs/deviations.md

@@ -0,0 +1,20 @@
+# Express Compatibility Deviations
+
+This package reflects the `express-clr` runtime behavior.
+
+Authoritative deviations live in:
+
+- `../express-clr/docs/deviations.md`
+
+Key current items:
+
+1. `express()` callable form is represented as `express.create()` / `express.app()`.
+2. C#-safe method names are used for some verbs (`lock_`, `m_search`), with `method("...")` for exact-verb routing.
+3. `next('router')` remains best-effort under flattened mount behavior.
+4. Advanced path-pattern behavior is best-effort; common string and `:param` patterns are covered.
+5. Built-in parser/static middleware behavior is close, not byte-for-byte identical to upstream Node middleware internals.
+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.
+
+Deviations should shrink over time and are validated through the runtime test matrix in `express-clr`.

package/docs/generation.md

@@ -0,0 +1,47 @@
+# Generation Workflow
+
+This repository publishes generated TypeScript bindings for `express-clr`.
+
+## Prerequisites
+
+- `../express-clr` exists and is built in `Release`.
+- `../tsbindgen` exists and builds.
+- `../dotnet/versions/<major>` exists.
+- `../aspnetcore` exists.
+- Local .NET runtime and ASP.NET runtime are installed under `$DOTNET_HOME` (default `$HOME/.dotnet`).
+
+## Generate for .NET 10
+
+```bash
+npm run generate:10
+```
+
+Equivalent script:
+
+```bash
+./__build/scripts/generate.sh 10
+```
+
+## What the Script Does
+
+1. Validates dependencies and runtime paths.
+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:
+   - `index.d.ts`
+   - `index.js`
+   - `index/bindings.json`
+   - `index/internal/index.d.ts`
+   - `families.json`
+   - `package.json`
+   - `README.md`
+   - `LICENSE`
+
+## Environment Overrides
+
+- `DOTNET_HOME`
+- `DOTNET_VERSION`
+
+Use these when runtime paths are non-default.

package/docs/release.md

@@ -0,0 +1,37 @@
+# Release Workflow
+
+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:
+
+```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:
+
+```bash
+npm run publish:10
+```
+
+## Post-Publish Checks
+
+- Confirm npm package page for `@tsonic/express`.
+- Verify install from a clean sample:
+
+```bash
+npm i @tsonic/express@10
+```
+
+- Smoke-check import and basic usage.
+
+## Notes
+
+- Runtime behavior changes belong to `express-clr`.
+- This repo should only contain generated API/package-facing artifacts and docs.

package/docs/snippets/10/body-parsing.ts

@@ -0,0 +1,5 @@
+app.use(express.json());
+app.use(express.urlencoded());
+app.use(express.text());
+app.use(express.raw());
+

package/docs/snippets/10/create-app-router.ts

@@ -0,0 +1,3 @@
+const app = express.create();
+const router = express.Router();
+

package/docs/snippets/10/error-middleware.ts

@@ -0,0 +1,3 @@
+app.useError((err, _req, res, _next) => {
+  res.status(500).json({ error: `${err}` });
+});

package/docs/snippets/10/hello-world-app.ts

@@ -0,0 +1,12 @@
+import { express } from "@tsonic/express/index.js";
+
+export function main(): void {
+  const app = express.create();
+
+  app.get("/", (_req, res) => {
+    res.send("hello");
+  });
+
+  app.listen(3000);
+}
+

package/docs/snippets/10/listen-close.ts

@@ -0,0 +1,3 @@
+const server = app.listen(3000);
+server.close();
+

package/docs/snippets/10/middleware.ts

@@ -0,0 +1,5 @@
+app.use((req, _res, next) => {
+  // Do something with req
+  next();
+});
+

package/docs/snippets/10/quick-start-app.ts

@@ -0,0 +1,12 @@
+import { express } from "@tsonic/express/index.js";
+
+export function main(): void {
+  const app = express.create();
+
+  app.get("/", (_req, res) => {
+    res.json({ ok: true });
+  });
+
+  app.listen(3000);
+}
+

package/docs/snippets/10/routing.ts

@@ -0,0 +1,7 @@
+app.get("/health", (_req, res) => res.send("ok"));
+app.post("/items", (req, res) => res.json(req.body));
+app.put("/items/:id", (req, res) => res.send(req.param("id")));
+app.delete("/items/:id", (_req, res) => res.sendStatus(204));
+app.patch("/items/:id", (_req, res) => res.sendStatus(204));
+app.all("/anything", (_req, res) => res.send("matched"));
+

package/docs/snippets/10/static-files.ts

@@ -0,0 +1,2 @@
+app.use(express.static("./public"));
+