@tsonic/express 10.0.25 → 10.0.27

package/README.md

@@ -27,13 +27,12 @@ import { express } from "@tsonic/express/index.js";
 export function main(): void {
   const app = express.create();
 
-  app.get("/", (_req, res) => {
+  app.get("/", async (_req, res, _next) => {
     res.json({ ok: true });
   });
 
   app.listen(3000);
 }
-
 EOF
 
 npm run dev
@@ -50,17 +49,24 @@ import { express } from "@tsonic/express/index.js";
 export function main(): void {
   const app = express.create();
 
-  app.get("/", (_req, res) => {
+  app.get("/", async (_req, res, _next) => {
     res.send("hello");
   });
 
   app.listen(3000);
 }
-
 ```
 
 ## Basic API Surface
 
+## Handler model (important)
+
+This package is **Task-first** (like ASP.NET): route handlers and middleware should be written as **`async`** functions (even if you don't `await` anything).
+
+This avoids “async-void” behavior and keeps execution/exception semantics deterministic.
+
+Also, handlers use the **3-argument** signature: `(req, res, next)` (even for routes). If you don't need `next`, name it `_next`.
+
 ### Create an app / router
 
 ```ts
@@ -69,6 +75,11 @@ import { express } from "@tsonic/express/index.js";
 const app = express.create();
 const router = express.Router();
 
+router.get("/ping", async (_req, res, _next) => {
+  res.send("pong");
+});
+
+app.use("/api", router);
 ```
 
 ### Routing
@@ -76,29 +87,59 @@ const router = express.Router();
 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.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"));
-
+app.get("/health", async (_req, res, _next) => {
+  res.send("ok");
+});
+app.post("/items", async (req, res, _next) => {
+  res.json(req.body);
+});
+app.put("/items/:id", async (req, res, _next) => {
+  res.send(req.params["id"] ?? "");
+});
+app.delete("/items/:id", async (_req, res, _next) => {
+  res.sendStatus(204);
+});
+app.patch("/items/:id", async (_req, res, _next) => {
+  res.sendStatus(204);
+});
+app.all("/anything", async (_req, res, _next) => {
+  res.send("matched");
+});
 ```
 
 ### Middleware
 
 ```ts
-app.use((req, _res, next) => {
+app.use(async (req, _res, next) => {
   // Do something with req
-  next();
+  await next();
+});
+```
+
+### CORS
+
+```ts
+app.use(express.cors());
+
+```
+
+### Cookies
+
+```ts
+app.get("/set-cookie", async (_req, res, _next) => {
+  res.cookie("sid", "abc");
+  res.send("ok");
 });
 
+app.get("/read-cookie", async (req, res, _next) => {
+  res.json({ sid: req.cookies["sid"] });
+});
 ```
 
 Error middleware:
 
 ```ts
-app.useError((err, _req, res, _next) => {
+app.useError(async (err, _req, res, _next) => {
   res.status(500).json({ error: `${err}` });
 });
 ```
@@ -108,7 +149,7 @@ app.useError((err, _req, res, _next) => {
 `Request` highlights:
 
 - `req.method`, `req.path`, `req.originalUrl`
-- `req.query`, `req.params`
+- `req.query`, `req.params`, `req.cookies`, `req.signedCookies`
 - `req.body` (when using body parsers)
 - `req.get(name)` / `req.header(name)`
 
@@ -130,6 +171,19 @@ app.use(express.raw());
 
 ```
 
+### Multipart / file uploads
+
+```ts
+const upload = express.multipart();
+
+app.post("/upload", upload.single("avatar"), async (req, res, _next) => {
+  res.json({
+    filename: req.file?.originalname,
+    fields: req.body,
+  });
+});
+```
+
 ### Static files
 
 ```ts
@@ -161,4 +215,3 @@ This repo is versioned by runtime major:
 
 MIT
 
-

package/docs/snippets/10/cookies.ts

@@ -0,0 +1,8 @@
+app.get("/set-cookie", async (_req, res, _next) => {
+  res.cookie("sid", "abc");
+  res.send("ok");
+});
+
+app.get("/read-cookie", async (req, res, _next) => {
+  res.json({ sid: req.cookies["sid"] });
+});

package/docs/snippets/10/cors.ts

@@ -0,0 +1,2 @@
+app.use(express.cors());
+

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

@@ -1,3 +1,8 @@
 const app = express.create();
 const router = express.Router();
 
+router.get("/ping", async (_req, res, _next) => {
+  res.send("pong");
+});
+
+app.use("/api", router);

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

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

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

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

package/docs/snippets/10/middleware.ts

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

package/docs/snippets/10/multipart.ts

@@ -0,0 +1,8 @@
+const upload = express.multipart();
+
+app.post("/upload", upload.single("avatar"), async (req, res, _next) => {
+  res.json({
+    filename: req.file?.originalname,
+    fields: req.body,
+  });
+});

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

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

package/docs/snippets/10/routing.ts

@@ -1,7 +1,18 @@
-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"));
-
+app.get("/health", async (_req, res, _next) => {
+  res.send("ok");
+});
+app.post("/items", async (req, res, _next) => {
+  res.json(req.body);
+});
+app.put("/items/:id", async (req, res, _next) => {
+  res.send(req.params["id"] ?? "");
+});
+app.delete("/items/:id", async (_req, res, _next) => {
+  res.sendStatus(204);
+});
+app.patch("/items/:id", async (_req, res, _next) => {
+  res.sendStatus(204);
+});
+app.all("/anything", async (_req, res, _next) => {
+  res.send("matched");
+});