@antelopejs/interface-database-catalog 0.0.4 → 0.1.1-next.42.g48979bb
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/README.md +31 -8
- package/dist/index.d.ts +59 -0
- package/dist/index.js.map +1 -1
- package/docs/index.md +50 -1
- package/package.json +24 -26
package/README.md
CHANGED
|
@@ -1,14 +1,18 @@
|
|
|
1
|
-
|
|
1
|
+
<a href="https://github.com/AntelopeJS/antelopejs"><img data-illustration src="./.github/readme/strip.svg" width="100%" alt="INTERFACE · DATABASE CATALOG: part of AntelopeJS, hexagonal architecture beyond your own code. A glowing button reads Star AntelopeJS."></a>
|
|
2
2
|
|
|
3
3
|
<div align="center">
|
|
4
|
-
<a href="./LICENSE"><img data-illustration alt="License" src="https://img.shields.io/badge/License-Apache_2.0-000000?style=for-the-badge&labelColor=000000"></a>
|
|
5
|
-
<a href="https://discord.gg/g4pFt6eXqu"><img data-illustration alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
|
|
6
|
-
<a href="https://github.com/AntelopeJS/interface-database-catalog/tree/main/docs"><img data-illustration alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
|
|
7
|
-
</div>
|
|
8
4
|
|
|
9
|
-
|
|
5
|
+
# `@antelopejs/interface-database-catalog`
|
|
6
|
+
|
|
7
|
+
<a href="https://www.npmjs.com/package/@antelopejs/interface-database-catalog"><img data-illustration alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-database-catalog?style=for-the-badge&labelColor=000000&color=000000"></a> <a href="./LICENSE"><img data-illustration alt="License" src="https://img.shields.io/badge/License-Apache_2.0-000000?style=for-the-badge&labelColor=000000"></a> <a href="https://discord.gg/g4pFt6eXqu"><img data-illustration alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a> <a href="https://github.com/AntelopeJS/interface-database-catalog/tree/main/docs"><img data-illustration alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a> <a href="https://github.com/AntelopeJS/antelopejs"><img data-illustration alt="Star AntelopeJS" src="https://img.shields.io/github/stars/AntelopeJS/antelopejs?label=Star%20AntelopeJS&style=for-the-badge&labelColor=000000&color=000000&logo=github"></a>
|
|
10
8
|
|
|
11
|
-
|
|
9
|
+
**Describes and profiles a database that an AntelopeJS database provider is connected to but does not own, so a generator can propose matching tables.**
|
|
10
|
+
|
|
11
|
+
[Documentation](./docs/index.md) · [Implementations](#implementations) · [All interfaces and providers](https://github.com/AntelopeJS/antelopejs#ecosystem)
|
|
12
|
+
|
|
13
|
+
</div>
|
|
14
|
+
|
|
15
|
+
Describes and profiles a database that an [`@antelopejs/interface-database`](https://github.com/AntelopeJS/interface-database) provider is connected to but does not own, so a generator can propose a module whose tables mirror it. It is a development tool: every catalog function refuses outside development.
|
|
12
16
|
|
|
13
17
|
## What it offers
|
|
14
18
|
|
|
@@ -18,6 +22,7 @@ Part of [AntelopeJS](https://github.com/AntelopeJS/antelopejs). Used by [Antelop
|
|
|
18
22
|
- `Profile` aggregates a relation per column and per foreign key, never returning rows.
|
|
19
23
|
- `CheckReference` measures how much of one column's values another column holds, for references the database does not declare.
|
|
20
24
|
- `SampleRows` answers a few rows of a relation, each value as text, for a person to look at. It is the one function that returns rows, and it is never meant for a generator or a model.
|
|
25
|
+
- `Probe` types the `probe` every driver exports from `dist/probe.js`: it signs in with a connection string and answers whether the account may read and write.
|
|
21
26
|
|
|
22
27
|
The answers follow the provider's own registration rules. A relation the catalog calls mappable registers, and the key it names is the one `_id` aliases.
|
|
23
28
|
|
|
@@ -60,7 +65,7 @@ The interface has one AntelopeJS peer dependency:
|
|
|
60
65
|
|
|
61
66
|
| Package | Supported | Tested with |
|
|
62
67
|
| ---------------------------- | ---------------- | ----------- |
|
|
63
|
-
| `@antelopejs/interface-core` | `>=0.
|
|
68
|
+
| `@antelopejs/interface-core` | `>=0.5.0 <0.6.0` | `0.5.1` |
|
|
64
69
|
|
|
65
70
|
<!-- antelopejs-docs-compat:end -->
|
|
66
71
|
|
|
@@ -73,6 +78,24 @@ pnpm install
|
|
|
73
78
|
pnpm run checks
|
|
74
79
|
```
|
|
75
80
|
|
|
81
|
+
## Part of AntelopeJS
|
|
82
|
+
|
|
83
|
+
[AntelopeJS](https://github.com/AntelopeJS/antelopejs) is a TypeScript framework where modules depend on contracts and the application chooses the provider behind each one. [AntelopeJS DMS](https://github.com/AntelopeJS/dms), the open-source back office, is built on it.
|
|
84
|
+
|
|
85
|
+
<!-- antelopejs-framework-modules:start -->
|
|
86
|
+
|
|
87
|
+
| Area | Contracts | Providers |
|
|
88
|
+
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
89
|
+
| API | [`interface-api`](https://github.com/AntelopeJS/interface-api) · [`interface-api-util`](https://github.com/AntelopeJS/interface-api-util) · [`interface-data-api`](https://github.com/AntelopeJS/interface-data-api) | [`api`](https://github.com/AntelopeJS/api) |
|
|
90
|
+
| Auth | [`interface-auth`](https://github.com/AntelopeJS/interface-auth) | [`auth-jwt`](https://github.com/AntelopeJS/auth-jwt) |
|
|
91
|
+
| Database | [`interface-database`](https://github.com/AntelopeJS/interface-database) · [`interface-database-decorators`](https://github.com/AntelopeJS/interface-database-decorators) · **`interface-database-catalog`** · [`interface-mongodb`](https://github.com/AntelopeJS/interface-mongodb) · [`interface-rethinkdb`](https://github.com/AntelopeJS/interface-rethinkdb) | [`postgres`](https://github.com/AntelopeJS/postgres) · [`mysql`](https://github.com/AntelopeJS/mysql) · [`mongodb`](https://github.com/AntelopeJS/mongodb) · [`rethinkdb`](https://github.com/AntelopeJS/rethinkdb) |
|
|
92
|
+
| Redis | [`interface-redis`](https://github.com/AntelopeJS/interface-redis) · [`interface-redis-scheduler`](https://github.com/AntelopeJS/interface-redis-scheduler) | [`redis`](https://github.com/AntelopeJS/redis) |
|
|
93
|
+
| Email | [`interface-email`](https://github.com/AntelopeJS/interface-email) | [`nodemailer`](https://github.com/AntelopeJS/nodemailer) · [`brevo`](https://github.com/AntelopeJS/brevo) |
|
|
94
|
+
| File storage | [`interface-file-storage`](https://github.com/AntelopeJS/interface-file-storage) | [`file-storage-local`](https://github.com/AntelopeJS/file-storage-local) · [`file-storage-s3`](https://github.com/AntelopeJS/file-storage-s3) |
|
|
95
|
+
| Payments | [`interface-payment`](https://github.com/AntelopeJS/interface-payment) · [`interface-subscriptions`](https://github.com/AntelopeJS/interface-subscriptions) · [`interface-stripe`](https://github.com/AntelopeJS/interface-stripe) | [`stripe`](https://github.com/AntelopeJS/stripe) · [`mollie`](https://github.com/AntelopeJS/mollie) · [`checkout-com`](https://github.com/AntelopeJS/checkout-com) · [`payment-subscriptions`](https://github.com/AntelopeJS/payment-subscriptions) |
|
|
96
|
+
|
|
97
|
+
<!-- antelopejs-framework-modules:end -->
|
|
98
|
+
|
|
76
99
|
## License
|
|
77
100
|
|
|
78
101
|
[Apache-2.0](./LICENSE)
|
package/dist/index.d.ts
CHANGED
|
@@ -276,6 +276,65 @@ export interface RowSample {
|
|
|
276
276
|
/** How the relation was sampled before its first rows were read, when it was. */
|
|
277
277
|
sample: SampleInfo | null;
|
|
278
278
|
}
|
|
279
|
+
/**
|
|
280
|
+
* Why the server turned the probe away: wrong user or password, a client host the server does
|
|
281
|
+
* not accept, a database that does not exist, a database the account may not connect to, a
|
|
282
|
+
* server that wants credentials the URL does not give, or any other refusal.
|
|
283
|
+
*/
|
|
284
|
+
export type ProbeRefusal = "credentials" | "host" | "database" | "database-denied" | "sign-in-required" | "other";
|
|
285
|
+
/**
|
|
286
|
+
* Why a signed-in account cannot read, when the cause is not its privileges: the URL names no
|
|
287
|
+
* database, the server has no database with that name, or the account may not list the database's
|
|
288
|
+
* relations.
|
|
289
|
+
*/
|
|
290
|
+
export type ProbeUnreadable = "no-database-named" | "no-database" | "cannot-list";
|
|
291
|
+
/** What a driver's probe connects to, and how long it may take. */
|
|
292
|
+
export type ProbeConfig = {
|
|
293
|
+
/** The connection string the driver's `config.url` takes; the database is its path. */
|
|
294
|
+
url: string;
|
|
295
|
+
/** Bounds the connect and each answer, in milliseconds. */
|
|
296
|
+
timeoutMs: number;
|
|
297
|
+
/** When it aborts, the probe closes everything it opened at once. */
|
|
298
|
+
signal: AbortSignal;
|
|
299
|
+
};
|
|
300
|
+
/** What a probe found, told apart by `outcome`. */
|
|
301
|
+
export type ProbeAnswer = {
|
|
302
|
+
/** No server answered at the URL. */
|
|
303
|
+
outcome: "unreachable";
|
|
304
|
+
/** The driver's own text, which may hold the URL or the password; redact it before showing it. */
|
|
305
|
+
message: string;
|
|
306
|
+
} | {
|
|
307
|
+
/** A server answered and refused the sign-in. */
|
|
308
|
+
outcome: "refused";
|
|
309
|
+
refusal: ProbeRefusal;
|
|
310
|
+
/** The driver's own text, which may hold the URL or the password; redact it before showing it. */
|
|
311
|
+
message: string;
|
|
312
|
+
} | {
|
|
313
|
+
/** The account signed in. */
|
|
314
|
+
outcome: "signed-in";
|
|
315
|
+
/** How long the account's first query took, in milliseconds, rounded up. */
|
|
316
|
+
latencyMs: number;
|
|
317
|
+
/** The account the server signed in, when it names one. */
|
|
318
|
+
user?: string;
|
|
319
|
+
/**
|
|
320
|
+
* The account may read any relation it sees, or it sees none. False whenever `unreadable` is
|
|
321
|
+
* set.
|
|
322
|
+
*/
|
|
323
|
+
canRead: boolean;
|
|
324
|
+
/**
|
|
325
|
+
* The account may create a table in the database the URL names, or insert, update or delete
|
|
326
|
+
* in a relation it sees.
|
|
327
|
+
*/
|
|
328
|
+
canWrite: boolean;
|
|
329
|
+
/** Why the account cannot read when the cause is not its privileges; set only with `canRead` false. */
|
|
330
|
+
unreadable?: ProbeUnreadable;
|
|
331
|
+
};
|
|
332
|
+
/**
|
|
333
|
+
* Signs in to a database and reports what the account may do there. Every driver exports one as
|
|
334
|
+
* `probe` from `dist/probe.js`, required as `@antelopejs/<driver>/dist/probe`. It never rejects
|
|
335
|
+
* and changes no row.
|
|
336
|
+
*/
|
|
337
|
+
export type Probe = (config: ProbeConfig) => Promise<ProbeAnswer>;
|
|
279
338
|
/**
|
|
280
339
|
* The connected database: engine, version, database and role.
|
|
281
340
|
*
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAwS/D,sCAAsC;AACzB,QAAA,iBAAiB,GAAG,EAAE,CAAC;AAEpC,oEAAoE;AACvD,QAAA,kBAAkB,GAAG,GAAG,CAAC;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAwS/D,sCAAsC;AACzB,QAAA,iBAAiB,GAAG,EAAE,CAAC;AAEpC,oEAAoE;AACvD,QAAA,kBAAkB,GAAG,GAAG,CAAC;AA4GtC;;;;;GAKG;AACU,QAAA,IAAI,GAAG,IAAA,kCAAiB,GAA8B,CAAC;AAEpE;;;GAGG;AACU,QAAA,aAAa,GACxB,IAAA,kCAAiB,GAAsD,CAAC;AAE1E,qDAAqD;AACxC,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAA2D,CAAC;AAE/E;;;GAGG;AACU,QAAA,OAAO,GAClB,IAAA,kCAAiB,GAAyD,CAAC;AAE7E;;;GAGG;AACU,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAEd,CAAC;AAEN;;;GAGG;AACU,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAAkD,CAAC"}
|
package/docs/index.md
CHANGED
|
@@ -4,7 +4,7 @@ description: Discover, describe and profile the relations of a database that an
|
|
|
4
4
|
mode: how-to
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
Use `@antelopejs/interface-database-catalog` to discover relations, inspect their structure, and profile aggregate characteristics before mapping an existing database into an application. The catalog describes a provider's connection. It does not open a new connection or register tables. It returns no raw records, except through `SampleRows`, which answers a few rows for a person to look at.
|
|
7
|
+
Use `@antelopejs/interface-database-catalog` to discover relations, inspect their structure, and profile aggregate characteristics before mapping an existing database into an application. The catalog describes a provider's connection. It does not open a new connection or register tables; only a driver's `probe`, described below, signs in on its own. It returns no raw records, except through `SampleRows`, which answers a few rows for a person to look at.
|
|
8
8
|
|
|
9
9
|
## Before you begin
|
|
10
10
|
|
|
@@ -143,3 +143,52 @@ Every function refuses:
|
|
|
143
143
|
|
|
144
144
|
- outside development;
|
|
145
145
|
- on a provider instance that owns its tables.
|
|
146
|
+
|
|
147
|
+
## Probe a connection string
|
|
148
|
+
|
|
149
|
+
Every AntelopeJS database driver exports `probe` from `dist/probe.js`, typed `export const probe: Probe`. A caller requires it as `@antelopejs/<driver>/dist/probe` to learn whether a connection string signs in and what the account may do. The probe opens its own connection from the URL and is not a catalog function. The interface declares the types; each driver implements them.
|
|
150
|
+
|
|
151
|
+
```ts docs-check
|
|
152
|
+
import type { Probe } from "@antelopejs/interface-database-catalog";
|
|
153
|
+
|
|
154
|
+
export async function probeUrl(driver: string, url: string) {
|
|
155
|
+
const { probe }: { probe: Probe } = require(
|
|
156
|
+
`@antelopejs/${driver}/dist/probe`,
|
|
157
|
+
);
|
|
158
|
+
const timeoutMs = 5000;
|
|
159
|
+
const controller = new AbortController();
|
|
160
|
+
const deadline = setTimeout(() => controller.abort(), 3 * timeoutMs);
|
|
161
|
+
try {
|
|
162
|
+
return await probe({ url, timeoutMs, signal: controller.signal });
|
|
163
|
+
} finally {
|
|
164
|
+
clearTimeout(deadline);
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
`require` returns an untyped value, and the annotation states its shape without checking it. It holds because each driver's `dist/probe.js` exports `probe` typed `Probe`.
|
|
170
|
+
|
|
171
|
+
`ProbeConfig` takes:
|
|
172
|
+
|
|
173
|
+
- `url`, the connection string the driver's `config.url` takes, with the database as its path;
|
|
174
|
+
- `timeoutMs`, which bounds the connect and each answer;
|
|
175
|
+
- `signal`, which closes everything the probe opened at once when it aborts. The caller sets its own deadline on it.
|
|
176
|
+
|
|
177
|
+
A probe never rejects and changes no row. It answers a `ProbeAnswer`, told apart by `outcome`:
|
|
178
|
+
|
|
179
|
+
| `outcome` | Fields | Meaning |
|
|
180
|
+
| --------------- | ---------------------------------------------------------- | ------------------------------------------- |
|
|
181
|
+
| `"unreachable"` | `message` | No server answered at the URL. |
|
|
182
|
+
| `"refused"` | `refusal`, `message` | A server answered and refused the sign-in. |
|
|
183
|
+
| `"signed-in"` | `latencyMs`, `user?`, `canRead`, `canWrite`, `unreadable?` | The account signed in, with what it may do. |
|
|
184
|
+
|
|
185
|
+
`refusal` is a `ProbeRefusal`: `"credentials"`, `"host"`, `"database"`, `"database-denied"`, `"sign-in-required"` or `"other"`.
|
|
186
|
+
|
|
187
|
+
For a signed-in account:
|
|
188
|
+
|
|
189
|
+
- `canWrite` is true when the account may create a table in the database the URL names, or insert, update or delete in a relation it sees;
|
|
190
|
+
- `canRead` is true when it may read any relation it sees, or sees none, and false whenever `unreadable` is set;
|
|
191
|
+
- `latencyMs` is how long the account's first query took, rounded up to a millisecond;
|
|
192
|
+
- `unreadable`, a `ProbeUnreadable`, comes with `canRead: false` and says why the account cannot read when the cause is not its privileges: `"no-database-named"`, `"no-database"` or `"cannot-list"`.
|
|
193
|
+
|
|
194
|
+
`message` is the driver's own text. A caller that shows it to a person writes its own sentence and redacts the URL and the password first.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-database-catalog",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.1.1-next.42.g48979bb",
|
|
4
4
|
"description": "AntelopeJS interface for describing and profiling a connected database",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
@@ -31,29 +31,10 @@
|
|
|
31
31
|
"access": "public",
|
|
32
32
|
"provenance": true
|
|
33
33
|
},
|
|
34
|
-
"scripts": {
|
|
35
|
-
"build": "rimraf dist && tsc --skipLibCheck",
|
|
36
|
-
"typecheck": "tsc --noEmit",
|
|
37
|
-
"test": "pnpm run build",
|
|
38
|
-
"format": "oxfmt .",
|
|
39
|
-
"lint:fix": "oxlint --fix",
|
|
40
|
-
"lint": "oxlint",
|
|
41
|
-
"prepack": "pnpm run build",
|
|
42
|
-
"release": "pnpm run lint && pnpm run typecheck && pnpm run prepack && release-it",
|
|
43
|
-
"format:check": "oxfmt --check .",
|
|
44
|
-
"knip": "knip",
|
|
45
|
-
"prepare": "if [ -e .git ] && command -v git >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1 && GIT_DIR=.git GIT_WORK_TREE=. git rev-parse --git-dir >/dev/null 2>&1; then GIT_DIR=.git GIT_WORK_TREE=. lefthook install; fi",
|
|
46
|
-
"checks": "antelopejs-checks",
|
|
47
|
-
"size": "antelopejs-check-size",
|
|
48
|
-
"sync": "antelopejs-sync",
|
|
49
|
-
"sync:check": "antelopejs-sync --check",
|
|
50
|
-
"suppressions": "antelopejs-suppressions",
|
|
51
|
-
"suppressions:update": "antelopejs-suppressions --update"
|
|
52
|
-
},
|
|
53
34
|
"devDependencies": {
|
|
54
|
-
"@antelopejs/core": "
|
|
55
|
-
"@antelopejs/interface-core": ">=0.
|
|
56
|
-
"@antelopejs/tooling-configs": "
|
|
35
|
+
"@antelopejs/core": "~1.23.3",
|
|
36
|
+
"@antelopejs/interface-core": ">=0.5.0 <0.6.0",
|
|
37
|
+
"@antelopejs/tooling-configs": ">=0.8.2 <0.9.0",
|
|
57
38
|
"@types/node": "^22.19.15",
|
|
58
39
|
"knip": "^6.34.0",
|
|
59
40
|
"lefthook": "^2.2.2",
|
|
@@ -66,12 +47,29 @@
|
|
|
66
47
|
"typescript": "^5.9.3"
|
|
67
48
|
},
|
|
68
49
|
"peerDependencies": {
|
|
69
|
-
"@antelopejs/interface-core": ">=0.
|
|
50
|
+
"@antelopejs/interface-core": ">=0.5.0 <0.6.0"
|
|
70
51
|
},
|
|
71
|
-
"packageManager": "pnpm@10.6.5",
|
|
72
52
|
"antelopeJs": {
|
|
73
53
|
"docs": {
|
|
74
54
|
"standard": true
|
|
75
55
|
}
|
|
56
|
+
},
|
|
57
|
+
"gitHead": "48979bb0618d7dd5e6ab1e0882000a11b046461a",
|
|
58
|
+
"scripts": {
|
|
59
|
+
"build": "rimraf dist && tsc --skipLibCheck",
|
|
60
|
+
"typecheck": "tsc --noEmit",
|
|
61
|
+
"test": "pnpm run build",
|
|
62
|
+
"format": "oxfmt .",
|
|
63
|
+
"lint:fix": "oxlint --fix",
|
|
64
|
+
"lint": "oxlint",
|
|
65
|
+
"release": "pnpm run lint && pnpm run typecheck && pnpm run prepack && release-it",
|
|
66
|
+
"format:check": "oxfmt --check .",
|
|
67
|
+
"knip": "knip",
|
|
68
|
+
"checks": "antelopejs-checks",
|
|
69
|
+
"size": "antelopejs-check-size",
|
|
70
|
+
"sync": "antelopejs-sync",
|
|
71
|
+
"sync:check": "antelopejs-sync --check",
|
|
72
|
+
"suppressions": "antelopejs-suppressions",
|
|
73
|
+
"suppressions:update": "antelopejs-suppressions --update"
|
|
76
74
|
}
|
|
77
|
-
}
|
|
75
|
+
}
|