@softistx/janus-kit 0.0.0-stage → 0.6.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,490 @@
1
+ # Troubleshooting `@softistx/janus-kit`
2
+
3
+ Installing `@softistx/janus*` fails with a 401 or 404? See
4
+ [the install entry](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md#installing-softistx-packages).
5
+
6
+ Each entry is headed by the text you see: a compiler error or a message.
7
+ Search this page for the words of your message.
8
+
9
+ The kit **defines no error class**. A configuration it refuses is a
10
+ `TypeError`, from `defineConfig` or from `connectKit`, which checks it again;
11
+ a database it cannot reach is an `Error` from `connectKit`, whose `cause` is
12
+ what the driver threw. Once
13
+ connected, every error is `@softistx/janus`'s, as documented in
14
+ [`@softistx/janus`'s troubleshooting](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md)
15
+ and its adapters'.
16
+
17
+ ## Index
18
+
19
+ **Install**
20
+ - [Optional peers are installed as required](#optional-peers-are-installed-as-required)
21
+
22
+ **Types**
23
+ - [`TS2307: Cannot find module '@softistx/janus-kit' or its corresponding type declarations.`](#ts2307-cannot-find-module-nxgtjanus-kit-or-its-corresponding-type-declarations)
24
+ - [`TS2339: Property 'access' does not exist on type 'Kit<…>'.`](#ts2339-property-access-does-not-exist-on-type-kit)
25
+ - [`TS2322: Type '{ url: string; db: PgDatabase; }' is not assignable to type 'PostgresConfig'.`](#ts2322-type--url-string-db-pgdatabase--is-not-assignable-to-type-postgresconfig)
26
+ - [`TS2322: Type '{ url: string; db: Db; }' is not assignable to type 'MongoConfig'.`](#ts2322-type--url-string-db-db--is-not-assignable-to-type-mongoconfig)
27
+ - [`TS2322: Type '{ db: Db; clientOptions: …; }' is not assignable to type 'MongoConfig'.`](#ts2322-type--db-db-clientoptions---is-not-assignable-to-type-mongoconfig)
28
+ - [`TS2353: Object literal may only specify known properties, and 'postgres' does not exist in type 'KitConfig<object, never>'.`](#ts2353-object-literal-may-only-specify-known-properties-and-postgres-does-not-exist-in-type-kitconfigobject-never)
29
+ - [`TS2339: Property 'postgres' does not exist on type 'HealthOf<"mongo">'.`](#ts2339-property-postgres-does-not-exist-on-type-healthofmongo)
30
+ - [`TS2322: Type 'RedisConnection' is not assignable to type 'undefined'.`](#ts2322-type-redisconnection-is-not-assignable-to-type-undefined)
31
+ - [`TS2353: Object literal may only specify known properties, and 'schema' does not exist in type …`](#ts2353-object-literal-may-only-specify-known-properties-and-schema-does-not-exist-in-type-)
32
+ - [`TS2345: Argument of type '{ postgres: …; }' is not assignable to parameter of type 'KitConfig<object, never>'.`](#ts2345-argument-of-type--postgres---is-not-assignable-to-parameter-of-type-kitconfigobject-never)
33
+ - [`TS2322: Type 'string' is not assignable to type 'boolean'.`](#ts2322-type-string-is-not-assignable-to-type-boolean)
34
+
35
+ **Starting**
36
+ - [`defineConfig: …`](#defineconfig-)
37
+ - [`connectKit: Janus's tables are missing from this database: …`](#connectkit-januss-tables-are-missing-from-this-database-)
38
+ - [`connectKit: PostgreSQL did not answer. …`](#connectkit-postgresql-did-not-answer-)
39
+ - [`` connectKit: the Drizzle instance in `postgres.db` did not answer. ``](#connectkit-the-drizzle-instance-in-postgresdb-did-not-answer)
40
+ - [`connectKit: Janus's collections are not in sync with @softistx/janus-mongo: …`](#connectkit-januss-collections-are-not-in-sync-with-nxgtjanus-mongo-)
41
+ - [`connectKit: Janus's collections differ from this @softistx/janus-mongo's definitions: …`, a process warning](#connectkit-januss-collections-differ-from-this-nxgtjanus-mongos-definitions--a-process-warning)
42
+ - [`connectKit: MongoDB did not answer. …`](#connectkit-mongodb-did-not-answer-)
43
+ - [`` TypeError: connectKit: `mongo.url` is not a connection string the driver can read. ``](#typeerror-connectkit-mongourl-is-not-a-connection-string-the-driver-can-read)
44
+ - [`` connectKit: the Db in `mongo.db` did not answer. ``](#connectkit-the-db-in-mongodb-did-not-answer)
45
+ - [`TypeError: connectMongo: this URI is already connected with other options. …`](#typeerror-connectmongo-this-uri-is-already-connected-with-other-options-)
46
+ - [`connectKit: Redis did not answer. …`, after about 31 seconds](#connectkit-redis-did-not-answer--after-about-31-seconds)
47
+ - [`` connectKit: `telemetry: true` needs @softistx/janus-telemetry … ``](#connectkit-telemetry-true-needs-nxgtjanus-telemetry-)
48
+ - [`TypeError: connectRedis: this URI is already connected with other options.`](#typeerror-connectredis-this-uri-is-already-connected-with-other-options)
49
+
50
+ **Running**
51
+ - [`STORE_FAILED` after `kit.close()`](#store_failed-after-kitclose)
52
+ - [`AggregateError: kit.close: several connections failed to close`](#aggregateerror-kitclose-several-connections-failed-to-close)
53
+ - [`connectKit: a connection failed to close after the kit failed to start: …`, a process warning](#connectkit-a-connection-failed-to-close-after-the-kit-failed-to-start--a-process-warning)
54
+
55
+ ---
56
+
57
+ ## Types
58
+
59
+ ### `TS2307: Cannot find module '@softistx/janus-kit' or its corresponding type declarations.`
60
+
61
+ **When:** you import from `@softistx/janus-kit` itself. Bun, at run time, says
62
+ `Cannot find module '@softistx/janus-kit'`.
63
+
64
+ **Why:** the package has no root entry: each database has its subpath, and
65
+ the import names it.
66
+
67
+ **Fix:** import from the subpath of your database.
68
+
69
+ ```ts
70
+ import { connectKit, defineConfig } from '@softistx/janus-kit/drizzle'; // PostgreSQL
71
+ import { connectKit, defineConfig } from '@softistx/janus-kit/mongo'; // MongoDB
72
+ ```
73
+
74
+ ### `TS2339: Property 'access' does not exist on type 'Kit<…>'.`
75
+
76
+ **When:** `kit.access` on a kit whose configuration has no `access`.
77
+
78
+ **Why:** the kit has `access` only when you gave it a function to build it.
79
+
80
+ **Fix:** add `access`, or use permissions without the kit.
81
+
82
+ ```ts
83
+ access: ({ relations, auth }) => permissions({ model: defineModel({ subjects: auth.types, types }), store: relations }),
84
+ ```
85
+
86
+ ### `TS2322: Type '{ url: string; db: PgDatabase; }' is not assignable to type 'PostgresConfig'.`
87
+
88
+ Also `Type '{}' is not assignable to type 'PostgresConfig'.`
89
+
90
+ **When:** `postgres: { url, db }`, or `postgres: {}`.
91
+
92
+ **Why:** the kit either opens the database, from `url`, or uses the one you
93
+ opened, `db`: one of the two, never both and never neither.
94
+
95
+ **Fix:** pass one. `url` is closed by `kit.close()`; `db` is yours to close.
96
+
97
+ ### `TS2322: Type '{ url: string; db: Db; }' is not assignable to type 'MongoConfig'.`
98
+
99
+ Also `Type '{}' is not assignable to type 'MongoConfig'.`
100
+
101
+ **When:** `mongo: { url, db }`, or `mongo: {}`, on `@softistx/janus-kit/mongo`.
102
+
103
+ **Why:** as for `postgres`: the kit opens the database from `url`, or uses the
104
+ `Db` you opened — one of the two.
105
+
106
+ **Fix:** pass one. `url` is closed by `kit.close()`; `db` is yours to close.
107
+
108
+ ### `TS2322: Type '{ db: Db; clientOptions: …; }' is not assignable to type 'MongoConfig'.`
109
+
110
+ The compiler goes on: `Types of property 'clientOptions' are incompatible.`
111
+
112
+ **When:** `mongo: { db, clientOptions }`.
113
+
114
+ **Why:** the `Db`'s client is already open, with its own options.
115
+
116
+ **Fix:** pass the options where you created that client, or pass `url` and
117
+ let the kit open it with `clientOptions`.
118
+
119
+ ### `TS2353: Object literal may only specify known properties, and 'postgres' does not exist in type 'KitConfig<object, never>'.`
120
+
121
+ **When:** `postgres: { … }` given to `defineConfig` from `@softistx/janus-kit/mongo`.
122
+
123
+ **Why:** each subpath takes its own database's key.
124
+
125
+ **Fix:** import from the subpath of the database you configure.
126
+
127
+ ### `TS2339: Property 'postgres' does not exist on type 'HealthOf<"mongo">'.`
128
+
129
+ **When:** `(await kit.ping()).postgres` on a MongoDB kit — a health route
130
+ written for PostgreSQL.
131
+
132
+ **Why:** `ping` names the database it probed: `mongo` there.
133
+
134
+ **Fix:** read `health.mongo`, or only `health.ok`, which every kit answers.
135
+
136
+ ### `TS2322: Type 'RedisConnection' is not assignable to type 'undefined'.`
137
+
138
+ Also `Type '{ tls: true; }' is not assignable to type 'undefined'.`, on
139
+ `clientOptions`.
140
+
141
+ **When:** `redis: { url, connection }`, or `redis: { connection, clientOptions }`.
142
+
143
+ **Why:** a `connection` is already open, with its own options. The kit opens
144
+ one only from `url`, and only then are `clientOptions` used.
145
+
146
+ **Fix:** pass `url` and `clientOptions`, or `connection` alone, opened with
147
+ the options you want:
148
+
149
+ ```ts
150
+ redis: { connection: await connectRedis(process.env.REDIS_URL!, { tls: true, enableOfflineQueue: false }) },
151
+ ```
152
+
153
+ ### `TS2353: Object literal may only specify known properties, and 'schema' does not exist in type …`
154
+
155
+ **When:** `postgres: { db, schema: 'janus' }`, or `schema: janus`.
156
+
157
+ **Why:** the kit takes the tables your schema file built, not the schema they
158
+ are in, so the tables the stores query are exactly the migration's.
159
+
160
+ **Fix:**
161
+
162
+ ```ts
163
+ postgres: { db, tables: janusTables }, // export const janusTables = defineJanusTables({ schema: janus })
164
+ ```
165
+
166
+ ### `TS2345: Argument of type '{ postgres: …; }' is not assignable to parameter of type 'KitConfig<object, never>'.`
167
+
168
+ Followed by `Property 'auth' is missing in type …`.
169
+
170
+ **When:** `defineConfig` without `auth`.
171
+
172
+ **Why:** the kit wires `janus()`, it does not replace it: you write it, so its
173
+ types are inferred where you wrote it.
174
+
175
+ **Fix:**
176
+
177
+ ```ts
178
+ auth: (adapters) => janus({ user: User, password: { login: 'email' }, hasher: scryptHasher(), ...adapters }),
179
+ ```
180
+
181
+ ### `TS2322: Type 'string' is not assignable to type 'boolean'.`
182
+
183
+ **When:** `telemetry: process.env.JANUS_TELEMETRY`, or `telemetry: 'true'`.
184
+
185
+ **Why:** `telemetry` is `true` or `false`, and an environment variable is a
186
+ string: `'false'` would turn it on.
187
+
188
+ **Fix:**
189
+
190
+ ```ts
191
+ telemetry: process.env.JANUS_TELEMETRY === 'true',
192
+ ```
193
+
194
+ ---
195
+
196
+ ## Starting
197
+
198
+ ### `defineConfig: …`
199
+
200
+ The rest names the key: `` `postgres` needs url or db. ``, `` `redis` has both
201
+ url and connection. Pass one. ``, `` `redis.prefix` is a non-empty string. ``,
202
+ `` `auth` is required — (adapters) => janus({ …, ...adapters }). ``,
203
+ `` `postgres.url` is a postgres:// or postgresql:// URL, not mysql://. ``,
204
+ `` `mongo.url` is a mongodb:// or mongodb+srv:// URL, not postgres://. `` and the
205
+ like. It is a `TypeError`. `connectKit: …` with the same words is the same
206
+ check, run again on a configuration that did not go through `defineConfig`.
207
+
208
+ **When:** the configuration is checked, where your application starts. The
209
+ compiler refuses most of these first; they reach run time from JavaScript,
210
+ or from a value typed `any`, such as an environment variable read without `!`
211
+ turning out empty.
212
+
213
+ **Why:** each is a configuration the kit cannot run with.
214
+
215
+ **Fix:** what the message says. An empty `url` usually means an environment
216
+ variable that is not set:
217
+
218
+ ```ts
219
+ const url = process.env.JANUS_DATABASE_URL;
220
+ if (!url) throw new Error('JANUS_DATABASE_URL is not set');
221
+ ```
222
+
223
+ ### `connectKit: Janus's tables are missing from this database: …`
224
+
225
+ The rest lists them, `"users", "logins", …`, or `"janus"."users", …` with
226
+ `postgres.tables` in a schema of their own.
227
+
228
+ **When:** `connectKit`, on a database without the tables.
229
+
230
+ **Why:** one of three things:
231
+ - the migration drizzle-kit generated from `defineJanusTables()` was never
232
+ applied;
233
+ - it was applied to another database: your application's, not Janus's;
234
+ - the tables are in a PostgreSQL schema, and `postgres.tables` was not given,
235
+ so the kit looked in `public`.
236
+
237
+ With `apiKeys: true`, `"api_keys"` is in the list too: apply the migration
238
+ that holds it, or leave the option out.
239
+
240
+ **Fix:** apply the migration to the database `postgres` names, or pass
241
+ `postgres.tables`. [`@softistx/janus-drizzle`'s guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-drizzle/docs/guide/database.md)
242
+ has both setups.
243
+
244
+ ```sh
245
+ bunx drizzle-kit migrate --config drizzle.janus.config.ts
246
+ ```
247
+
248
+ ### `connectKit: PostgreSQL did not answer. …`
249
+
250
+ The message goes on: `` Check `postgres.url`, and that the database exists. ``
251
+ `cause` is the driver's error.
252
+
253
+ **When:** `connectKit`, when the first query fails: a host that refuses the
254
+ connection (measured: 5 ms), a wrong password, a database that does not exist.
255
+
256
+ **Why:** the kit checks the tables before anything else, so an unreachable
257
+ database fails here, not at the first sign-in.
258
+
259
+ **Fix:** read `error.cause` for the driver's reason, and check the URL. The
260
+ URL is not in the message: it may hold a password.
261
+
262
+ ### `` connectKit: the Drizzle instance in `postgres.db` did not answer. ``
263
+
264
+ `cause` is the driver's error.
265
+
266
+ **When:** `connectKit` with `postgres: { db }`, when the first query on it
267
+ fails: its client closed already, or its connection refused.
268
+
269
+ **Why:** the kit checks the tables on the instance you handed in before
270
+ building anything on it.
271
+
272
+ **Fix:** read `error.cause`, and check the instance where you opened it.
273
+
274
+ ### `connectKit: Janus's collections are not in sync with @softistx/janus-mongo: …`
275
+
276
+ The rest names each collection and what it lacks — `users (missing)`, or
277
+ `users (indexes)` for an index that is not there — then `` Run
278
+ syncMongoAdapter(db), a deployment step, against the database `mongo` names. ``
279
+
280
+ **When:** `connectKit` from `@softistx/janus-kit/mongo`, on a database where
281
+ `syncMongoAdapter(db, { dryRun: true })` would create a collection or an
282
+ index. Anything else that differs is [only a warning](#connectkit-januss-collections-differ-from-this-nxgtjanus-mongos-definitions--a-process-warning).
283
+
284
+ **Why:** one of three things:
285
+ - `syncMongoAdapter` never ran against this database: every collection is
286
+ `missing`;
287
+ - it ran against another one — the URL has no path, and the driver used
288
+ `test`;
289
+ - `apiKeys: true` is set and `syncMongoApiKeys(db)` never ran: `apiKeys
290
+ (missing)`;
291
+ - `@softistx/janus-mongo` was upgraded and added an index, or one was dropped by
292
+ hand. A missing login index is the dangerous one: two users could share a
293
+ login.
294
+
295
+ When the missing collection is `apiKeys`, the message names
296
+ `syncMongoApiKeys(db)`, or both calls when another collection is also missing.
297
+
298
+ **Fix:** run the sync where you deploy, with a user that holds `dbAdmin`, and
299
+ name the database in the URL:
300
+
301
+ ```ts
302
+ import { syncMongoAdapter, syncMongoApiKeys } from '@softistx/janus-mongo';
303
+ import { connectMongo } from '@softistx/mongo';
304
+
305
+ await using mongo = await connectMongo(process.env.JANUS_MONGO_ADMIN_URL!); // mongodb://…/janus
306
+ console.log(await syncMongoAdapter(mongo.db));
307
+ console.log(await syncMongoApiKeys(mongo.db)); // only with `apiKeys: true`
308
+ ```
309
+
310
+ ### `connectKit: Janus's collections differ from this @softistx/janus-mongo's definitions: …`, a process warning
311
+
312
+ The rest names each collection and what differs — `users (validator)`,
313
+ `sessions (indexes)`, `tokens (options)` — then `` Run syncMongoAdapter(db)
314
+ once every instance runs this version. `` Its code is
315
+ `JANUS_KIT_COLLECTIONS_DRIFTED`. The kit starts.
316
+
317
+ **When:** `connectKit`, on collections whose validator, options or index
318
+ options differ from the definitions of the `@softistx/janus-mongo` this process
319
+ loaded — in either direction.
320
+
321
+ **Why:** in a rolling deploy or a rollback, one release meets the collections
322
+ another one synced. Refusing to start there would stop the release you are
323
+ rolling back to; a missing collection or index, which makes the stores
324
+ unsafe, [still refuses](#connectkit-januss-collections-are-not-in-sync-with-nxgtjanus-mongo-).
325
+
326
+ **Fix:** once every instance runs the same version, run `syncMongoAdapter(db)`
327
+ where you deploy. To act on it, listen:
328
+
329
+ ```ts
330
+ process.on('warning', (warning) => {
331
+ if ((warning as { code?: string }).code === 'JANUS_KIT_COLLECTIONS_DRIFTED') log.warn(warning.message);
332
+ });
333
+ ```
334
+
335
+ ### `connectKit: MongoDB did not answer. …`
336
+
337
+ The message goes on: `` Check `mongo.url`, and that the server is reachable. ``
338
+ `cause` is the driver's error, a `MongoServerSelectionError` for a server
339
+ that refuses the connection.
340
+
341
+ **When:** `connectKit` with `mongo.url`, when the driver finds no server
342
+ within `serverSelectionTimeoutMS`: 5 s, the kit's, measured; 30 s is the
343
+ driver's own.
344
+
345
+ **Why:** the kit connects and compares the collections before anything else,
346
+ so an unreachable database fails here, not at the first sign-in.
347
+
348
+ **Fix:** read `error.cause` for the driver's reason, and check the URL. The
349
+ URL is not in the message: it may hold a password.
350
+
351
+ ### `` TypeError: connectKit: `mongo.url` is not a connection string the driver can read. ``
352
+
353
+ `cause` is the driver's `MongoParseError` or `MongoRuntimeError`.
354
+
355
+ **When:** `connectKit` with a `mongo.url` the driver cannot parse — a port
356
+ that is not a number, an `@` in an unencoded password — at once, before any
357
+ server is contacted.
358
+
359
+ **Why:** a URL that cannot be read is a wiring mistake, not an outage, as
360
+ `/drizzle` reports one for `postgres.url`.
361
+
362
+ **Fix:** read `error.cause`, and encode the password:
363
+
364
+ ```ts
365
+ const url = `mongodb://janus:${encodeURIComponent(password)}@db.internal/janus`;
366
+ ```
367
+
368
+ ### `` connectKit: the Db in `mongo.db` did not answer. ``
369
+
370
+ `cause` is the driver's error.
371
+
372
+ **When:** `connectKit` with `mongo: { db }`, when comparing the collections
373
+ fails: its client closed already, or it cannot reach a server.
374
+
375
+ **Why:** the kit compares the collections of the `Db` you handed in before
376
+ building anything on it.
377
+
378
+ **Fix:** read `error.cause`, and check the client where you opened it.
379
+
380
+ ### `TypeError: connectMongo: this URI is already connected with other options. …`
381
+
382
+ From `@softistx/mongo` 0.30 the same message comes as a `UriConflictError`
383
+ (`code: 'URI_CONFLICT'`); the kit passes either through unchanged. Test it
384
+ with `error instanceof UriConflictError` or `error.code === 'URI_CONFLICT'`.
385
+
386
+ **When:** `connectKit` with `mongo.url`, when your application already
387
+ connected to the same URL with `connectMongo` and other options — without the
388
+ kit's `serverSelectionTimeoutMS: 5_000`, for instance.
389
+
390
+ **Why:** `@softistx/mongo` shares one client per URL, and one client has one set
391
+ of options. The kit passes the refusal through as it is.
392
+
393
+ **Fix:** give the same options in both places, give Janus a URL of its own,
394
+ or open it yourself and pass `{ db }`:
395
+
396
+ ```ts
397
+ mongo: { db: mongo.db }, // your connectMongo(…) connection, closed by you
398
+ ```
399
+
400
+ ### `connectKit: Redis did not answer. …`, after about 31 seconds
401
+
402
+ The message goes on: `` Check `redis.url`, or leave `redis` out to keep sessions in PostgreSQL. ``
403
+ (`MongoDB` from `@softistx/janus-kit/mongo`). `cause` is Bun's `Connection closed`.
404
+
405
+ **When:** `connectKit`, with `redis.url` pointing at a Redis that is down or
406
+ unreachable.
407
+
408
+ **Why:** Bun's client retries its first connection before it gives up:
409
+ 31.2 s measured, with the kit's `enableOfflineQueue: false`.
410
+
411
+ **Fix:** start Redis, or check the URL. The database connection the kit
412
+ opened is closed before the error leaves.
413
+
414
+ ### `` connectKit: `telemetry: true` needs @softistx/janus-telemetry … ``
415
+
416
+ **When:** `telemetry: true`, without `@softistx/janus-telemetry` installed.
417
+
418
+ **Why:** it is an optional peer, loaded only when telemetry is asked for.
419
+
420
+ **Fix:**
421
+
422
+ ```sh
423
+ bun add @softistx/janus-telemetry @softistx/telemetry
424
+ ```
425
+
426
+ ### `TypeError: connectRedis: this URI is already connected with other options.`
427
+
428
+ From `@softistx/redis` 0.24 the same message comes as a `RedisError` with
429
+ `code: 'URI_CONFLICT'`; the kit passes either through unchanged. Test it with
430
+ `error instanceof RedisError && error.code === 'URI_CONFLICT'`.
431
+
432
+ **When:** `connectKit` with `redis.url`, while your application holds a
433
+ connection to the same URL, opened with other options.
434
+
435
+ **Why:** `@softistx/redis` shares one client per URL, with one set of options, and
436
+ the kit connects with `enableOfflineQueue: false`.
437
+
438
+ **Fix:** pass the kit your connection, `redis: { connection }`, or give Janus
439
+ its own URL, another database number for instance: `redis://localhost:6379/1`.
440
+
441
+ ---
442
+
443
+ ## Running
444
+
445
+ ### `STORE_FAILED` after `kit.close()`
446
+
447
+ **When:** a call through `kit.auth` or `kit.access` after the kit was closed:
448
+ a request still in flight during shutdown, or a test that closed the kit
449
+ early.
450
+
451
+ **Why:** the connections the kit opened are closed, so every store call fails,
452
+ and a failure is never answered as an absence.
453
+
454
+ **Fix:** stop taking requests before closing the kit, for instance after your
455
+ server's `stop()` resolves.
456
+
457
+ ### `AggregateError: kit.close: several connections failed to close`
458
+
459
+ `errors` holds each one. A single failure rejects with that error alone.
460
+
461
+ **When:** `kit.close()`, when closing Redis and the database both failed.
462
+
463
+ **Why:** `close()` tries every connection it opened before it reports, so one
464
+ failure never leaves another open.
465
+
466
+ **Fix:** log `error.errors` at shutdown; there is nothing to retry.
467
+
468
+ ### `connectKit: a connection failed to close after the kit failed to start: …`, a process warning
469
+
470
+ Its code is `JANUS_KIT_CLOSE_FAILED`. The rest is the close's error.
471
+
472
+ **When:** `connectKit` failed, and closing a connection it had opened on the
473
+ way failed too.
474
+
475
+ **Why:** the error that stopped the kit is the one `connectKit` rejects with;
476
+ a failure to clean up after it is reported beside it, as a process warning.
477
+
478
+ **Fix:** fix the first error. The warning tells you a connection may have been
479
+ left open until the process exits.
480
+
481
+ ## Optional peers are installed as required
482
+
483
+ **When:** after `bun add @softistx/janus-kit` of version 0.6.14 or older, or from a lock that resolved one, `node_modules` holds `@softistx/drizzle`, `@softistx/mongo`, `@softistx/janus-drizzle`, `@softistx/janus-mongo`, `@softistx/janus-telemetry`, `drizzle-orm` and `mongodb`, or a second copy of a library sits beside yours.
484
+ **Why:** the package document of versions up to 0.6.14 lacks `peerDependenciesMeta`, so Bun, which installs peers, treats every optional peer as required. The published `package.json` is right; only the package document lacks the field. The first version published on npmjs, and every later one, keeps it. Where you use only one database stack, the other's peers still arrive, and a range that differs from yours can add a duplicate copy.
485
+ **Fix:** install with `--omit=peer`, which skips every peer, **the required ones too** (verified with Bun 1.4.4), then add the required peers back as direct dependencies, plus the database stack you use: `@softistx/drizzle @softistx/janus-drizzle drizzle-orm` for PostgreSQL, or `@softistx/mongo @softistx/janus-mongo mongodb` for MongoDB (and `@softistx/janus-telemetry` if you use it).
486
+
487
+ ```bash
488
+ bun add @softistx/janus @softistx/redis typescript
489
+ bun install --omit=peer
490
+ ```
package/package.json CHANGED
@@ -1,6 +1,114 @@
1
1
  {
2
- "name": "@softistx/janus-kit",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "@softistx/janus-kit",
3
+ "version": "0.6.16",
4
+ "description": "@softistx/janus wired in one call, one subpath per database — PostgreSQL through Drizzle, MongoDB — with sessions in Redis, telemetry, a health check and a close",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "files": [
8
+ "dist",
9
+ "docs",
10
+ "README.md",
11
+ "package.json",
12
+ "LICENSE"
13
+ ],
14
+ "exports": {
15
+ "./drizzle": {
16
+ "types": "./dist/drizzle/index.d.ts",
17
+ "import": "./dist/drizzle/index.js",
18
+ "default": "./dist/drizzle/index.js"
19
+ },
20
+ "./mongo": {
21
+ "types": "./dist/mongo/index.d.ts",
22
+ "import": "./dist/mongo/index.js",
23
+ "default": "./dist/mongo/index.js"
24
+ },
25
+ "./package.json": "./package.json"
26
+ },
27
+ "keywords": [
28
+ "identity",
29
+ "authentication",
30
+ "authorization",
31
+ "postgresql",
32
+ "redis",
33
+ "janus",
34
+ "typescript",
35
+ "mongodb"
36
+ ],
37
+ "repository": {
38
+ "type": "git",
39
+ "url": "git+https://github.com/softistx/nxgt-janus.git",
40
+ "directory": "packages/janus-kit"
41
+ },
42
+ "publishConfig": {
43
+ "registry": "https://registry.npmjs.org/",
44
+ "access": "public"
45
+ },
46
+ "scripts": {
47
+ "build": "bun run ../../build.ts",
48
+ "test": "bun test src",
49
+ "typecheck": "bun check",
50
+ "typecheck:tsc": "tsc --noEmit"
51
+ },
52
+ "nxgt": {
53
+ "entrypoints": [
54
+ "src/drizzle/index.ts",
55
+ "src/mongo/index.ts"
56
+ ]
57
+ },
58
+ "dependencies": {
59
+ "@softistx/janus-redis": "^0.10.4"
60
+ },
61
+ "devDependencies": {
62
+ "@electric-sql/pglite": "0.5.16",
63
+ "@softistx/drizzle": "0.8.1",
64
+ "@softistx/mongo": "^0.30.1",
65
+ "@softistx/redis": "0.24.0",
66
+ "@softistx/telemetry": "0.4.2",
67
+ "@softistx/janus": "^0.74.0",
68
+ "@softistx/janus-drizzle": "^0.26.0",
69
+ "@softistx/janus-mongo": "^0.31.0",
70
+ "@softistx/janus-telemetry": "^0.19.5",
71
+ "@types/bun": "^1.4.4",
72
+ "drizzle-kit": "1.0.0-rc.4",
73
+ "drizzle-orm": "1.0.0-rc.4",
74
+ "mongodb": "^7.9.0",
75
+ "mongodb-memory-server-core": "11.3.0",
76
+ "redis-memory-server": "0.17.2",
77
+ "zod": "^4.6.7"
78
+ },
79
+ "peerDependencies": {
80
+ "@softistx/drizzle": ">=0.8.0 <1",
81
+ "@softistx/mongo": ">=0.27.0 <1",
82
+ "@softistx/redis": ">=0.14.0 <1",
83
+ "@softistx/janus": "^0.74.0",
84
+ "@softistx/janus-drizzle": "^0.26.0",
85
+ "@softistx/janus-mongo": "^0.31.0",
86
+ "@softistx/janus-telemetry": "^0.19.5",
87
+ "drizzle-orm": ">=1.0.0-rc.4 <2",
88
+ "mongodb": ">=7.0.0 <8",
89
+ "typescript": "^6.0.3 || ^7.0.0"
90
+ },
91
+ "peerDependenciesMeta": {
92
+ "@softistx/drizzle": {
93
+ "optional": true
94
+ },
95
+ "@softistx/mongo": {
96
+ "optional": true
97
+ },
98
+ "@softistx/janus-drizzle": {
99
+ "optional": true
100
+ },
101
+ "@softistx/janus-mongo": {
102
+ "optional": true
103
+ },
104
+ "@softistx/janus-telemetry": {
105
+ "optional": true
106
+ },
107
+ "drizzle-orm": {
108
+ "optional": true
109
+ },
110
+ "mongodb": {
111
+ "optional": true
112
+ }
113
+ }
114
+ }