@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.
- package/LICENSE +21 -0
- package/README.md +270 -2
- package/dist/chunks/index-vw036wd3.js +187 -0
- package/dist/chunks/index-vw036wd3.js.map +13 -0
- package/dist/drizzle/config.d.ts +49 -0
- package/dist/drizzle/config.d.ts.map +1 -0
- package/dist/drizzle/connect.d.ts +24 -0
- package/dist/drizzle/connect.d.ts.map +1 -0
- package/dist/drizzle/index.d.ts +16 -0
- package/dist/drizzle/index.d.ts.map +1 -0
- package/dist/drizzle/index.js +115 -0
- package/dist/drizzle/index.js.map +11 -0
- package/dist/mongo/config.d.ts +45 -0
- package/dist/mongo/config.d.ts.map +1 -0
- package/dist/mongo/connect.d.ts +26 -0
- package/dist/mongo/connect.d.ts.map +1 -0
- package/dist/mongo/index.d.ts +16 -0
- package/dist/mongo/index.d.ts.map +1 -0
- package/dist/mongo/index.js +134 -0
- package/dist/mongo/index.js.map +11 -0
- package/dist/shared/config.d.ts +90 -0
- package/dist/shared/config.d.ts.map +1 -0
- package/dist/shared/health.d.ts +33 -0
- package/dist/shared/health.d.ts.map +1 -0
- package/dist/shared/kit.d.ts +71 -0
- package/dist/shared/kit.d.ts.map +1 -0
- package/dist/shared/uri-conflict.d.ts +9 -0
- package/dist/shared/uri-conflict.d.ts.map +1 -0
- package/docs/README.md +11 -0
- package/docs/guide/configuration.md +264 -0
- package/docs/guide/lifecycle.md +59 -0
- package/docs/roadmap.md +47 -0
- package/docs/troubleshooting.md +490 -0
- package/package.json +113 -5
|
@@ -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
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
+
}
|