@nxgt/janus-hono 0.3.5 → 0.3.6

package/README.md

@@ -60,9 +60,29 @@ declarations import without extensions, so `nodenext` is not supported.
 | `bindJanus({ auth?, access? })` | The functions above with the instances bound: `session(options?)`, `sendSession(c, signedIn)` and `signOut(c)` with `auth`; `permission(permission, type, load, options?)` with `access`; `provide()` always |
 | `provide({ auth?, access? })` | Middleware. Sets `c.var.auth` and `c.var.access` to the instances given — only those — for a route that writes users or tuples |
 | `ObjectData<C, Type>`, `PermissionOptions`, `Instances` | The types of `load`'s answer, of `permission()`'s options and of `provide()`'s argument |
+| `JanusErrorsOptions` | `{ report?, fallback? }`, the options of `janusErrors()` — for a wrapper of your own |
+| `Bound<I>` | What `bindJanus(instances)` answers, for `I` the type of `instances` — to pass a bound `j` to a module of routes |
+| `Bindable` | What `bindJanus()` takes: `{ auth?, access? }`, the constraint on `Bound`'s `I` |
+| `BoundAuth<typeof auth>` | The part of `Bound` that `auth` brings: `session`, `sendSession` and `signOut` |
+| `BoundSession<typeof auth>` | `j.session`: `session(auth, options?)` with `auth` bound, typed as `session()` is — `{ required: true }` types `c.var.user` as never `null` |
+| `BoundPermission<C>` | `j.permission`: `permission(access, …)` with `access` bound, for `C` the model's config: `ConfigOf<typeof model>` from `@nxgt/janus/permissions`, or take the whole type as `Bound<…>['permission']` |
 
 The whole status table is in [`@nxgt/janus`'s errors guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/errors.md).
 
+### A wrapper of your own
+
+A wrapper around `janusErrors()` takes the same options, with your defaults:
+
+```ts
+import { type JanusErrorsOptions, janusErrors } from '@nxgt/janus-hono';
+import { logger } from './logger'; // your own
+
+export const appErrors = (options: JanusErrorsOptions = {}) =>
+	janusErrors({ report: (error) => logger.error(error), ...options });
+
+app.onError(appErrors());
+```
+
 ## Second factor
 
 With `janus({ secondFactor })`, `signIn` answers a session or a challenge.
@@ -165,6 +185,24 @@ const app = new Hono()
 
 Only what is given is bound: `bindJanus({ auth })` has no `permission`.
 
+A module of routes that receives `j` types it `Bound<…>`, over the types of
+the instances it was given:
+
+```ts
+import { type Bound, bindJanus, byParam } from '@nxgt/janus-hono';
+
+export type Janus = Bound<{ auth: typeof auth; access: typeof access }>;
+
+export const recordRoutes = (j: Janus) =>
+	new Hono()
+		.use(j.session(), j.provide())
+		.get('/records/:id', j.permission('view', 'record', byParam('id', (id) => records.find(id))), (c) =>
+			c.json(c.var.object), // typed, as with the unbound functions
+		);
+
+app.route('/', recordRoutes(bindJanus({ auth, access })));
+```
+
 Each side is usable alone. An application that signs users in some other way
 passes `{ subject: (c) => … }` to `permission()`; one without permissions uses
 `session()` and `janusErrors()` only.

package/docs/guide/routes.md

@@ -39,6 +39,16 @@ app.onError((error, c) => {
 an `HTTPException` answers its own response and anything else is a logged
 500, as Hono does by default.
 
+A wrapper around `janusErrors()` takes the same options, `JanusErrorsOptions`,
+with your defaults:
+
+```ts
+import { type JanusErrorsOptions, janusErrors } from '@nxgt/janus-hono';
+
+export const appErrors = (options: JanusErrorsOptions = {}) =>
+	janusErrors({ report: (error) => logger.error(error), ...options });
+```
+
 ### Binding the instances once
 
 Every function of this package takes `auth` or `access` first.
@@ -57,6 +67,27 @@ app.post('/sign-in', async (c) => {
 });
 ```
 
+A module of routes that receives `j` rather than importing it types it
+`Bound<…>`, over the types of the instances it was given — only what is given
+is bound, so `Bound<{ auth: typeof auth }>` has no `permission`:
+
+```ts
+import { type Bound, byParam } from '@nxgt/janus-hono';
+
+export type Janus = Bound<{ auth: typeof auth; access: typeof access }>;
+
+export const recordRoutes = (j: Janus) =>
+	new Hono()
+		.use(j.session(), j.provide())
+		.get('/records/:id', j.permission('view', 'record', byParam('id', (id) => records.find(id))), (c) =>
+			c.json(c.var.object),
+		);
+```
+
+`BoundSession`, `BoundAuth` and `BoundPermission` are its parts — `j.session`,
+the three functions `auth` brings, and `j.permission` — for a helper that needs
+only one of them.
+
 The rest of this guide writes the unbound form; each call reads the same with
 `j.` and without its first argument.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/janus-hono",
-	"version": "0.3.5",
+	"version": "0.3.6",
 	"description": "Hono middleware for @nxgt/janus: the signed-in user on every request, the session cookie, routes guarded by a permission, and every error as its status",
 	"license": "MIT",
 	"type": "module",
@@ -49,13 +49,13 @@
 		]
 	},
 	"devDependencies": {
-		"@nxgt/janus": "^0.10.0",
+		"@nxgt/janus": "^0.11.0",
 		"@types/bun": "^1.4.2",
 		"hono": "^4.13.9",
 		"zod": "^4.6.5"
 	},
 	"peerDependencies": {
-		"@nxgt/janus": "^0.10.0",
+		"@nxgt/janus": "^0.11.0",
 		"hono": "^4.13.4",
 		"typescript": "^6.0.3"
 	}