@antelopejs/interface-database-catalog 0.1.1-next.43.gdb3d6bc → 0.1.1-next.44.gee21aa3
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 +1 -0
- package/dist/testing.d.ts +30 -0
- package/dist/testing.js +64 -0
- package/dist/testing.js.map +1 -0
- package/docs/index.md +42 -0
- package/docs/tsconfig.json +2 -1
- package/package.json +12 -3
package/README.md
CHANGED
|
@@ -23,6 +23,7 @@ Describes and profiles a database that an [`@antelopejs/interface-database`](htt
|
|
|
23
23
|
- `CheckReference` measures how much of one column's values another column holds, for references the database does not declare.
|
|
24
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
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.
|
|
26
|
+
- `AssertNoRareValue`, from `@antelopejs/interface-database-catalog/testing`, fails a driver's test when a profile names a value its fixture counts fewer than 5 times.
|
|
26
27
|
|
|
27
28
|
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.
|
|
28
29
|
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import type { RelationProfile } from "./index";
|
|
2
|
+
/** The fewest rows a value must be counted in before a profile may name it. */
|
|
3
|
+
export declare const NAMED_VALUE_MIN_ROWS = 5;
|
|
4
|
+
/** A value a driver's fixture holds in a column, with the rows that hold it. */
|
|
5
|
+
export interface FixtureCount {
|
|
6
|
+
value: string | number | boolean;
|
|
7
|
+
rows: number;
|
|
8
|
+
}
|
|
9
|
+
/** A result set, or a part of one, as JSON reads it. */
|
|
10
|
+
export type ResultValue = string | number | boolean | null | ResultValue[] | {
|
|
11
|
+
[key: string]: ResultValue;
|
|
12
|
+
};
|
|
13
|
+
/** What one profile answered and received, and what the fixture it read holds. */
|
|
14
|
+
export interface ProfileUnderTest {
|
|
15
|
+
profile: RelationProfile;
|
|
16
|
+
/**
|
|
17
|
+
* Every result set the provider's connection received while it profiled. Each value in it is
|
|
18
|
+
* compared whole, as text, with each rare value.
|
|
19
|
+
*/
|
|
20
|
+
results: ResultValue[];
|
|
21
|
+
/** For each profiled column, how many rows of the fixture hold each of its values. */
|
|
22
|
+
counts: Record<string, FixtureCount[]>;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Throws when a profile names a value its fixture counts fewer than `NAMED_VALUE_MIN_ROWS` times:
|
|
26
|
+
* in a column's `range`, in its `categories`, or in any result set the connection received. A
|
|
27
|
+
* category counted fewer than `NAMED_VALUE_MIN_ROWS` times also throws. The error lists every
|
|
28
|
+
* leak.
|
|
29
|
+
*/
|
|
30
|
+
export declare function AssertNoRareValue({ profile, results, counts, }: ProfileUnderTest): void;
|
package/dist/testing.js
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.NAMED_VALUE_MIN_ROWS = void 0;
|
|
4
|
+
exports.AssertNoRareValue = AssertNoRareValue;
|
|
5
|
+
/** The fewest rows a value must be counted in before a profile may name it. */
|
|
6
|
+
exports.NAMED_VALUE_MIN_ROWS = 5;
|
|
7
|
+
function IsRow(value) {
|
|
8
|
+
return value instanceof Object;
|
|
9
|
+
}
|
|
10
|
+
function Leaves(value) {
|
|
11
|
+
if (Array.isArray(value)) {
|
|
12
|
+
return value.flatMap(Leaves);
|
|
13
|
+
}
|
|
14
|
+
if (IsRow(value)) {
|
|
15
|
+
return Object.values(value).flatMap(Leaves);
|
|
16
|
+
}
|
|
17
|
+
return [value];
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Throws when a profile names a value its fixture counts fewer than `NAMED_VALUE_MIN_ROWS` times:
|
|
21
|
+
* in a column's `range`, in its `categories`, or in any result set the connection received. A
|
|
22
|
+
* category counted fewer than `NAMED_VALUE_MIN_ROWS` times also throws. The error lists every
|
|
23
|
+
* leak.
|
|
24
|
+
*/
|
|
25
|
+
function AssertNoRareValue({ profile, results, counts, }) {
|
|
26
|
+
const leaks = [];
|
|
27
|
+
const rare = new Map();
|
|
28
|
+
for (const [column, values] of Object.entries(counts)) {
|
|
29
|
+
for (const { value, rows } of values) {
|
|
30
|
+
if (rows < exports.NAMED_VALUE_MIN_ROWS) {
|
|
31
|
+
rare.set(String(value), `${column}, counted ${rows} times`);
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
const check = (where, value) => {
|
|
36
|
+
const counted = rare.get(String(value));
|
|
37
|
+
if (counted !== undefined) {
|
|
38
|
+
leaks.push(`${where} names ${String(value)} (${counted})`);
|
|
39
|
+
}
|
|
40
|
+
};
|
|
41
|
+
for (const column of profile.columns) {
|
|
42
|
+
if (column.range?.status === "ok") {
|
|
43
|
+
check(`${column.name} range min`, column.range.value.min);
|
|
44
|
+
check(`${column.name} range max`, column.range.value.max);
|
|
45
|
+
}
|
|
46
|
+
if (column.categories?.status === "ok") {
|
|
47
|
+
for (const { value, rows } of column.categories.value.values) {
|
|
48
|
+
check(`${column.name} categories`, value);
|
|
49
|
+
if (rows < exports.NAMED_VALUE_MIN_ROWS) {
|
|
50
|
+
leaks.push(`${column.name} categories name ${String(value)}, counted ${rows} times`);
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
results.forEach((result, index) => {
|
|
56
|
+
for (const leaf of Leaves(result)) {
|
|
57
|
+
check(`result set ${index}`, leaf);
|
|
58
|
+
}
|
|
59
|
+
});
|
|
60
|
+
if (leaks.length > 0) {
|
|
61
|
+
throw new Error(`The profile of ${profile.relation} names rare values:\n${leaks.join("\n")}`);
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
//# sourceMappingURL=testing.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}
|
package/docs/index.md
CHANGED
|
@@ -144,6 +144,48 @@ Every function refuses:
|
|
|
144
144
|
- outside development;
|
|
145
145
|
- on a provider instance that owns its tables.
|
|
146
146
|
|
|
147
|
+
## Test that a profile names no rare value
|
|
148
|
+
|
|
149
|
+
A profile may name a value only when it counts it in at least `NAMED_VALUE_MIN_ROWS` (5) rows. `@antelopejs/interface-database-catalog/testing` exports `AssertNoRareValue`, which a driver's tests call with:
|
|
150
|
+
|
|
151
|
+
- `profile`, the `RelationProfile` the driver answered;
|
|
152
|
+
- `results`, every result set its connection received while it profiled, as JSON reads them;
|
|
153
|
+
- `counts`, for each profiled column, how many rows of the driver's fixture hold each value.
|
|
154
|
+
|
|
155
|
+
It throws, listing every leak, when a column's `range` or `categories`, or any value in a result set, names a value the fixture counts fewer than 5 times, and when a category is counted fewer than 5 times. Each value in a result set is compared whole, as text, so `"7001"` matches the number `7001` and `17001` does not.
|
|
156
|
+
|
|
157
|
+
```ts docs-check
|
|
158
|
+
import { Profile } from "@antelopejs/interface-database-catalog";
|
|
159
|
+
import {
|
|
160
|
+
AssertNoRareValue,
|
|
161
|
+
type ResultValue,
|
|
162
|
+
} from "@antelopejs/interface-database-catalog/testing";
|
|
163
|
+
|
|
164
|
+
/** The result sets the driver's connection receives, appended by the driver's own tap. */
|
|
165
|
+
const received: ResultValue[] = [];
|
|
166
|
+
|
|
167
|
+
it("names no level counted fewer than 5 times", async () => {
|
|
168
|
+
received.length = 0;
|
|
169
|
+
const profile = await Profile({
|
|
170
|
+
relation: "sales.grades",
|
|
171
|
+
columns: ["level"],
|
|
172
|
+
});
|
|
173
|
+
AssertNoRareValue({
|
|
174
|
+
profile,
|
|
175
|
+
results: received,
|
|
176
|
+
counts: {
|
|
177
|
+
level: [
|
|
178
|
+
{ value: 7001, rows: 4 },
|
|
179
|
+
{ value: 7002, rows: 5 },
|
|
180
|
+
{ value: 7008, rows: 5 },
|
|
181
|
+
],
|
|
182
|
+
},
|
|
183
|
+
});
|
|
184
|
+
});
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
A driver whose rows hold dates or buffers passes `JSON.parse(JSON.stringify(rows))`. A result set that legitimately names a rare value, such as an enum's declared labels, is left out of `results`.
|
|
188
|
+
|
|
147
189
|
## Probe a connection string
|
|
148
190
|
|
|
149
191
|
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.
|
package/docs/tsconfig.json
CHANGED
|
@@ -6,7 +6,8 @@
|
|
|
6
6
|
"composite": false,
|
|
7
7
|
"incremental": false,
|
|
8
8
|
"paths": {
|
|
9
|
-
"@antelopejs/interface-database-catalog": ["../src/index.ts"]
|
|
9
|
+
"@antelopejs/interface-database-catalog": ["../src/index.ts"],
|
|
10
|
+
"@antelopejs/interface-database-catalog/testing": ["../src/testing.ts"]
|
|
10
11
|
}
|
|
11
12
|
},
|
|
12
13
|
"include": ["../src/**/*.ts", "./**/*.ts"]
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-database-catalog",
|
|
3
|
-
"version": "0.1.1-next.
|
|
3
|
+
"version": "0.1.1-next.44.gee21aa3",
|
|
4
4
|
"description": "AntelopeJS interface for describing and profiling a connected database",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
},
|
|
17
17
|
"files": [
|
|
18
18
|
"dist",
|
|
19
|
+
"!dist/test",
|
|
19
20
|
"docs"
|
|
20
21
|
],
|
|
21
22
|
"main": "dist/index.js",
|
|
@@ -25,6 +26,10 @@
|
|
|
25
26
|
"types": "./dist/index.d.ts",
|
|
26
27
|
"default": "./dist/index.js"
|
|
27
28
|
},
|
|
29
|
+
"./testing": {
|
|
30
|
+
"types": "./dist/testing.d.ts",
|
|
31
|
+
"default": "./dist/testing.js"
|
|
32
|
+
},
|
|
28
33
|
"./package.json": "./package.json"
|
|
29
34
|
},
|
|
30
35
|
"publishConfig": {
|
|
@@ -35,9 +40,13 @@
|
|
|
35
40
|
"@antelopejs/core": "~1.23.3",
|
|
36
41
|
"@antelopejs/interface-core": ">=0.5.0 <0.6.0",
|
|
37
42
|
"@antelopejs/tooling-configs": ">=0.8.9 <0.9.0",
|
|
43
|
+
"@types/chai": "^4.3.20",
|
|
44
|
+
"@types/mocha": "^10.0.10",
|
|
38
45
|
"@types/node": "^22.19.15",
|
|
46
|
+
"chai": "^4.5.0",
|
|
39
47
|
"knip": "^6.34.0",
|
|
40
48
|
"lefthook": "^2.2.2",
|
|
49
|
+
"mocha": "^11.7.5",
|
|
41
50
|
"oxfmt": "^0.77.0",
|
|
42
51
|
"oxlint": "1.81.0",
|
|
43
52
|
"oxlint-tsgolint": "^7.0.2001",
|
|
@@ -54,11 +63,11 @@
|
|
|
54
63
|
"standard": true
|
|
55
64
|
}
|
|
56
65
|
},
|
|
57
|
-
"gitHead": "
|
|
66
|
+
"gitHead": "ee21aa3b766594c3a6c0381fa4e74bea0424cf13",
|
|
58
67
|
"scripts": {
|
|
59
68
|
"build": "rimraf dist && tsc --skipLibCheck",
|
|
60
69
|
"typecheck": "tsc --noEmit",
|
|
61
|
-
"test": "pnpm run build",
|
|
70
|
+
"test": "pnpm run build && mocha --reporter dot 'dist/test/**/*.test.js'",
|
|
62
71
|
"format": "oxfmt .",
|
|
63
72
|
"lint:fix": "oxlint --fix",
|
|
64
73
|
"lint": "oxlint",
|