@antelopejs/interface-database-catalog 0.0.1 → 0.0.3
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 +9 -5
- package/dist/index.d.ts +34 -0
- package/dist/index.js +10 -1
- package/dist/index.js.map +1 -1
- package/docs/index.md +105 -12
- package/docs/tsconfig.json +13 -0
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -15,6 +15,7 @@ Describes and profiles a database that an [`@antelopejs/interface-database`](htt
|
|
|
15
15
|
- `DescribeRelations` details columns with their native types and the `@Field` declarations they accept, indexes and foreign keys.
|
|
16
16
|
- `Profile` aggregates a relation per column and per foreign key, never returning rows.
|
|
17
17
|
- `CheckReference` measures how much of one column's values another column holds, for references the database does not declare.
|
|
18
|
+
- `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 is never meant for a generator or a model.
|
|
18
19
|
|
|
19
20
|
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.
|
|
20
21
|
|
|
@@ -47,14 +48,17 @@ Relations are named `"schema.name"`, the form `DescribeRelations` and `Profile`
|
|
|
47
48
|
|
|
48
49
|
## Documentation
|
|
49
50
|
|
|
50
|
-
- [Overview](
|
|
51
|
+
- [Overview and provider connections](./docs/index.md)
|
|
51
52
|
|
|
52
53
|
## Compatibility
|
|
53
54
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
55
|
+
Requires AntelopeJS core `>=1.14.0` and the following peer dependency:
|
|
56
|
+
|
|
57
|
+
<!-- docs-compat: ./package.json#peerDependencies -->
|
|
58
|
+
|
|
59
|
+
| Package | Range |
|
|
60
|
+
| ---------------------------- | ---------------- |
|
|
61
|
+
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
|
|
58
62
|
|
|
59
63
|
## Contributing
|
|
60
64
|
|
package/dist/index.d.ts
CHANGED
|
@@ -247,6 +247,35 @@ export interface ReferenceMatch {
|
|
|
247
247
|
sampled: boolean;
|
|
248
248
|
targetIsKey: boolean;
|
|
249
249
|
}
|
|
250
|
+
/** The most rows a sample answers. */
|
|
251
|
+
export declare const SAMPLE_ROWS_LIMIT = 20;
|
|
252
|
+
/** The most characters a sampled value answers before it is cut. */
|
|
253
|
+
export declare const SAMPLE_TEXT_LENGTH = 200;
|
|
254
|
+
/** The relation, columns and number of rows to sample; every column when `columns` is absent. */
|
|
255
|
+
export interface SampleRequest {
|
|
256
|
+
relation: string;
|
|
257
|
+
columns?: string[];
|
|
258
|
+
/** At most `SAMPLE_ROWS_LIMIT`. */
|
|
259
|
+
limit: number;
|
|
260
|
+
}
|
|
261
|
+
/** A sampled value as text, cut at `SAMPLE_TEXT_LENGTH` characters. */
|
|
262
|
+
export interface SampledText {
|
|
263
|
+
text: string;
|
|
264
|
+
truncated: boolean;
|
|
265
|
+
}
|
|
266
|
+
/** A binary value, answered by its length only. */
|
|
267
|
+
export interface SampledBinary {
|
|
268
|
+
bytes: number;
|
|
269
|
+
}
|
|
270
|
+
export type SampledValue = SampledText | SampledBinary | null;
|
|
271
|
+
/** Rows of a relation, each value in the order of `columns`. */
|
|
272
|
+
export interface RowSample {
|
|
273
|
+
relation: string;
|
|
274
|
+
columns: string[];
|
|
275
|
+
rows: SampledValue[][];
|
|
276
|
+
/** How the relation was sampled before its first rows were read, when it was. */
|
|
277
|
+
sample: SampleInfo | null;
|
|
278
|
+
}
|
|
250
279
|
/**
|
|
251
280
|
* The connected database: engine, version, database and role.
|
|
252
281
|
*
|
|
@@ -271,3 +300,8 @@ export declare const Profile: (request: ProfileRequest) => Promise<RelationProfi
|
|
|
271
300
|
* declare.
|
|
272
301
|
*/
|
|
273
302
|
export declare const CheckReference: (check: ReferenceCheck) => Promise<Measure<ReferenceMatch>>;
|
|
303
|
+
/**
|
|
304
|
+
* A few rows of a relation, for a person to look at. Unlike every other function, it answers
|
|
305
|
+
* row values: a consumer shows them to the project's owner and passes them to nothing else.
|
|
306
|
+
*/
|
|
307
|
+
export declare const SampleRows: (request: SampleRequest) => Promise<RowSample>;
|
package/dist/index.js
CHANGED
|
@@ -1,7 +1,11 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.CheckReference = exports.Profile = exports.DescribeRelations = exports.ListRelations = exports.Info = void 0;
|
|
3
|
+
exports.SampleRows = exports.CheckReference = exports.Profile = exports.DescribeRelations = exports.ListRelations = exports.Info = exports.SAMPLE_TEXT_LENGTH = exports.SAMPLE_ROWS_LIMIT = void 0;
|
|
4
4
|
const interface_core_1 = require("@antelopejs/interface-core");
|
|
5
|
+
/** The most rows a sample answers. */
|
|
6
|
+
exports.SAMPLE_ROWS_LIMIT = 20;
|
|
7
|
+
/** The most characters a sampled value answers before it is cut. */
|
|
8
|
+
exports.SAMPLE_TEXT_LENGTH = 200;
|
|
5
9
|
/**
|
|
6
10
|
* The connected database: engine, version, database and role.
|
|
7
11
|
*
|
|
@@ -26,4 +30,9 @@ exports.Profile = (0, interface_core_1.InterfaceFunction)();
|
|
|
26
30
|
* declare.
|
|
27
31
|
*/
|
|
28
32
|
exports.CheckReference = (0, interface_core_1.InterfaceFunction)();
|
|
33
|
+
/**
|
|
34
|
+
* A few rows of a relation, for a person to look at. Unlike every other function, it answers
|
|
35
|
+
* row values: a consumer shows them to the project's owner and passes them to nothing else.
|
|
36
|
+
*/
|
|
37
|
+
exports.SampleRows = (0, interface_core_1.InterfaceFunction)();
|
|
29
38
|
//# sourceMappingURL=index.js.map
|
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;;;;;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"}
|
|
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;AAgCtC;;;;;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
|
@@ -1,10 +1,62 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Inspect an existing database
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
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, and it returns no raw records except through `SampleRows`, a few rows for a person to look at.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Before you begin
|
|
6
|
+
|
|
7
|
+
Run inside an AntelopeJS module in development, connected to a provider that implements this catalog and does not own its tables. Every catalog function refuses outside development or on an instance that owns its tables. These are safety boundaries, not configuration errors to work around in production.
|
|
8
|
+
|
|
9
|
+
## Explore in increasing detail
|
|
10
|
+
|
|
11
|
+
| Step | Call | Use the answer to… |
|
|
12
|
+
| ----------------------------------------- | -------------------------------- | ---------------------------------------------------------------- |
|
|
13
|
+
| 1. Identify the connection | `Info()` | Confirm the engine, database, and role before inspecting data. |
|
|
14
|
+
| 2. Select a relation | `ListRelations(schemas?)` | Review names, keys, write privileges, and mapping refusals. |
|
|
15
|
+
| 3. Understand its structure | `DescribeRelations(relations)` | Inspect field declarations, indexes, and declared relationships. |
|
|
16
|
+
| 4. Measure only what you need | `Profile({ relation, columns })` | Inspect aggregates and traits for selected columns. |
|
|
17
|
+
| 5. Investigate an undeclared relationship | `CheckReference({ from, to })` | Measure value containment without declaring a foreign key. |
|
|
18
|
+
|
|
19
|
+
Start with metadata before requesting profiles. Use qualified relation names such as `"public.orders"`; omitting `columns` profiles all columns of the selected relation.
|
|
20
|
+
|
|
21
|
+
## Inspect one relation
|
|
22
|
+
|
|
23
|
+
This example uses the consuming module's default catalog binding. First inspect the relation list, then pass a name it returned to `inspectRelation`, such as `"public.orders"`. It reads metadata only; profiling is a separate, potentially more expensive step.
|
|
24
|
+
|
|
25
|
+
```ts docs-check
|
|
26
|
+
import {
|
|
27
|
+
Info,
|
|
28
|
+
ListRelations,
|
|
29
|
+
DescribeRelations,
|
|
30
|
+
} from "@antelopejs/interface-database-catalog";
|
|
31
|
+
|
|
32
|
+
export async function listDatabase() {
|
|
33
|
+
return { connection: await Info(), relations: await ListRelations() };
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export async function inspectRelation(relation: string) {
|
|
37
|
+
const descriptions = await DescribeRelations([relation]);
|
|
38
|
+
return descriptions.map((description) => ({
|
|
39
|
+
relation: `${description.schema}.${description.name}`,
|
|
40
|
+
key: description.key,
|
|
41
|
+
writes: description.writes,
|
|
42
|
+
columns: description.columns,
|
|
43
|
+
unmappable: description.unmappable,
|
|
44
|
+
}));
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Review `unmappable`, each column's `accepts` and `lossy` notes, and write permissions before generating table declarations. A missing key is not automatically a mapping refusal: such a relation can register without `_id`. Introspection does not grant permissions or add constraints.
|
|
49
|
+
|
|
50
|
+
## Advanced: select a named provider
|
|
51
|
+
|
|
52
|
+
A module that implements `@antelopejs/interface-database` over a database it does not own may also implement this interface. Each consumer reaches it through a connection declared on its own module entry in the project configuration, one per database. Two consumers of the same database give their connections the same id:
|
|
6
53
|
|
|
7
54
|
```ts
|
|
55
|
+
"dms-builder": {
|
|
56
|
+
importOverrides: [
|
|
57
|
+
{ interface: "@antelopejs/interface-database-catalog", source: "postgres-erp", id: "erp" },
|
|
58
|
+
],
|
|
59
|
+
},
|
|
8
60
|
"dms-ai": {
|
|
9
61
|
importOverrides: [
|
|
10
62
|
{ interface: "@antelopejs/interface-database-catalog", source: "postgres-erp", id: "erp" },
|
|
@@ -12,17 +64,37 @@ A module that implements `@antelopejs/interface-database` over a database it doe
|
|
|
12
64
|
},
|
|
13
65
|
```
|
|
14
66
|
|
|
15
|
-
`GetInterfaceInstances`
|
|
67
|
+
`GetInterfaceInstances(interfaceID)` lists connections visible to the calling module. `GetInterfaceInstance(interfaceID, connectionID)` returns connection metadata, including its loadable `path`, or `undefined`; it does not return the catalog exports. Resolve the connection by package name and load its path using AntelopeJS's established CommonJS loader pattern:
|
|
68
|
+
|
|
69
|
+
```ts docs-check
|
|
70
|
+
import { GetInterfaceInstance } from "@antelopejs/interface-core";
|
|
71
|
+
|
|
72
|
+
export async function inspectErp() {
|
|
73
|
+
const connection = GetInterfaceInstance(
|
|
74
|
+
"@antelopejs/interface-database-catalog",
|
|
75
|
+
"erp",
|
|
76
|
+
);
|
|
77
|
+
if (!connection) throw new Error("Missing erp catalog connection");
|
|
78
|
+
|
|
79
|
+
const catalog: typeof import("@antelopejs/interface-database-catalog") = require(
|
|
80
|
+
connection.path,
|
|
81
|
+
);
|
|
82
|
+
return await catalog.ListRelations(["public"]);
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Run this inside the consuming AntelopeJS module, with the provider loaded and the connection configured. A plain package import uses that module's default binding; loading `connection.path` selects the named binding. These calls do not create database connections themselves.
|
|
16
87
|
|
|
17
88
|
## Functions
|
|
18
89
|
|
|
19
|
-
| Function
|
|
20
|
-
|
|
|
21
|
-
| `Info()`
|
|
22
|
-
| `ListRelations(schemas?)`
|
|
23
|
-
| `DescribeRelations(relations)`
|
|
24
|
-
| `Profile({ relation, columns? })`
|
|
25
|
-
| `CheckReference({ from, to })`
|
|
90
|
+
| Function | Answers |
|
|
91
|
+
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
92
|
+
| `Info()` | engine, version, database and role of the connection |
|
|
93
|
+
| `ListRelations(schemas?)` | visible relations (excluding child partitions), row estimates, keys, write privileges, and mapping refusals |
|
|
94
|
+
| `DescribeRelations(relations)` | the named relations in full: columns with their native types and the declarations they accept, indexes, foreign keys out and in |
|
|
95
|
+
| `Profile({ relation, columns? })` | aggregates per column and per foreign key, and the traits they imply |
|
|
96
|
+
| `CheckReference({ from, to })` | whether one column's non-null values occur in another, without assuming a declared foreign key |
|
|
97
|
+
| `SampleRows({ relation, columns?, limit })` | a few rows, each value as text, for a person to look at; never for a generator or a model |
|
|
26
98
|
|
|
27
99
|
Relations are named `"schema.name"`.
|
|
28
100
|
|
|
@@ -38,7 +110,28 @@ A profile holds aggregates, never rows:
|
|
|
38
110
|
|
|
39
111
|
Values appear only as enum labels and as **categories**: the most frequent values of a column with few distinct values, each counted often enough to be a category rather than a record. Rarer values are folded into `other` and never named.
|
|
40
112
|
|
|
41
|
-
|
|
113
|
+
### Interpret incomplete measurements
|
|
114
|
+
|
|
115
|
+
Every measure has its own time bound. Handle its status before reading a value; a failed measure does not invalidate the rest of a profile.
|
|
116
|
+
|
|
117
|
+
| Status | Available data | Interpretation |
|
|
118
|
+
| ----------- | -------------- | ----------------------------------------------------------------------------------- |
|
|
119
|
+
| `"ok"` | `value` | The measure completed. Check sampling and exactness before treating it as a census. |
|
|
120
|
+
| `"timeout"` | No value | The time bound expired; this is not a zero count. |
|
|
121
|
+
| `"error"` | `code` | The database refused the measure; only its error code is exposed. |
|
|
122
|
+
|
|
123
|
+
A large relation is sampled, and `sample` reports the percentage and row count. A distinct count from a sample is a lower bound. Row counts also carry an `exact` flag. `CheckReference` reports containment and whether the target is a key; it does not prove that the database enforces a foreign key.
|
|
124
|
+
|
|
125
|
+
## What a sample answers
|
|
126
|
+
|
|
127
|
+
`SampleRows` is the one function that answers row values. It is meant for a person deciding what a relation's columns hold, never for a generator or a model:
|
|
128
|
+
|
|
129
|
+
- at most `SAMPLE_ROWS_LIMIT` (20) rows;
|
|
130
|
+
- every value as text, cut at `SAMPLE_TEXT_LENGTH` (200) characters, and `truncated` when it was;
|
|
131
|
+
- a binary value as its length only;
|
|
132
|
+
- a large relation is sampled as a profile is, and `sample` says so.
|
|
133
|
+
|
|
134
|
+
It reads without writing anything, within the same time bounds as a profile.
|
|
42
135
|
|
|
43
136
|
## Refusals
|
|
44
137
|
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
{
|
|
2
|
+
"extends": "../tsconfig.json",
|
|
3
|
+
"compilerOptions": {
|
|
4
|
+
"rootDir": "..",
|
|
5
|
+
"noEmit": true,
|
|
6
|
+
"composite": false,
|
|
7
|
+
"incremental": false,
|
|
8
|
+
"paths": {
|
|
9
|
+
"@antelopejs/interface-database-catalog": ["../src/index.ts"]
|
|
10
|
+
}
|
|
11
|
+
},
|
|
12
|
+
"include": ["../src/**/*.ts", "./**/*.ts"]
|
|
13
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-database-catalog",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.3",
|
|
4
4
|
"description": "AntelopeJS interface for describing and profiling a connected database",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
@@ -43,8 +43,8 @@
|
|
|
43
43
|
"knip": "knip"
|
|
44
44
|
},
|
|
45
45
|
"devDependencies": {
|
|
46
|
-
"@antelopejs/interface-core": ">=0.2.
|
|
47
|
-
"@antelopejs/tooling-configs": "^0.0.
|
|
46
|
+
"@antelopejs/interface-core": ">=0.2.4 <1.0.0",
|
|
47
|
+
"@antelopejs/tooling-configs": "^0.0.9",
|
|
48
48
|
"@types/node": "^22.19.15",
|
|
49
49
|
"knip": "^6.34.0",
|
|
50
50
|
"oxfmt": "^0.66.0",
|
|
@@ -56,7 +56,7 @@
|
|
|
56
56
|
"typescript": "^5.9.3"
|
|
57
57
|
},
|
|
58
58
|
"peerDependencies": {
|
|
59
|
-
"@antelopejs/interface-core": ">=0.2.
|
|
59
|
+
"@antelopejs/interface-core": ">=0.2.4 <1.0.0"
|
|
60
60
|
},
|
|
61
61
|
"packageManager": "pnpm@10.6.5"
|
|
62
62
|
}
|