@htilabs/platform-common-models 0.6.0 → 0.7.0-beta.1
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 +191 -0
- package/dist/config/index.cjs.map +1 -0
- package/dist/config/index.d.cts +101 -0
- package/dist/config/index.d.ts +101 -0
- package/dist/config/index.js +165 -0
- package/dist/config/index.js.map +1 -0
- package/dist/constants/index.cjs +46 -5
- 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 +42 -5
- package/dist/constants/index.js.map +1 -1
- package/dist/cvcs/index.cjs +321 -0
- package/dist/cvcs/index.cjs.map +1 -1
- package/dist/cvcs/index.d.cts +789 -436
- package/dist/cvcs/index.d.ts +789 -436
- package/dist/cvcs/index.js +318 -0
- package/dist/cvcs/index.js.map +1 -1
- package/dist/index.cjs +424 -6
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +94 -3
- package/dist/index.d.ts +94 -3
- package/dist/index.js +412 -6
- package/dist/index.js.map +1 -1
- package/dist/{platform-auth-CjC57132.d.cts → platform-auth-C97LpsRd.d.cts} +8 -4
- package/dist/{platform-auth-CjC57132.d.ts → platform-auth-C97LpsRd.d.ts} +8 -4
- package/dist/schemas/index.cjs +43 -6
- package/dist/schemas/index.cjs.map +1 -1
- package/dist/schemas/index.d.cts +4 -0
- package/dist/schemas/index.d.ts +4 -0
- package/dist/schemas/index.js +43 -6
- 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 +9 -2
- package/src/__tests__/__snapshots__/cvc-sot.snap +12 -0
- package/src/__tests__/cvc-sot-snapshot.test.ts +24 -0
- package/src/__tests__/cvc-structural.test.ts +3 -0
- package/src/__tests__/runtime-contract-validator.test.ts +556 -0
- package/src/config/fixtures/valid.yaml +90 -0
- package/src/config/index.ts +352 -0
- package/src/constants/ic.ts +49 -6
- package/src/cvcs/hmisSex.v1.0.0.json +89 -0
- package/src/cvcs/index.ts +6 -0
- package/src/cvcs/juvenileJusticeEpisodeType.v1.0.0.json +96 -0
- package/src/cvcs/recencyBand.v1.0.0.json +124 -0
- package/src/generated/cvc-enums.ts +59 -0
- package/src/index.ts +20 -0
- package/src/schemas/common.ts +4 -0
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
service: test-svc
|
|
2
|
+
version: 1
|
|
3
|
+
environments:
|
|
4
|
+
- local
|
|
5
|
+
- dev
|
|
6
|
+
- test
|
|
7
|
+
- prod
|
|
8
|
+
|
|
9
|
+
variables:
|
|
10
|
+
NODE_ENV:
|
|
11
|
+
type: enum
|
|
12
|
+
values: [development, production, test]
|
|
13
|
+
required: false
|
|
14
|
+
secret: false
|
|
15
|
+
description: Node runtime mode.
|
|
16
|
+
default:
|
|
17
|
+
local: development
|
|
18
|
+
test: test
|
|
19
|
+
prod: production
|
|
20
|
+
|
|
21
|
+
PORT:
|
|
22
|
+
type: number
|
|
23
|
+
required: false
|
|
24
|
+
secret: false
|
|
25
|
+
description: Listen port.
|
|
26
|
+
default:
|
|
27
|
+
local: 3000
|
|
28
|
+
|
|
29
|
+
HOST:
|
|
30
|
+
type: string
|
|
31
|
+
required: true
|
|
32
|
+
secret: false
|
|
33
|
+
description: Bind address.
|
|
34
|
+
default:
|
|
35
|
+
local: 0.0.0.0
|
|
36
|
+
|
|
37
|
+
DEBUG_JSON:
|
|
38
|
+
type: json
|
|
39
|
+
required: false
|
|
40
|
+
secret: false
|
|
41
|
+
description: Debug JSON payload.
|
|
42
|
+
|
|
43
|
+
API_URL:
|
|
44
|
+
type: url
|
|
45
|
+
required: false
|
|
46
|
+
secret: false
|
|
47
|
+
description: External API URL.
|
|
48
|
+
default:
|
|
49
|
+
local: http://localhost:4000
|
|
50
|
+
|
|
51
|
+
DB_SECRET:
|
|
52
|
+
type: string
|
|
53
|
+
required: true
|
|
54
|
+
secret: true
|
|
55
|
+
description: Database connection secret.
|
|
56
|
+
default:
|
|
57
|
+
local: mongodb://localhost:27017
|
|
58
|
+
|
|
59
|
+
ENABLED:
|
|
60
|
+
type: boolean
|
|
61
|
+
required: false
|
|
62
|
+
secret: false
|
|
63
|
+
description: Feature flag.
|
|
64
|
+
default:
|
|
65
|
+
local: true
|
|
66
|
+
|
|
67
|
+
THEME:
|
|
68
|
+
type: enum
|
|
69
|
+
values: [light, dark, system]
|
|
70
|
+
required: false
|
|
71
|
+
secret: false
|
|
72
|
+
description: UI theme.
|
|
73
|
+
|
|
74
|
+
PUBLIC_API_URL:
|
|
75
|
+
type: url
|
|
76
|
+
required: false
|
|
77
|
+
secret: false
|
|
78
|
+
client_visible: true
|
|
79
|
+
description: Public API URL shown in browser.
|
|
80
|
+
default:
|
|
81
|
+
local: http://localhost:4000
|
|
82
|
+
|
|
83
|
+
BUILD_ARG:
|
|
84
|
+
type: string
|
|
85
|
+
required: false
|
|
86
|
+
secret: false
|
|
87
|
+
phase: build
|
|
88
|
+
description: Build-time argument.
|
|
89
|
+
default:
|
|
90
|
+
local: build-value
|
|
@@ -0,0 +1,352 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @htilabs/platform-common-models — Runtime Config Contract Validator
|
|
3
|
+
*
|
|
4
|
+
* Implements contract R12.1 (platform-common home):
|
|
5
|
+
* - validateAgainstContract(runtimeYamlPath, opts?) — startup validator (R3.2)
|
|
6
|
+
* - createConfigEndpoint(runtimeYamlPath, opts?) — /api/config factory (R7)
|
|
7
|
+
*
|
|
8
|
+
* Consumers MUST call validateAgainstContract once at process startup, before
|
|
9
|
+
* any other initialization that reads env vars. Build-phase variables
|
|
10
|
+
* (phase: build) are NOT checked at runtime per R3.4.
|
|
11
|
+
*
|
|
12
|
+
* No secret VALUES are read, stored, or returned here. Secret env vars are
|
|
13
|
+
* validated for presence but their values are never logged or exposed.
|
|
14
|
+
*
|
|
15
|
+
* Dual ESM + CJS via tsup. Plain JS consumers (pave, leads) use require():
|
|
16
|
+
* const { validateAgainstContract } = require('@htilabs/platform-common-models/config');
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
import { readFileSync } from "node:fs";
|
|
20
|
+
import { parse } from "yaml";
|
|
21
|
+
|
|
22
|
+
// ─── Schema types (mirrors thread's runtime-config-lib.ts VariableSpec) ──────
|
|
23
|
+
|
|
24
|
+
export interface VariableSpec {
|
|
25
|
+
type: "string" | "boolean" | "number" | "enum" | "url" | "json";
|
|
26
|
+
required: boolean;
|
|
27
|
+
secret: boolean;
|
|
28
|
+
description: string;
|
|
29
|
+
phase?: "runtime" | "build";
|
|
30
|
+
values?: string[];
|
|
31
|
+
default?: Record<string, unknown>;
|
|
32
|
+
provider?: string;
|
|
33
|
+
name?: string;
|
|
34
|
+
client_visible?: boolean;
|
|
35
|
+
deprecated?: { since: string; remove_after?: string; replacement?: string };
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export interface ServiceContract {
|
|
39
|
+
service: string;
|
|
40
|
+
version: number;
|
|
41
|
+
environments: string[];
|
|
42
|
+
// Thread extensions (tolerated, not required — R1.1 note)
|
|
43
|
+
port?: number;
|
|
44
|
+
build_secrets?: string[];
|
|
45
|
+
variables: Record<string, VariableSpec>;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** Typed config accessor returned by validateAgainstContract. */
|
|
49
|
+
export type TypedConfig = Record<string, string | boolean | number | unknown>;
|
|
50
|
+
|
|
51
|
+
export interface ValidateOptions {
|
|
52
|
+
/**
|
|
53
|
+
* Environment name used to select per-env defaults (e.g. "local", "test").
|
|
54
|
+
* Defaults to process.env.NODE_ENV, then "local".
|
|
55
|
+
*/
|
|
56
|
+
env?: string;
|
|
57
|
+
/**
|
|
58
|
+
* If true, do not call process.exit(1) on failure; throw instead.
|
|
59
|
+
* Useful for tests. Defaults to false (production mode exits).
|
|
60
|
+
*/
|
|
61
|
+
throwOnFailure?: boolean;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export interface EndpointOptions {
|
|
65
|
+
/** Cache-Control header value. Defaults to "private, no-store". */
|
|
66
|
+
cacheControl?: string;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* A framework-agnostic route handler that returns a JSON response.
|
|
71
|
+
* Compatible with:
|
|
72
|
+
* - Next.js App Router: export const GET = createConfigEndpoint(...)
|
|
73
|
+
* - Fastify: instance.get('/api/config', createConfigEndpoint(...))
|
|
74
|
+
* - Express: app.get('/api/config', createConfigEndpoint(...))
|
|
75
|
+
*/
|
|
76
|
+
export type RouteHandler = (
|
|
77
|
+
req?: unknown,
|
|
78
|
+
res?: unknown,
|
|
79
|
+
) => Promise<Response | void> | Response | void;
|
|
80
|
+
|
|
81
|
+
// ─── YAML parser ──────────────────────────────────────────────────────────────
|
|
82
|
+
|
|
83
|
+
function loadContract(runtimeYamlPath: string): ServiceContract {
|
|
84
|
+
let raw: string;
|
|
85
|
+
try {
|
|
86
|
+
raw = readFileSync(runtimeYamlPath, "utf8");
|
|
87
|
+
} catch (err) {
|
|
88
|
+
const msg =
|
|
89
|
+
err instanceof Error ? err.message : String(err);
|
|
90
|
+
throw new Error(
|
|
91
|
+
`[platform-common/config] Cannot read ${runtimeYamlPath}: ${msg}`,
|
|
92
|
+
);
|
|
93
|
+
}
|
|
94
|
+
const parsed = parse(raw) as ServiceContract | null;
|
|
95
|
+
if (!parsed || typeof parsed !== "object") {
|
|
96
|
+
throw new Error(
|
|
97
|
+
`[platform-common/config] ${runtimeYamlPath}: not a YAML mapping`,
|
|
98
|
+
);
|
|
99
|
+
}
|
|
100
|
+
if (parsed.version !== 1) {
|
|
101
|
+
throw new Error(
|
|
102
|
+
`[platform-common/config] ${runtimeYamlPath}: unsupported contract version ${parsed.version} (expected 1)`,
|
|
103
|
+
);
|
|
104
|
+
}
|
|
105
|
+
if (!parsed.variables || typeof parsed.variables !== "object") {
|
|
106
|
+
throw new Error(
|
|
107
|
+
`[platform-common/config] ${runtimeYamlPath}: missing "variables" map`,
|
|
108
|
+
);
|
|
109
|
+
}
|
|
110
|
+
return parsed;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
// ─── Coercion ────────────────────────────────────────────────────────────────
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Coerce a raw environment string value to the declared type.
|
|
117
|
+
* Returns [ok, coerced] or [false, errorMessage].
|
|
118
|
+
*/
|
|
119
|
+
function coerce(
|
|
120
|
+
key: string,
|
|
121
|
+
raw: string,
|
|
122
|
+
spec: VariableSpec,
|
|
123
|
+
): [true, unknown] | [false, string] {
|
|
124
|
+
switch (spec.type) {
|
|
125
|
+
case "boolean": {
|
|
126
|
+
if (raw === "true" || raw === "1") return [true, true];
|
|
127
|
+
if (raw === "false" || raw === "0") return [true, false];
|
|
128
|
+
return [false, `${key}: expected boolean ("true"/"false"/"1"/"0"), got "${raw}"`];
|
|
129
|
+
}
|
|
130
|
+
case "number": {
|
|
131
|
+
const n = Number(raw);
|
|
132
|
+
if (!Number.isFinite(n)) {
|
|
133
|
+
return [false, `${key}: expected number, got "${raw}"`];
|
|
134
|
+
}
|
|
135
|
+
return [true, n];
|
|
136
|
+
}
|
|
137
|
+
case "enum": {
|
|
138
|
+
const vals = spec.values ?? [];
|
|
139
|
+
if (!vals.includes(raw)) {
|
|
140
|
+
return [false, `${key}: expected one of [${vals.join(", ")}], got "${raw}"`];
|
|
141
|
+
}
|
|
142
|
+
return [true, raw];
|
|
143
|
+
}
|
|
144
|
+
case "url": {
|
|
145
|
+
try {
|
|
146
|
+
new URL(raw);
|
|
147
|
+
return [true, raw];
|
|
148
|
+
} catch {
|
|
149
|
+
return [false, `${key}: expected a valid URL, got "${raw}"`];
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
case "json": {
|
|
153
|
+
try {
|
|
154
|
+
const parsed = JSON.parse(raw) as unknown;
|
|
155
|
+
return [true, parsed];
|
|
156
|
+
} catch {
|
|
157
|
+
return [false, `${key}: expected valid JSON, got "${raw}"`];
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
default:
|
|
161
|
+
// string
|
|
162
|
+
return [true, raw];
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
// ─── Default application ─────────────────────────────────────────────────────
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* Returns the default value for a variable in the given environment,
|
|
170
|
+
* or undefined if no default applies.
|
|
171
|
+
*
|
|
172
|
+
* Exact env match only — defaults are per-environment and MUST NOT bleed
|
|
173
|
+
* across envs. (A local default stays local; it does not fall back into prod.)
|
|
174
|
+
*/
|
|
175
|
+
function resolveDefault(
|
|
176
|
+
spec: VariableSpec,
|
|
177
|
+
env: string,
|
|
178
|
+
): string | undefined {
|
|
179
|
+
if (!spec.default) return undefined;
|
|
180
|
+
const v = spec.default[env];
|
|
181
|
+
if (v === undefined) return undefined;
|
|
182
|
+
return String(v);
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
// ─── validateAgainstContract ─────────────────────────────────────────────────
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* Parse `runtimeYamlPath`, coerce every runtime-phase variable from
|
|
189
|
+
* `process.env` (with per-env defaults applied), and fail fast on any
|
|
190
|
+
* missing or invalid required variable (R3.2).
|
|
191
|
+
*
|
|
192
|
+
* Build-phase variables (phase: build) are skipped per R3.4.
|
|
193
|
+
*
|
|
194
|
+
* Returns a typed config object keyed by variable name.
|
|
195
|
+
*/
|
|
196
|
+
export function validateAgainstContract(
|
|
197
|
+
runtimeYamlPath: string,
|
|
198
|
+
opts: ValidateOptions = {},
|
|
199
|
+
): TypedConfig {
|
|
200
|
+
const contract = loadContract(runtimeYamlPath);
|
|
201
|
+
const env =
|
|
202
|
+
opts.env ??
|
|
203
|
+
(process.env.NODE_ENV as string | undefined) ??
|
|
204
|
+
"local";
|
|
205
|
+
|
|
206
|
+
const errors: string[] = [];
|
|
207
|
+
const result: TypedConfig = {};
|
|
208
|
+
|
|
209
|
+
for (const [key, spec] of Object.entries(contract.variables)) {
|
|
210
|
+
// R3.4: skip build-phase variables entirely at runtime.
|
|
211
|
+
if (spec.phase === "build") continue;
|
|
212
|
+
|
|
213
|
+
const rawFromEnv = process.env[key];
|
|
214
|
+
const defaultValue = resolveDefault(spec, env);
|
|
215
|
+
const effective = rawFromEnv ?? defaultValue;
|
|
216
|
+
|
|
217
|
+
if (effective === undefined || effective === "") {
|
|
218
|
+
if (spec.required) {
|
|
219
|
+
errors.push(
|
|
220
|
+
`${key}: required but not set (no value in process.env and no default for env "${env}")`,
|
|
221
|
+
);
|
|
222
|
+
}
|
|
223
|
+
// Not required and not set — omit from result.
|
|
224
|
+
continue;
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
const [ok, coerced] = coerce(key, effective, spec);
|
|
228
|
+
if (!ok) {
|
|
229
|
+
errors.push(coerced as string);
|
|
230
|
+
continue;
|
|
231
|
+
}
|
|
232
|
+
result[key] = coerced;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
if (errors.length > 0) {
|
|
236
|
+
const message = [
|
|
237
|
+
`[platform-common/config] validateAgainstContract failed for ${runtimeYamlPath}`,
|
|
238
|
+
`${errors.length} variable(s) missing or invalid:`,
|
|
239
|
+
...errors.map((e) => ` - ${e}`),
|
|
240
|
+
].join("\n");
|
|
241
|
+
|
|
242
|
+
if (opts.throwOnFailure) {
|
|
243
|
+
throw new Error(message);
|
|
244
|
+
}
|
|
245
|
+
console.error(message);
|
|
246
|
+
process.exit(1);
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
return result;
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
// ─── createConfigEndpoint ────────────────────────────────────────────────────
|
|
253
|
+
|
|
254
|
+
/**
|
|
255
|
+
* Build a static JSON payload containing only variables that are
|
|
256
|
+
* client_visible: true AND secret: false (R7.2, R7.3). Reads process.env
|
|
257
|
+
* once at factory call time.
|
|
258
|
+
*/
|
|
259
|
+
function buildClientPayload(
|
|
260
|
+
contract: ServiceContract,
|
|
261
|
+
env: string,
|
|
262
|
+
): Record<string, unknown> {
|
|
263
|
+
const payload: Record<string, unknown> = {};
|
|
264
|
+
|
|
265
|
+
for (const [key, spec] of Object.entries(contract.variables)) {
|
|
266
|
+
// R7.3: never expose secrets.
|
|
267
|
+
if (spec.secret) continue;
|
|
268
|
+
// R7.2: only expose client_visible vars.
|
|
269
|
+
if (!spec.client_visible) continue;
|
|
270
|
+
// R3.4: build-phase vars are not available at runtime.
|
|
271
|
+
if (spec.phase === "build") continue;
|
|
272
|
+
|
|
273
|
+
const raw = process.env[key] ?? resolveDefault(spec, env);
|
|
274
|
+
if (raw === undefined) continue;
|
|
275
|
+
|
|
276
|
+
const [ok, coerced] = coerce(key, raw, spec);
|
|
277
|
+
payload[key] = ok ? coerced : raw;
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
return payload;
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
/**
|
|
284
|
+
* Route-handler factory for GET /api/config (R7.1).
|
|
285
|
+
*
|
|
286
|
+
* Reads the contract and process.env once at factory-call time and caches
|
|
287
|
+
* the JSON payload. The returned handler is compatible with:
|
|
288
|
+
*
|
|
289
|
+
* Next.js App Router:
|
|
290
|
+
* export const GET = createConfigEndpoint(path);
|
|
291
|
+
*
|
|
292
|
+
* Fastify:
|
|
293
|
+
* instance.get('/api/config', createConfigEndpoint(path));
|
|
294
|
+
*
|
|
295
|
+
* Express:
|
|
296
|
+
* app.get('/api/config', createConfigEndpoint(path));
|
|
297
|
+
*
|
|
298
|
+
* The handler detects the calling convention at runtime:
|
|
299
|
+
* - Next.js / fetch-native: called with no arguments; returns a Response.
|
|
300
|
+
* - Express: called with (req, res); calls res.json() and returns void.
|
|
301
|
+
* - Fastify: called with (req, reply); calls reply.send() and returns void.
|
|
302
|
+
*/
|
|
303
|
+
export function createConfigEndpoint(
|
|
304
|
+
runtimeYamlPath: string,
|
|
305
|
+
opts: EndpointOptions = {},
|
|
306
|
+
): RouteHandler {
|
|
307
|
+
const contract = loadContract(runtimeYamlPath);
|
|
308
|
+
const env =
|
|
309
|
+
(process.env.NODE_ENV as string | undefined) ?? "local";
|
|
310
|
+
const payload = buildClientPayload(contract, env);
|
|
311
|
+
const cacheControl = opts.cacheControl ?? "private, no-store";
|
|
312
|
+
const body = JSON.stringify(payload);
|
|
313
|
+
|
|
314
|
+
return function configHandler(
|
|
315
|
+
_req?: unknown,
|
|
316
|
+
res?: unknown,
|
|
317
|
+
): Promise<Response | void> | Response | void {
|
|
318
|
+
// Express-shaped: res has .json()
|
|
319
|
+
if (res && typeof (res as Record<string, unknown>)["json"] === "function") {
|
|
320
|
+
const r = res as {
|
|
321
|
+
setHeader: (k: string, v: string) => void;
|
|
322
|
+
json: (data: unknown) => void;
|
|
323
|
+
};
|
|
324
|
+
r.setHeader("Cache-Control", cacheControl);
|
|
325
|
+
r.setHeader("Content-Type", "application/json");
|
|
326
|
+
r.json(payload);
|
|
327
|
+
return;
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
// Fastify-shaped: res has .send()
|
|
331
|
+
if (res && typeof (res as Record<string, unknown>)["send"] === "function") {
|
|
332
|
+
const r = res as {
|
|
333
|
+
header: (k: string, v: string) => void;
|
|
334
|
+
type: (ct: string) => void;
|
|
335
|
+
send: (data: string) => void;
|
|
336
|
+
};
|
|
337
|
+
r.header("Cache-Control", cacheControl);
|
|
338
|
+
r.type("application/json");
|
|
339
|
+
r.send(body);
|
|
340
|
+
return;
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
// Next.js / fetch-native (no res argument, or unrecognised res)
|
|
344
|
+
return new Response(body, {
|
|
345
|
+
status: 200,
|
|
346
|
+
headers: {
|
|
347
|
+
"Content-Type": "application/json",
|
|
348
|
+
"Cache-Control": cacheControl,
|
|
349
|
+
},
|
|
350
|
+
});
|
|
351
|
+
};
|
|
352
|
+
}
|
package/src/constants/ic.ts
CHANGED
|
@@ -45,7 +45,9 @@ export const DATA_QUALITY_DESCRIPTIONS: Record<DataQualityValue, string> = {
|
|
|
45
45
|
|
|
46
46
|
// ─── CVC-1: Name Type ───────────────────────────────────────────────
|
|
47
47
|
// Distinguishes between legal names (structured: first/middle/last/suffix)
|
|
48
|
-
// and unstructured name forms (alias, trade name,
|
|
48
|
+
// and unstructured name forms (alias, trade name, nickname, etc.)
|
|
49
|
+
// Mononym is not a name_type — it's a shape flag on structured components
|
|
50
|
+
// (see `isMononym` on personNameSchema).
|
|
49
51
|
// Reference: core_name_type in IC/CVC codebook
|
|
50
52
|
|
|
51
53
|
export const CVC_1_NAME_TYPE = {
|
|
@@ -55,8 +57,6 @@ export const CVC_1_NAME_TYPE = {
|
|
|
55
57
|
ALIAS: "alias",
|
|
56
58
|
/** Trade name / business name - single unstructured name field */
|
|
57
59
|
TRADE_NAME: "trade_name",
|
|
58
|
-
/** Single-word name (e.g., "Madonna", "Prince") - single unstructured name field */
|
|
59
|
-
MONONYM: "mononym",
|
|
60
60
|
/** Nickname - single unstructured name field */
|
|
61
61
|
NICKNAME: "nickname",
|
|
62
62
|
/** Online handle or username - single unstructured name field */
|
|
@@ -71,7 +71,6 @@ export const CVC_1_VALUES = [
|
|
|
71
71
|
CVC_1_NAME_TYPE.LEGAL,
|
|
72
72
|
CVC_1_NAME_TYPE.ALIAS,
|
|
73
73
|
CVC_1_NAME_TYPE.TRADE_NAME,
|
|
74
|
-
CVC_1_NAME_TYPE.MONONYM,
|
|
75
74
|
CVC_1_NAME_TYPE.NICKNAME,
|
|
76
75
|
CVC_1_NAME_TYPE.HANDLE,
|
|
77
76
|
CVC_1_NAME_TYPE.UNKNOWN,
|
|
@@ -81,7 +80,6 @@ export const CVC_1_LABELS: Record<CVC1Value, string> = {
|
|
|
81
80
|
[CVC_1_NAME_TYPE.LEGAL]: "Legal Name",
|
|
82
81
|
[CVC_1_NAME_TYPE.ALIAS]: "Alias / AKA",
|
|
83
82
|
[CVC_1_NAME_TYPE.TRADE_NAME]: "Trade Name",
|
|
84
|
-
[CVC_1_NAME_TYPE.MONONYM]: "Mononym",
|
|
85
83
|
[CVC_1_NAME_TYPE.NICKNAME]: "Nickname",
|
|
86
84
|
[CVC_1_NAME_TYPE.HANDLE]: "Handle / Username",
|
|
87
85
|
[CVC_1_NAME_TYPE.UNKNOWN]: "Unknown",
|
|
@@ -102,7 +100,6 @@ export const CVC_1_STRUCTURED_NAME_TYPES: readonly CVC1Value[] = [
|
|
|
102
100
|
export const CVC_1_UNSTRUCTURED_NAME_TYPES: readonly CVC1Value[] = [
|
|
103
101
|
CVC_1_NAME_TYPE.ALIAS,
|
|
104
102
|
CVC_1_NAME_TYPE.TRADE_NAME,
|
|
105
|
-
CVC_1_NAME_TYPE.MONONYM,
|
|
106
103
|
CVC_1_NAME_TYPE.NICKNAME,
|
|
107
104
|
CVC_1_NAME_TYPE.HANDLE,
|
|
108
105
|
CVC_1_NAME_TYPE.UNKNOWN,
|
|
@@ -1415,7 +1412,10 @@ export const CVC_17_CORE_GENDER_IDENTITY = {
|
|
|
1415
1412
|
TRANSGENDER: "TRANSGENDER",
|
|
1416
1413
|
NON_BINARY: "NON_BINARY",
|
|
1417
1414
|
OTHER: "OTHER",
|
|
1415
|
+
// Level 0 - Missingness codes (codebook canonical set)
|
|
1418
1416
|
UNKNOWN: "UNK",
|
|
1417
|
+
DATA_NOT_COLLECTED: "DNC",
|
|
1418
|
+
PREFER_NOT_TO_ANSWER: "PNA",
|
|
1419
1419
|
// Level 2 - Transgender subcategories
|
|
1420
1420
|
TRANSGENDER_FTM: "TRANSGENDER_FTM",
|
|
1421
1421
|
TRANSGENDER_MTF: "TRANSGENDER_MTF",
|
|
@@ -1431,6 +1431,8 @@ export const CVC_17_LABELS: Record<CVC17Value, string> = {
|
|
|
1431
1431
|
[CVC_17_CORE_GENDER_IDENTITY.NON_BINARY]: "Non-Binary",
|
|
1432
1432
|
[CVC_17_CORE_GENDER_IDENTITY.OTHER]: "Other",
|
|
1433
1433
|
[CVC_17_CORE_GENDER_IDENTITY.UNKNOWN]: "Unknown",
|
|
1434
|
+
[CVC_17_CORE_GENDER_IDENTITY.DATA_NOT_COLLECTED]: "Data not collected",
|
|
1435
|
+
[CVC_17_CORE_GENDER_IDENTITY.PREFER_NOT_TO_ANSWER]: "Client prefers not to answer",
|
|
1434
1436
|
[CVC_17_CORE_GENDER_IDENTITY.TRANSGENDER_FTM]: "Transgender - FTM",
|
|
1435
1437
|
[CVC_17_CORE_GENDER_IDENTITY.TRANSGENDER_MTF]: "Transgender - MTF",
|
|
1436
1438
|
};
|
|
@@ -1467,6 +1469,38 @@ export function isTransgenderGenderIdentity(value: CVC17Value | null | undefined
|
|
|
1467
1469
|
return CVC_17_TRANSGENDER_VALUES.includes(value);
|
|
1468
1470
|
}
|
|
1469
1471
|
|
|
1472
|
+
// Selectable non-missingness values (Level 1 primary + Level 2 subcategories)
|
|
1473
|
+
export const CVC_17_SELECTABLE_VALUES: CVC17Value[] = [
|
|
1474
|
+
CVC_17_CORE_GENDER_IDENTITY.MALE,
|
|
1475
|
+
CVC_17_CORE_GENDER_IDENTITY.FEMALE,
|
|
1476
|
+
CVC_17_CORE_GENDER_IDENTITY.TRANSGENDER,
|
|
1477
|
+
CVC_17_CORE_GENDER_IDENTITY.TRANSGENDER_FTM,
|
|
1478
|
+
CVC_17_CORE_GENDER_IDENTITY.TRANSGENDER_MTF,
|
|
1479
|
+
CVC_17_CORE_GENDER_IDENTITY.NON_BINARY,
|
|
1480
|
+
CVC_17_CORE_GENDER_IDENTITY.OTHER,
|
|
1481
|
+
];
|
|
1482
|
+
|
|
1483
|
+
// Missingness values (codebook canonical set: UNK, DNC, PNA)
|
|
1484
|
+
export const CVC_17_MISSINGNESS_VALUES: CVC17Value[] = [
|
|
1485
|
+
CVC_17_CORE_GENDER_IDENTITY.UNKNOWN,
|
|
1486
|
+
CVC_17_CORE_GENDER_IDENTITY.DATA_NOT_COLLECTED,
|
|
1487
|
+
CVC_17_CORE_GENDER_IDENTITY.PREFER_NOT_TO_ANSWER,
|
|
1488
|
+
];
|
|
1489
|
+
|
|
1490
|
+
// All CVC-17 values as an array (for Mongoose schema enum validation)
|
|
1491
|
+
export const CVC_17_VALUES: CVC17Value[] = [
|
|
1492
|
+
CVC_17_CORE_GENDER_IDENTITY.MALE,
|
|
1493
|
+
CVC_17_CORE_GENDER_IDENTITY.FEMALE,
|
|
1494
|
+
CVC_17_CORE_GENDER_IDENTITY.TRANSGENDER,
|
|
1495
|
+
CVC_17_CORE_GENDER_IDENTITY.NON_BINARY,
|
|
1496
|
+
CVC_17_CORE_GENDER_IDENTITY.OTHER,
|
|
1497
|
+
CVC_17_CORE_GENDER_IDENTITY.UNKNOWN,
|
|
1498
|
+
CVC_17_CORE_GENDER_IDENTITY.DATA_NOT_COLLECTED,
|
|
1499
|
+
CVC_17_CORE_GENDER_IDENTITY.PREFER_NOT_TO_ANSWER,
|
|
1500
|
+
CVC_17_CORE_GENDER_IDENTITY.TRANSGENDER_FTM,
|
|
1501
|
+
CVC_17_CORE_GENDER_IDENTITY.TRANSGENDER_MTF,
|
|
1502
|
+
];
|
|
1503
|
+
|
|
1470
1504
|
// ─── IC-24: Race ───────────────────────────────────────────────────
|
|
1471
1505
|
|
|
1472
1506
|
export const IC_24_RACE = {
|
|
@@ -5282,3 +5316,12 @@ export const CVC_67_SELECTABLE_VALUES: CVC67Value[] = [
|
|
|
5282
5316
|
export const CVC_67_MISSINGNESS_VALUES: CVC67Value[] = [
|
|
5283
5317
|
CVC_67_HMIS_SEX.DATA_NOT_COLLECTED,
|
|
5284
5318
|
];
|
|
5319
|
+
|
|
5320
|
+
// All CVC-67 values as an array (for Mongoose schema enum validation)
|
|
5321
|
+
export const CVC_67_VALUES: CVC67Value[] = [
|
|
5322
|
+
CVC_67_HMIS_SEX.MALE,
|
|
5323
|
+
CVC_67_HMIS_SEX.FEMALE,
|
|
5324
|
+
CVC_67_HMIS_SEX.CLIENT_PREFERS_NOT_TO_ANSWER,
|
|
5325
|
+
CVC_67_HMIS_SEX.CLIENT_DOESNT_KNOW,
|
|
5326
|
+
CVC_67_HMIS_SEX.DATA_NOT_COLLECTED,
|
|
5327
|
+
];
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
{
|
|
2
|
+
"domain": "hmis_sex",
|
|
3
|
+
"name": "Core HMIS Sex",
|
|
4
|
+
"version": "1.0.0",
|
|
5
|
+
"levels": {
|
|
6
|
+
"0": "Unknown or Missing",
|
|
7
|
+
"1": "Sex"
|
|
8
|
+
},
|
|
9
|
+
"entries": [
|
|
10
|
+
{
|
|
11
|
+
"code": "067-000-000-000-000-000-000",
|
|
12
|
+
"key": "missingness_root",
|
|
13
|
+
"title": "Unknown, Redacted, or Missing",
|
|
14
|
+
"selectable": false,
|
|
15
|
+
"parentCode": null,
|
|
16
|
+
"childCodes": [
|
|
17
|
+
"067-000-000-000-000-000-001",
|
|
18
|
+
"067-000-000-000-000-000-002",
|
|
19
|
+
"067-000-000-000-000-000-003",
|
|
20
|
+
"067-000-000-000-000-000-004",
|
|
21
|
+
"067-000-000-000-000-000-005"
|
|
22
|
+
],
|
|
23
|
+
"definition": "Root group for values indicating absent, withheld, or uncollected data."
|
|
24
|
+
},
|
|
25
|
+
{
|
|
26
|
+
"code": "067-000-000-000-000-000-001",
|
|
27
|
+
"key": "unknown",
|
|
28
|
+
"title": "Unknown",
|
|
29
|
+
"selectable": true,
|
|
30
|
+
"parentCode": "067-000-000-000-000-000-000",
|
|
31
|
+
"childCodes": [],
|
|
32
|
+
"definition": "Value is unknown at time of entry."
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
"code": "067-000-000-000-000-000-002",
|
|
36
|
+
"key": "anonymous",
|
|
37
|
+
"title": "Anonymous",
|
|
38
|
+
"selectable": true,
|
|
39
|
+
"parentCode": "067-000-000-000-000-000-000",
|
|
40
|
+
"childCodes": [],
|
|
41
|
+
"definition": "Value is intentionally withheld or redacted."
|
|
42
|
+
},
|
|
43
|
+
{
|
|
44
|
+
"code": "067-000-000-000-000-000-003",
|
|
45
|
+
"key": "data_not_collected",
|
|
46
|
+
"title": "Data not collected",
|
|
47
|
+
"selectable": true,
|
|
48
|
+
"parentCode": "067-000-000-000-000-000-000",
|
|
49
|
+
"childCodes": [],
|
|
50
|
+
"definition": "Use this response if the staff does not ask the person to provide their sex."
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
"code": "067-000-000-000-000-000-004",
|
|
54
|
+
"key": "client_doesn_t_know",
|
|
55
|
+
"title": "Client doesn't know",
|
|
56
|
+
"selectable": true,
|
|
57
|
+
"parentCode": "067-000-000-000-000-000-000",
|
|
58
|
+
"childCodes": [],
|
|
59
|
+
"definition": "\"Client doesn't know\" should only be selected when a person does not know their sex from among the responses."
|
|
60
|
+
},
|
|
61
|
+
{
|
|
62
|
+
"code": "067-000-000-000-000-000-005",
|
|
63
|
+
"key": "client_prefers_not_to_answer",
|
|
64
|
+
"title": "Client prefers not to answer",
|
|
65
|
+
"selectable": true,
|
|
66
|
+
"parentCode": "067-000-000-000-000-000-000",
|
|
67
|
+
"childCodes": [],
|
|
68
|
+
"definition": "\"Client prefers not to answer\" should only be selected when a person chooses not to identify their sex from among the responses."
|
|
69
|
+
},
|
|
70
|
+
{
|
|
71
|
+
"code": "067-001-000-000-000-000-000",
|
|
72
|
+
"key": "female",
|
|
73
|
+
"title": "Female",
|
|
74
|
+
"selectable": true,
|
|
75
|
+
"parentCode": null,
|
|
76
|
+
"childCodes": [],
|
|
77
|
+
"definition": "A person of the sex characterized by a reproductive system with the biological function of producing eggs (ova)."
|
|
78
|
+
},
|
|
79
|
+
{
|
|
80
|
+
"code": "067-002-000-000-000-000-000",
|
|
81
|
+
"key": "male",
|
|
82
|
+
"title": "Male",
|
|
83
|
+
"selectable": true,
|
|
84
|
+
"parentCode": null,
|
|
85
|
+
"childCodes": [],
|
|
86
|
+
"definition": "A person of the sex characterized by a reproductive system with the biological function of producing sperm."
|
|
87
|
+
}
|
|
88
|
+
]
|
|
89
|
+
}
|
package/src/cvcs/index.ts
CHANGED
|
@@ -63,6 +63,9 @@ import incomeBenefitsSourcesSot from "./incomeBenefitsSources.v1.0.0.json" with
|
|
|
63
63
|
import enrollmentApplicationStatusSot from "./enrollmentApplicationStatus.v1.0.0.json" with { type: "json" };
|
|
64
64
|
import administeringJurisdictionSot from "./administeringJurisdiction.v1.0.0.json" with { type: "json" };
|
|
65
65
|
import frequencyCadenceSot from "./frequencyCadence.v1.0.0.json" with { type: "json" };
|
|
66
|
+
import recencyBandSot from "./recencyBand.v1.0.0.json" with { type: "json" };
|
|
67
|
+
import juvenileJusticeEpisodeTypeSot from "./juvenileJusticeEpisodeType.v1.0.0.json" with { type: "json" };
|
|
68
|
+
import hmisSexSot from "./hmisSex.v1.0.0.json" with { type: "json" };
|
|
66
69
|
|
|
67
70
|
export {
|
|
68
71
|
serviceCategoriesSot,
|
|
@@ -109,4 +112,7 @@ export {
|
|
|
109
112
|
enrollmentApplicationStatusSot,
|
|
110
113
|
administeringJurisdictionSot,
|
|
111
114
|
frequencyCadenceSot,
|
|
115
|
+
recencyBandSot,
|
|
116
|
+
juvenileJusticeEpisodeTypeSot,
|
|
117
|
+
hmisSexSot,
|
|
112
118
|
};
|