@htilabs/platform-common-models 0.8.13 → 0.8.15
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 +44 -0
- package/dist/config/index.cjs +4 -0
- package/dist/config/index.cjs.map +1 -1
- package/dist/config/index.d.cts +16 -1
- package/dist/config/index.d.ts +16 -1
- package/dist/config/index.js +2 -0
- package/dist/config/index.js.map +1 -1
- package/dist/constants/index.cjs +10 -0
- package/dist/constants/index.cjs.map +1 -1
- package/dist/constants/index.d.cts +1 -1
- package/dist/constants/index.d.ts +1 -1
- package/dist/constants/index.js +10 -0
- package/dist/constants/index.js.map +1 -1
- package/dist/cvcs/index.cjs +601 -2
- package/dist/cvcs/index.cjs.map +1 -1
- package/dist/cvcs/index.d.cts +2754 -2084
- package/dist/cvcs/index.d.ts +2754 -2084
- package/dist/cvcs/index.js +594 -2
- package/dist/cvcs/index.js.map +1 -1
- package/dist/{index-I-DiX9eQ.d.ts → index-CDoqrfc1.d.ts} +1 -1
- package/dist/{index-CoVr1jIV.d.cts → index-Zu_mOJRn.d.cts} +1 -1
- package/dist/index.cjs +709 -4
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +154 -7
- package/dist/index.d.ts +154 -7
- package/dist/index.js +693 -4
- package/dist/index.js.map +1 -1
- package/dist/models/index.d.cts +2 -2
- package/dist/models/index.d.ts +2 -2
- package/dist/mongo/index.cjs +383 -0
- package/dist/mongo/index.cjs.map +1 -0
- package/dist/mongo/index.d.cts +221 -0
- package/dist/mongo/index.d.ts +221 -0
- package/dist/mongo/index.js +351 -0
- package/dist/mongo/index.js.map +1 -0
- package/dist/{platform-auth-BfCMuAlC.d.cts → platform-auth-AsfnIXfK.d.cts} +2 -2
- package/dist/{platform-auth-BfCMuAlC.d.ts → platform-auth-AsfnIXfK.d.ts} +2 -2
- package/dist/schemas/index.cjs +5 -1
- package/dist/schemas/index.cjs.map +1 -1
- package/dist/schemas/index.d.cts +29 -25
- package/dist/schemas/index.d.ts +29 -25
- package/dist/schemas/index.js +5 -1
- package/dist/schemas/index.js.map +1 -1
- package/dist/types/index.d.cts +2 -2
- package/dist/types/index.d.ts +2 -2
- package/package.json +10 -1
- package/src/__sot__/coreIndicators.pin.json +6 -1
- package/src/__tests__/__snapshots__/cvc-sot.snap +18 -2
- package/src/__tests__/cvc-136-scoring-invariant.test.ts +6 -3
- package/src/__tests__/cvc-drift-gate.test.ts +14 -3
- package/src/__tests__/cvc-sot-snapshot.test.ts +13 -1
- package/src/__tests__/cvc-structural.test.ts +6 -0
- package/src/__tests__/mongo-verifier.test.ts +502 -0
- package/src/config/index.ts +8 -2
- package/src/constants/ic.ts +31 -2
- package/src/cvcs/assertionStatus.v1.0.0.json +80 -0
- package/src/cvcs/caseShareState.v1.0.0.json +62 -0
- package/src/cvcs/coreIndicators.v1.0.0.json +67 -2
- package/src/cvcs/createdBySystem.v1.0.0.json +89 -0
- package/src/cvcs/criminalOrgCategory.v1.0.0.json +116 -0
- package/src/cvcs/hmisSex.v1.0.0.json +89 -0
- package/src/cvcs/index.ts +22 -0
- package/src/cvcs/minorAdultStatus.v1.0.0.json +80 -0
- package/src/cvcs/referralOrigin.v1.0.0.json +26 -0
- package/src/cvcs/subjectType.v1.0.0.json +80 -0
- package/src/generated/cvc-enums.ts +125 -2
- package/src/index.ts +20 -0
- package/src/mongo/catalog.ts +65 -0
- package/src/mongo/contract.ts +157 -0
- package/src/mongo/index.ts +343 -0
- package/src/mongo/similarity.ts +133 -0
- package/src/mongo/uri.ts +53 -0
- package/src/schemas/common.ts +4 -0
- package/dist/{cvcEntry-BCj1OWqL.d.cts → cvcEntry-0BIB9sen.d.cts} +8 -8
- package/dist/{cvcEntry-BCj1OWqL.d.ts → cvcEntry-0BIB9sen.d.ts} +8 -8
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
{
|
|
2
|
+
"domain": "referral_origin",
|
|
3
|
+
"name": "Core Referral Origin",
|
|
4
|
+
"version": "1.0.0",
|
|
5
|
+
"levels": { "1": "Origin" },
|
|
6
|
+
"entries": [
|
|
7
|
+
{
|
|
8
|
+
"code": "909-001-000-000-000-000-000",
|
|
9
|
+
"key": "internal",
|
|
10
|
+
"title": "Internal",
|
|
11
|
+
"selectable": true,
|
|
12
|
+
"parentCode": null,
|
|
13
|
+
"childCodes": [],
|
|
14
|
+
"definition": "A referral whose sending and receiving parties sit within the same agency or account boundary, so completing it involves no disclosure of client information across an organizational boundary."
|
|
15
|
+
},
|
|
16
|
+
{
|
|
17
|
+
"code": "909-002-000-000-000-000-000",
|
|
18
|
+
"key": "external",
|
|
19
|
+
"title": "External",
|
|
20
|
+
"selectable": true,
|
|
21
|
+
"parentCode": null,
|
|
22
|
+
"childCodes": [],
|
|
23
|
+
"definition": "A referral whose receiving party is a different agency, making acceptance a cross-agency disclosure of client information. Where an implementation cannot positively determine the origin, it must treat the referral as external, so that the stronger disclosure controls apply by default rather than the weaker ones."
|
|
24
|
+
}
|
|
25
|
+
]
|
|
26
|
+
}
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
{
|
|
2
|
+
"domain": "subject_type",
|
|
3
|
+
"name": "Subject Type",
|
|
4
|
+
"version": "1.0.0",
|
|
5
|
+
"_status": "PROVISIONAL — GDR §10.1 confirmed-CVC name is `core - subject_type`, but Final CVCs/CVC_INDEX.md @ a596eb9 carries no number for it, so it parks in the provisional 900-block pending canonical Notion authoring + steward ratification. Substantive values sourced verbatim from the PAVE @pave/domain `SUBJECT_TYPES` enum (D10 GDR §10.1 bulk publish, bead pv-pgdr-cvc-source-gdr-10-1-bulk-publish). The PAVE enum enumerates only the substantive entity kinds, so the missingness quadruplet is added per SOT convention.",
|
|
6
|
+
"_source": "pave-2.0/packages/domain/src/enums.ts SUBJECT_TYPES",
|
|
7
|
+
"levels": {
|
|
8
|
+
"0": "Unknown or Missing",
|
|
9
|
+
"1": "Assertion subject type"
|
|
10
|
+
},
|
|
11
|
+
"entries": [
|
|
12
|
+
{
|
|
13
|
+
"code": "987-000-000-000-000-000-000",
|
|
14
|
+
"key": "missingness_root",
|
|
15
|
+
"title": "Unknown, Redacted, or Missing",
|
|
16
|
+
"selectable": false,
|
|
17
|
+
"parentCode": null,
|
|
18
|
+
"childCodes": [
|
|
19
|
+
"987-000-000-000-000-000-001",
|
|
20
|
+
"987-000-000-000-000-000-002",
|
|
21
|
+
"987-000-000-000-000-000-003"
|
|
22
|
+
],
|
|
23
|
+
"definition": "Root group for values indicating absent, withheld, or uncollected data."
|
|
24
|
+
},
|
|
25
|
+
{
|
|
26
|
+
"code": "987-000-000-000-000-000-001",
|
|
27
|
+
"key": "unknown",
|
|
28
|
+
"title": "Unknown",
|
|
29
|
+
"selectable": true,
|
|
30
|
+
"parentCode": "987-000-000-000-000-000-000",
|
|
31
|
+
"childCodes": [],
|
|
32
|
+
"definition": "The subject type is unknown at time of entry (missingness sentinel)."
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
"code": "987-000-000-000-000-000-002",
|
|
36
|
+
"key": "anonymous",
|
|
37
|
+
"title": "Anonymous / declined to answer",
|
|
38
|
+
"selectable": true,
|
|
39
|
+
"parentCode": "987-000-000-000-000-000-000",
|
|
40
|
+
"childCodes": [],
|
|
41
|
+
"definition": "Value is intentionally withheld, declined, or redacted."
|
|
42
|
+
},
|
|
43
|
+
{
|
|
44
|
+
"code": "987-000-000-000-000-000-003",
|
|
45
|
+
"key": "data_not_collected",
|
|
46
|
+
"title": "Data not collected",
|
|
47
|
+
"selectable": true,
|
|
48
|
+
"parentCode": "987-000-000-000-000-000-000",
|
|
49
|
+
"childCodes": [],
|
|
50
|
+
"definition": "No attempt was made to collect the value."
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
"code": "987-001-000-000-000-000-000",
|
|
54
|
+
"key": "person",
|
|
55
|
+
"title": "Person",
|
|
56
|
+
"selectable": true,
|
|
57
|
+
"parentCode": null,
|
|
58
|
+
"childCodes": [],
|
|
59
|
+
"definition": "The assertion is about a person; `subject_id` resolves to a person record. Emitting systems typically default to this value (e.g. PAVE's assertion factory defaults `subjectType: \"person\"`)."
|
|
60
|
+
},
|
|
61
|
+
{
|
|
62
|
+
"code": "987-002-000-000-000-000-000",
|
|
63
|
+
"key": "relationship",
|
|
64
|
+
"title": "Relationship",
|
|
65
|
+
"selectable": true,
|
|
66
|
+
"parentCode": null,
|
|
67
|
+
"childCodes": [],
|
|
68
|
+
"definition": "The assertion is about a relationship between people; `subject_id` resolves to a relationship record."
|
|
69
|
+
},
|
|
70
|
+
{
|
|
71
|
+
"code": "987-003-000-000-000-000-000",
|
|
72
|
+
"key": "case",
|
|
73
|
+
"title": "Case",
|
|
74
|
+
"selectable": true,
|
|
75
|
+
"parentCode": null,
|
|
76
|
+
"childCodes": [],
|
|
77
|
+
"definition": "The assertion is about a case; `subject_id` resolves to a case record."
|
|
78
|
+
}
|
|
79
|
+
]
|
|
80
|
+
}
|
|
@@ -889,6 +889,34 @@ export const SharePurposeKeys = {
|
|
|
889
889
|
|
|
890
890
|
export type SharePurposeKey = keyof typeof SharePurposeKeys;
|
|
891
891
|
|
|
892
|
+
/**
|
|
893
|
+
* Key → positional code map for the `referral_origin` CVC domain.
|
|
894
|
+
*
|
|
895
|
+
* Domain: `referral_origin` · Version: 1.0.0 · Entries: 2
|
|
896
|
+
*/
|
|
897
|
+
export const ReferralOriginKeys = {
|
|
898
|
+
internal: "909-001-000-000-000-000-000",
|
|
899
|
+
external: "909-002-000-000-000-000-000",
|
|
900
|
+
} as const;
|
|
901
|
+
|
|
902
|
+
export type ReferralOriginKey = keyof typeof ReferralOriginKeys;
|
|
903
|
+
|
|
904
|
+
/**
|
|
905
|
+
* Key → positional code map for the `case_share_state` CVC domain.
|
|
906
|
+
*
|
|
907
|
+
* Domain: `case_share_state` · Version: 1.0.0 · Entries: 6
|
|
908
|
+
*/
|
|
909
|
+
export const CaseShareStateKeys = {
|
|
910
|
+
pending: "925-001-000-000-000-000-000",
|
|
911
|
+
claimed: "925-002-000-000-000-000-000",
|
|
912
|
+
accepted_awaiting_review: "925-003-000-000-000-000-000",
|
|
913
|
+
accepted: "925-004-000-000-000-000-000",
|
|
914
|
+
declined: "925-005-000-000-000-000-000",
|
|
915
|
+
rejected: "925-006-000-000-000-000-000",
|
|
916
|
+
} as const;
|
|
917
|
+
|
|
918
|
+
export type CaseShareStateKey = keyof typeof CaseShareStateKeys;
|
|
919
|
+
|
|
892
920
|
/**
|
|
893
921
|
* Key → positional code map for the `facilitator_entity_type` CVC domain.
|
|
894
922
|
*
|
|
@@ -4118,9 +4146,9 @@ export const DhStateKeys = {
|
|
|
4118
4146
|
export type DhStateKey = keyof typeof DhStateKeys;
|
|
4119
4147
|
|
|
4120
4148
|
/**
|
|
4121
|
-
* Key → positional code map for the `core_indicators` CVC domain (CVC-136;
|
|
4149
|
+
* Key → positional code map for the `core_indicators` CVC domain (CVC-136; 215 canonical indicator codes re-sourced from prototype `data/core_indicators.yaml` @ 84a1b677 plus the 2 codes @hti/scoring emits ahead of the codebook). Entries carry `family` / `polarity` / `severity` / `isAlert` / `alertWhen`; the alert list is a DERIVED VIEW over `isAlert`, not a rival taxonomy.
|
|
4122
4150
|
*
|
|
4123
|
-
* Domain: `core_indicators` · Version: 1.0.0 · Entries:
|
|
4151
|
+
* Domain: `core_indicators` · Version: 1.0.0 · Entries: 219
|
|
4124
4152
|
*/
|
|
4125
4153
|
export const CoreIndicatorKeys = {
|
|
4126
4154
|
missingness_root: "136-000-000-000-000-000-000",
|
|
@@ -4337,6 +4365,11 @@ export const CoreIndicatorKeys = {
|
|
|
4337
4365
|
works_across_multiple_cities_or_locations: "136-208-000-000-000-000-000",
|
|
4338
4366
|
works_for_little_or_no_pay: "136-209-000-000-000-000-000",
|
|
4339
4367
|
youth_watched_filmed_or_photographed_sexually_explicit: "136-210-000-000-000-000-000",
|
|
4368
|
+
clients_unaware_of_third_party_coordination: "136-211-000-000-000-000-000",
|
|
4369
|
+
depends_on_spouse_or_family_for_immigration_status: "136-212-000-000-000-000-000",
|
|
4370
|
+
sexualized_content_in_person_performance_activity: "136-213-000-000-000-000-000",
|
|
4371
|
+
sexualized_content_online_performance_activity: "136-214-000-000-000-000-000",
|
|
4372
|
+
trauma_perpetrator_is_current_manager: "136-215-000-000-000-000-000",
|
|
4340
4373
|
} as const;
|
|
4341
4374
|
|
|
4342
4375
|
export type CoreIndicatorKey = keyof typeof CoreIndicatorKeys;
|
|
@@ -5025,3 +5058,93 @@ export const WhyNotKeys = {
|
|
|
5025
5058
|
} as const;
|
|
5026
5059
|
|
|
5027
5060
|
export type WhyNotKey = keyof typeof WhyNotKeys;
|
|
5061
|
+
|
|
5062
|
+
/**
|
|
5063
|
+
* Key → positional code map for the `assertion_status` CVC domain (GDR §10.1 `core - status`; assertion lifecycle status; PROVISIONAL, pending Notion ratification).
|
|
5064
|
+
*
|
|
5065
|
+
* Domain: `assertion_status` · Version: 1.0.0 · Entries: 7
|
|
5066
|
+
*/
|
|
5067
|
+
export const AssertionStatusKeys = {
|
|
5068
|
+
missingness_root: "985-000-000-000-000-000-000",
|
|
5069
|
+
unknown: "985-000-000-000-000-000-001",
|
|
5070
|
+
anonymous: "985-000-000-000-000-000-002",
|
|
5071
|
+
data_not_collected: "985-000-000-000-000-000-003",
|
|
5072
|
+
active: "985-001-000-000-000-000-000",
|
|
5073
|
+
superseded: "985-002-000-000-000-000-000",
|
|
5074
|
+
retracted: "985-003-000-000-000-000-000",
|
|
5075
|
+
} as const;
|
|
5076
|
+
|
|
5077
|
+
export type AssertionStatusKey = keyof typeof AssertionStatusKeys;
|
|
5078
|
+
|
|
5079
|
+
/**
|
|
5080
|
+
* Key → positional code map for the `created_by_system` CVC domain (GDR §10.1 `core - created_by_system`; creating actor class; PROVISIONAL, pending Notion ratification).
|
|
5081
|
+
*
|
|
5082
|
+
* Domain: `created_by_system` · Version: 1.0.0 · Entries: 8
|
|
5083
|
+
*/
|
|
5084
|
+
export const CreatedBySystemKeys = {
|
|
5085
|
+
missingness_root: "986-000-000-000-000-000-000",
|
|
5086
|
+
unknown: "986-000-000-000-000-000-001",
|
|
5087
|
+
anonymous: "986-000-000-000-000-000-002",
|
|
5088
|
+
data_not_collected: "986-000-000-000-000-000-003",
|
|
5089
|
+
human: "986-001-000-000-000-000-000",
|
|
5090
|
+
integration: "986-002-000-000-000-000-000",
|
|
5091
|
+
rules_engine: "986-003-000-000-000-000-000",
|
|
5092
|
+
model: "986-004-000-000-000-000-000",
|
|
5093
|
+
} as const;
|
|
5094
|
+
|
|
5095
|
+
export type CreatedBySystemKey = keyof typeof CreatedBySystemKeys;
|
|
5096
|
+
|
|
5097
|
+
/**
|
|
5098
|
+
* Key → positional code map for the `subject_type` CVC domain (GDR §10.1 `core - subject_type`; assertion subject type; PROVISIONAL, pending Notion ratification).
|
|
5099
|
+
*
|
|
5100
|
+
* Domain: `subject_type` · Version: 1.0.0 · Entries: 7
|
|
5101
|
+
*/
|
|
5102
|
+
export const SubjectTypeKeys = {
|
|
5103
|
+
missingness_root: "987-000-000-000-000-000-000",
|
|
5104
|
+
unknown: "987-000-000-000-000-000-001",
|
|
5105
|
+
anonymous: "987-000-000-000-000-000-002",
|
|
5106
|
+
data_not_collected: "987-000-000-000-000-000-003",
|
|
5107
|
+
person: "987-001-000-000-000-000-000",
|
|
5108
|
+
relationship: "987-002-000-000-000-000-000",
|
|
5109
|
+
case: "987-003-000-000-000-000-000",
|
|
5110
|
+
} as const;
|
|
5111
|
+
|
|
5112
|
+
export type SubjectTypeKey = keyof typeof SubjectTypeKeys;
|
|
5113
|
+
|
|
5114
|
+
/**
|
|
5115
|
+
* Key → positional code map for the `minor_adult_status` CVC domain (GDR §10.1 `core - minor_adult_status`; age band at event; PROVISIONAL at 988 — canonical CVC-61 exists in the index but its Notion codebook is empty, see ADR-CVC-0.8.13 NARRATIVE_ONLY; renumber 988→61 on Notion authoring).
|
|
5116
|
+
*
|
|
5117
|
+
* Domain: `minor_adult_status` · Version: 1.0.0 · Entries: 7
|
|
5118
|
+
*/
|
|
5119
|
+
export const MinorAdultStatusKeys = {
|
|
5120
|
+
missingness_root: "988-000-000-000-000-000-000",
|
|
5121
|
+
unknown: "988-000-000-000-000-000-001",
|
|
5122
|
+
anonymous: "988-000-000-000-000-000-002",
|
|
5123
|
+
data_not_collected: "988-000-000-000-000-000-003",
|
|
5124
|
+
minor: "988-001-000-000-000-000-000",
|
|
5125
|
+
adult: "988-002-000-000-000-000-000",
|
|
5126
|
+
indeterminate: "988-003-000-000-000-000-000",
|
|
5127
|
+
} as const;
|
|
5128
|
+
|
|
5129
|
+
export type MinorAdultStatusKey = keyof typeof MinorAdultStatusKeys;
|
|
5130
|
+
|
|
5131
|
+
/**
|
|
5132
|
+
* Key → positional code map for the `criminal_org_category` CVC domain (WIKI 7-type taxonomy for the criminal-org registry; ported from prototype/data/cvcs/core_criminal_org_category.yaml; PROVISIONAL at 990 — net-new, PENDING canonical Notion authoring).
|
|
5133
|
+
*
|
|
5134
|
+
* Domain: `criminal_org_category` · Version: 1.0.0 · Entries: 11
|
|
5135
|
+
*/
|
|
5136
|
+
export const CriminalOrgCategoryKeys = {
|
|
5137
|
+
missingness_root: "990-000-000-000-000-000-000",
|
|
5138
|
+
unknown: "990-000-000-000-000-000-001",
|
|
5139
|
+
anonymous: "990-000-000-000-000-000-002",
|
|
5140
|
+
data_not_collected: "990-000-000-000-000-000-003",
|
|
5141
|
+
street_gang: "990-001-000-000-000-000-000",
|
|
5142
|
+
prison_gang: "990-002-000-000-000-000-000",
|
|
5143
|
+
outlaw_motorcycle_gang: "990-003-000-000-000-000-000",
|
|
5144
|
+
tco_cartel: "990-004-000-000-000-000-000",
|
|
5145
|
+
white_supremacist_extremist: "990-005-000-000-000-000-000",
|
|
5146
|
+
organized_crime_family: "990-006-000-000-000-000-000",
|
|
5147
|
+
familial_or_independent_trafficking_network: "990-007-000-000-000-000-000",
|
|
5148
|
+
} as const;
|
|
5149
|
+
|
|
5150
|
+
export type CriminalOrgCategoryKey = keyof typeof CriminalOrgCategoryKeys;
|
package/src/index.ts
CHANGED
|
@@ -88,3 +88,23 @@ export { compileModel as compileCvcEntryModel } from "./models/cvcEntryModel.js"
|
|
|
88
88
|
// filesystem access. See `./cvcs/index.ts` for the full list and naming.
|
|
89
89
|
|
|
90
90
|
export * from "./cvcs/index.js";
|
|
91
|
+
|
|
92
|
+
// ─── SOT-first CVC flat-array aliases ───────────────────────────────────────
|
|
93
|
+
// Legacy-shaped `CVC_<N>_VALUES` arrays for CVCs that are SOT-native (no
|
|
94
|
+
// ic.ts constants). Derived from the SOT JSON envelope's `entries` filtered
|
|
95
|
+
// to `selectable: true` so the SOT JSON remains the single source of truth
|
|
96
|
+
// AND the non-selectable `missingness_root` grouping code is excluded (it
|
|
97
|
+
// would otherwise fail schema enum validation on write).
|
|
98
|
+
|
|
99
|
+
import recencyBandSot from "./cvcs/recencyBand.v1.0.0.json" with { type: "json" };
|
|
100
|
+
import juvenileJusticeEpisodeTypeSot from "./cvcs/juvenileJusticeEpisodeType.v1.0.0.json" with { type: "json" };
|
|
101
|
+
|
|
102
|
+
const selectableCodes = (envelope: {
|
|
103
|
+
entries: ReadonlyArray<{ code: string; selectable: boolean }>;
|
|
104
|
+
}): string[] =>
|
|
105
|
+
envelope.entries.filter((e) => e.selectable).map((e) => e.code);
|
|
106
|
+
|
|
107
|
+
export const CVC_137_VALUES: string[] = selectableCodes(recencyBandSot);
|
|
108
|
+
export const CVC_197_VALUES: string[] = selectableCodes(
|
|
109
|
+
juvenileJusticeEpisodeTypeSot,
|
|
110
|
+
);
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @htilabs/platform-common-models — read-only MongoDB catalogue
|
|
3
|
+
*
|
|
4
|
+
* The verifier reaches MongoDB ONLY through this interface. It exposes two
|
|
5
|
+
* read operations and nothing else: there is no method here that can create,
|
|
6
|
+
* write, or drop anything. The read-only guarantee is enforced by the type,
|
|
7
|
+
* not by convention.
|
|
8
|
+
*
|
|
9
|
+
* Injecting the catalogue also keeps the package's test suite free of a real
|
|
10
|
+
* MongoDB, matching how `runCvcBootCheck` injects `exit` and `logger`.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
export interface MongoCatalog {
|
|
14
|
+
/** Names of databases that physically exist (i.e. hold data). */
|
|
15
|
+
listDatabases(): Promise<string[]>;
|
|
16
|
+
/** Names of collections that physically exist in `database`. */
|
|
17
|
+
listCollections(database: string): Promise<string[]>;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Minimal structural view of a `mongodb` MongoClient. Declared structurally so
|
|
22
|
+
* this package takes no dependency on the `mongodb` driver — apps pass their
|
|
23
|
+
* own client, whatever major version they are on.
|
|
24
|
+
*/
|
|
25
|
+
export interface MongoClientLike {
|
|
26
|
+
db(name?: string): {
|
|
27
|
+
admin(): {
|
|
28
|
+
listDatabases(): Promise<{ databases: Array<{ name: string }> }>;
|
|
29
|
+
};
|
|
30
|
+
listCollections(
|
|
31
|
+
filter?: Record<string, unknown>,
|
|
32
|
+
options?: Record<string, unknown>,
|
|
33
|
+
): { toArray(): Promise<Array<{ name: string }>> };
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Minimal structural view of a Mongoose Connection. */
|
|
38
|
+
export interface MongooseConnectionLike {
|
|
39
|
+
getClient(): MongoClientLike;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Build a catalogue from a native `mongodb` client. */
|
|
43
|
+
export function catalogFromClient(client: MongoClientLike): MongoCatalog {
|
|
44
|
+
return {
|
|
45
|
+
async listDatabases(): Promise<string[]> {
|
|
46
|
+
const { databases } = await client.db().admin().listDatabases();
|
|
47
|
+
return databases.map((d) => d.name);
|
|
48
|
+
},
|
|
49
|
+
async listCollections(database: string): Promise<string[]> {
|
|
50
|
+
// `nameOnly` keeps the server from materializing collection options.
|
|
51
|
+
const infos = await client
|
|
52
|
+
.db(database)
|
|
53
|
+
.listCollections({}, { nameOnly: true })
|
|
54
|
+
.toArray();
|
|
55
|
+
return infos.map((c) => c.name);
|
|
56
|
+
},
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** Build a catalogue from an open Mongoose connection. */
|
|
61
|
+
export function catalogFromMongoose(
|
|
62
|
+
connection: MongooseConnectionLike,
|
|
63
|
+
): MongoCatalog {
|
|
64
|
+
return catalogFromClient(connection.getClient());
|
|
65
|
+
}
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @htilabs/platform-common-models — `mongo:` contract block
|
|
3
|
+
*
|
|
4
|
+
* Extends the HTI Runtime Config Contract (`config/runtime/<service>.yaml`)
|
|
5
|
+
* with a declaration of the databases and collections a service expects.
|
|
6
|
+
*
|
|
7
|
+
* The declaration is deliberately data, not code: `expansion` is Python and
|
|
8
|
+
* parses the same YAML. Nothing here may depend on a TypeScript-only construct.
|
|
9
|
+
*
|
|
10
|
+
* ## Why declared rather than introspected
|
|
11
|
+
*
|
|
12
|
+
* Reading collection names off registered Mongoose models would cover only the
|
|
13
|
+
* Mongoose apps (thread, leads, pave) and would report false findings: thread
|
|
14
|
+
* registers `AgencyInfo` (collection `agencyinfos`), which exists in NO
|
|
15
|
+
* database because nothing has ever written to it. Mongo creates collections
|
|
16
|
+
* lazily. A declaration states intent; introspection only restates the code.
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
/** One database a service connects to, and the collections it uses. */
|
|
20
|
+
export interface MongoDbSpec {
|
|
21
|
+
/** Contract variable holding the database NAME (e.g. `THREAD_DB`). */
|
|
22
|
+
db_var: string;
|
|
23
|
+
/**
|
|
24
|
+
* Contract variable holding the connection URI or cluster prefix
|
|
25
|
+
* (e.g. `MONGODB_CLUSTER`). When the URI already embeds a database name and
|
|
26
|
+
* no `db_var` applies, set `db_var` to the same variable — the name is then
|
|
27
|
+
* parsed out of the URI.
|
|
28
|
+
*/
|
|
29
|
+
uri_var: string;
|
|
30
|
+
/**
|
|
31
|
+
* Collections the service reads or writes. Declare only what the service
|
|
32
|
+
* USES — not everything present in the database. An undeclared collection
|
|
33
|
+
* present in Mongo is reported, never fatal.
|
|
34
|
+
*
|
|
35
|
+
* An EMPTY list opts out of collection checking entirely: only the database
|
|
36
|
+
* name is verified, and `listCollections` is never called. Use it when a
|
|
37
|
+
* service reaches a database whose collections it cannot practically
|
|
38
|
+
* enumerate. Declaring even one collection opts back in.
|
|
39
|
+
*/
|
|
40
|
+
collections: string[];
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Per-environment database-name affinity. When the deploy environment has an
|
|
45
|
+
* entry here, every resolved database name must end with the given suffix.
|
|
46
|
+
*
|
|
47
|
+
* This generalizes thread's `assertTestDb` (packages/db/src/connections.ts):
|
|
48
|
+
* it is the only check that catches a test run pointed at a production
|
|
49
|
+
* database, and it needs no connection to MongoDB.
|
|
50
|
+
*/
|
|
51
|
+
export type EnvAffinity = Record<string, string>;
|
|
52
|
+
|
|
53
|
+
export interface MongoContractBlock {
|
|
54
|
+
/** e.g. `{ test: "-test", dev: "-dev" }`. Environments omitted are unconstrained. */
|
|
55
|
+
env_affinity?: EnvAffinity;
|
|
56
|
+
databases: MongoDbSpec[];
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Prefix for every diagnostic this module emits. */
|
|
60
|
+
const TAG = "[platform-common/mongo]";
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Validate and normalize the `mongo:` block of a parsed contract.
|
|
64
|
+
*
|
|
65
|
+
* Returns `null` when the contract declares no `mongo:` block — a service that
|
|
66
|
+
* does not use MongoDB is not an error.
|
|
67
|
+
*
|
|
68
|
+
* Throws on a malformed block: a contract that lies about its shape is a
|
|
69
|
+
* programming error, not a runtime finding.
|
|
70
|
+
*/
|
|
71
|
+
export function parseMongoBlock(
|
|
72
|
+
raw: unknown,
|
|
73
|
+
contractPath: string,
|
|
74
|
+
): MongoContractBlock | null {
|
|
75
|
+
if (raw === undefined || raw === null) return null;
|
|
76
|
+
|
|
77
|
+
if (typeof raw !== "object" || Array.isArray(raw)) {
|
|
78
|
+
throw new Error(`${TAG} ${contractPath}: "mongo" must be a mapping`);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
const block = raw as Partial<MongoContractBlock>;
|
|
82
|
+
|
|
83
|
+
if (!Array.isArray(block.databases) || block.databases.length === 0) {
|
|
84
|
+
throw new Error(
|
|
85
|
+
`${TAG} ${contractPath}: "mongo.databases" must be a non-empty list`,
|
|
86
|
+
);
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
block.databases.forEach((db, i) => {
|
|
90
|
+
const where = `${contractPath}: mongo.databases[${i}]`;
|
|
91
|
+
if (!db || typeof db !== "object") {
|
|
92
|
+
throw new Error(`${TAG} ${where} must be a mapping`);
|
|
93
|
+
}
|
|
94
|
+
if (typeof db.db_var !== "string" || db.db_var.length === 0) {
|
|
95
|
+
throw new Error(`${TAG} ${where}.db_var must be a non-empty string`);
|
|
96
|
+
}
|
|
97
|
+
if (typeof db.uri_var !== "string" || db.uri_var.length === 0) {
|
|
98
|
+
throw new Error(`${TAG} ${where}.uri_var must be a non-empty string`);
|
|
99
|
+
}
|
|
100
|
+
if (!Array.isArray(db.collections)) {
|
|
101
|
+
throw new Error(`${TAG} ${where}.collections must be a list`);
|
|
102
|
+
}
|
|
103
|
+
db.collections.forEach((c, j) => {
|
|
104
|
+
if (typeof c !== "string" || c.length === 0) {
|
|
105
|
+
throw new Error(
|
|
106
|
+
`${TAG} ${where}.collections[${j}] must be a non-empty string`,
|
|
107
|
+
);
|
|
108
|
+
}
|
|
109
|
+
});
|
|
110
|
+
});
|
|
111
|
+
|
|
112
|
+
if (block.env_affinity !== undefined) {
|
|
113
|
+
if (typeof block.env_affinity !== "object" || Array.isArray(block.env_affinity)) {
|
|
114
|
+
throw new Error(
|
|
115
|
+
`${TAG} ${contractPath}: "mongo.env_affinity" must be a mapping of env -> suffix`,
|
|
116
|
+
);
|
|
117
|
+
}
|
|
118
|
+
for (const [env, suffix] of Object.entries(block.env_affinity)) {
|
|
119
|
+
if (typeof suffix !== "string" || suffix.length === 0) {
|
|
120
|
+
throw new Error(
|
|
121
|
+
`${TAG} ${contractPath}: mongo.env_affinity.${env} must be a non-empty string`,
|
|
122
|
+
);
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
return {
|
|
128
|
+
env_affinity: block.env_affinity,
|
|
129
|
+
databases: block.databases as MongoDbSpec[],
|
|
130
|
+
};
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Check a resolved database name against the environment's affinity suffix.
|
|
135
|
+
*
|
|
136
|
+
* Returns `null` when the name is acceptable (or the environment declares no
|
|
137
|
+
* affinity), otherwise a human-readable violation message.
|
|
138
|
+
*
|
|
139
|
+
* Requires NO MongoDB connection. This is the check that catches
|
|
140
|
+
* `NODE_ENV=test` pointed at `platform-db`.
|
|
141
|
+
*/
|
|
142
|
+
export function checkEnvAffinity(
|
|
143
|
+
dbName: string,
|
|
144
|
+
dbVar: string,
|
|
145
|
+
env: string,
|
|
146
|
+
affinity: EnvAffinity | undefined,
|
|
147
|
+
): string | null {
|
|
148
|
+
const suffix = affinity?.[env];
|
|
149
|
+
if (!suffix) return null;
|
|
150
|
+
if (dbName.endsWith(suffix)) return null;
|
|
151
|
+
|
|
152
|
+
return (
|
|
153
|
+
`${dbVar}="${dbName}" is not valid in environment "${env}": ` +
|
|
154
|
+
`database names must end with "${suffix}". ` +
|
|
155
|
+
`Refusing to run against a database outside this environment.`
|
|
156
|
+
);
|
|
157
|
+
}
|