@htilabs/platform-common-models 0.64.0 → 0.65.0
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 +72 -0
- package/dist/index.cjs +57 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +54 -0
- package/dist/index.js.map +1 -1
- package/dist/org-directory/index.cjs +19 -0
- package/dist/org-directory/index.cjs.map +1 -1
- package/dist/org-directory/index.d.cts +34 -6
- package/dist/org-directory/index.d.ts +34 -6
- package/dist/org-directory/index.js +16 -0
- package/dist/org-directory/index.js.map +1 -1
- package/dist/points-of-contact/index.cjs +6 -0
- package/dist/points-of-contact/index.cjs.map +1 -1
- package/dist/points-of-contact/index.js +6 -0
- package/dist/points-of-contact/index.js.map +1 -1
- package/dist/schemas/index.cjs +57 -0
- package/dist/schemas/index.cjs.map +1 -1
- package/dist/schemas/index.d.cts +52 -1
- package/dist/schemas/index.d.ts +52 -1
- package/dist/schemas/index.js +54 -0
- package/dist/schemas/index.js.map +1 -1
- package/package.json +1 -1
- package/src/orgDirectory/__tests__/orgKey.test.ts +84 -0
- package/src/orgDirectory/orgRecord.ts +41 -3
- package/src/orgDirectory/rules.ts +4 -1
- package/src/schemas/index.ts +3 -0
- package/src/schemas/organization.ts +58 -0
package/README.md
CHANGED
|
@@ -16,6 +16,78 @@ Package exports are organized into a public root API and a small number of
|
|
|
16
16
|
dedicated subpaths (`/validation`, `/cvcs`) — consult `package.json` for the
|
|
17
17
|
authoritative `exports` map.
|
|
18
18
|
|
|
19
|
+
## 0.65.0 — the Org's identifier: `key` (additive)
|
|
20
|
+
|
|
21
|
+
An organization now carries its identifier, the one value that names the same
|
|
22
|
+
organization in every database (the UDD Org `id`, a slug such as `the_spring`;
|
|
23
|
+
schema of record hti-features `udd-schemas/org/Org.v1.json`). Until now an
|
|
24
|
+
`organizations` row had only `_id`, which is each database's own, so nothing
|
|
25
|
+
tied a production row to the same organization in the Admin Hub's curated list.
|
|
26
|
+
|
|
27
|
+
- `ORG_RECORD_FIELD_NAMES` gains `key` (first). `addOrgRecordFields` declares
|
|
28
|
+
it (`String`, immutable, slug-shaped) and a partial unique index
|
|
29
|
+
`org_key_unique` (`ORG_KEY_INDEX_NAME`; the definition is exported as
|
|
30
|
+
`ORG_KEY_INDEX_SPEC` / `ORG_KEY_INDEX_OPTIONS`). A row with no key, or a
|
|
31
|
+
null one, is not indexed, so those never collide.
|
|
32
|
+
- What `immutable` does, measured on Mongoose 9.3.1 against MongoDB (the
|
|
33
|
+
tests are in `scripts/fill-org-registry.test.ts`, run in CI): the model
|
|
34
|
+
stores a key **only while it is creating the row**.
|
|
35
|
+
- Stored: `new Model({ key }).save()`, `Model.create({ key })`, and an
|
|
36
|
+
upsert that inserts the row (`$setOnInsert: { key }`, or `$set`, which
|
|
37
|
+
Mongoose moves to `$setOnInsert`).
|
|
38
|
+
- Not stored, and **no error is raised**: on a row that already exists,
|
|
39
|
+
`doc.key = …; doc.save()` and `updateOne` / `findOneAndUpdate` with
|
|
40
|
+
`$set: { key }`, or an upsert that finds the row. This is true whether
|
|
41
|
+
the row already has a key or has none, so a model cannot give an old row
|
|
42
|
+
its first key.
|
|
43
|
+
- Stored as `key`, not `id`: Mongoose gives every document an `id` of its own,
|
|
44
|
+
and the curated store already names it `key`.
|
|
45
|
+
- `isOrgKey`, `ORG_KEY_PATTERN`, `mintOrgKey(_id)` → `org-<_id>` for an
|
|
46
|
+
organization created without one (the curated store's rule: a new key never
|
|
47
|
+
encodes a name). `OrgIdentityWriteSchema` still refuses `key`: it is never
|
|
48
|
+
taken from a request body and never changes.
|
|
49
|
+
- `toDirectoryOrganizationView` returns `key` (null on a row not yet given one).
|
|
50
|
+
- Consumers: a model that mounts `addOrgRecordFields` gains the path and passes
|
|
51
|
+
`organizationSchemaIssues` unchanged. Upgrading alone does not give new
|
|
52
|
+
organizations an identifier: each app has to store one where it creates an
|
|
53
|
+
organization, in one of the forms that work:
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
const _id = new Types.ObjectId();
|
|
57
|
+
await new Organization({ _id, name, key: mintOrgKey(_id) }).save(); // or Organization.create({ … })
|
|
58
|
+
|
|
59
|
+
await Organization.updateOne(
|
|
60
|
+
{ _id },
|
|
61
|
+
{ $set: { name }, $setOnInsert: { key: mintOrgKey(_id) } },
|
|
62
|
+
{ upsert: true },
|
|
63
|
+
);
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Do not set `key` on a row that already exists (it is silently dropped, see
|
|
67
|
+
above). Existing rows get theirs only from the registry fill's key sheet,
|
|
68
|
+
which writes with the plain MongoDB driver.
|
|
69
|
+
- `scripts/fill-org-registry.ts`: matches a row to the curated list by `key`
|
|
70
|
+
first; `--propose-keys` / `--apply-keys` give existing rows their identifier
|
|
71
|
+
from a sheet a person reviews (see `scripts/FILL_ORG_REGISTRY_RUNBOOK.md`):
|
|
72
|
+
- The sheet has a `stored_id` column (the slug an old row carries in its
|
|
73
|
+
`id` field). `approved_key` takes a curated key, the line's own
|
|
74
|
+
`stored_id`, or `mint` (`org-<_id>`).
|
|
75
|
+
- Nothing is proposed when the evidence is not clear-cut, and the reason
|
|
76
|
+
says which case it is (two rows for one key, sources that disagree, a
|
|
77
|
+
name or database id that matches two curated organizations, a match by
|
|
78
|
+
short name only, an old slug the curated list does not know).
|
|
79
|
+
- `--apply-keys` prints each organization's stored name beside its key,
|
|
80
|
+
refuses a line whose name is not the stored one, marks an approval that
|
|
81
|
+
differs from the proposal, and builds the `org_key_unique` index first if
|
|
82
|
+
the collection does not have it (it says so before asking to confirm; it
|
|
83
|
+
refuses if an index of that name exists with other options).
|
|
84
|
+
- It plans all or nothing, then writes row by row: a row edited in between,
|
|
85
|
+
or one the database refuses, is reported and the command exits non-zero.
|
|
86
|
+
- Undo (`--rollback`) removes an identifier whenever the row still holds
|
|
87
|
+
the one the script wrote, even after an app has saved the row. Undo the
|
|
88
|
+
most recent apply first (the fill, then the identifiers).
|
|
89
|
+
- Both commands stop if a curated organization has no key, a malformed
|
|
90
|
+
key, a key another curated organization has, or the key `mint`.
|
|
19
91
|
## 0.64.0 — gender and disability: the codebook code on every category; the two reporting claims hold our own codes (additive; Crysta 2026-11-10)
|
|
20
92
|
|
|
21
93
|
Crysta confirmed on 2026-11-10 that gender and disability follow the race rule
|
package/dist/index.cjs
CHANGED
|
@@ -389,6 +389,9 @@ __export(src_exports, {
|
|
|
389
389
|
NeedsAssessmentChangeTypeKeys: () => NeedsAssessmentChangeTypeKeys,
|
|
390
390
|
NeedsResidentialAgainKeys: () => NeedsResidentialAgainKeys,
|
|
391
391
|
ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS: () => ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS,
|
|
392
|
+
ORG_KEY_INDEX_NAME: () => ORG_KEY_INDEX_NAME,
|
|
393
|
+
ORG_KEY_INDEX_OPTIONS: () => ORG_KEY_INDEX_OPTIONS,
|
|
394
|
+
ORG_KEY_INDEX_SPEC: () => ORG_KEY_INDEX_SPEC,
|
|
392
395
|
ORG_TYPE_FIELD_NAMES: () => ORG_TYPE_FIELD_NAMES,
|
|
393
396
|
ORG_TYPE_HEADING_KEYS: () => ORG_TYPE_HEADING_KEYS,
|
|
394
397
|
ORG_TYPE_KEYS: () => ORG_TYPE_KEYS,
|
|
@@ -18735,6 +18738,7 @@ function isLiveOrganizationProgram(row) {
|
|
|
18735
18738
|
// src/orgDirectory/orgRecord.ts
|
|
18736
18739
|
var ORG_REVIEW_STATUS_VALUES = PROGRAM_REVIEW_STATUS_VALUES;
|
|
18737
18740
|
var ORG_RECORD_FIELD_NAMES = Object.freeze([
|
|
18741
|
+
"key",
|
|
18738
18742
|
"legalName",
|
|
18739
18743
|
"commonName",
|
|
18740
18744
|
"shortName",
|
|
@@ -18784,6 +18788,10 @@ var ORGANIZATION_ENVELOPE_KEYS = Object.freeze([
|
|
|
18784
18788
|
"updatedUser",
|
|
18785
18789
|
"updatedTime"
|
|
18786
18790
|
]);
|
|
18791
|
+
var ORG_KEY_PATTERN = /^[a-z0-9][a-z0-9_-]{0,119}$/;
|
|
18792
|
+
function isOrgKey(value) {
|
|
18793
|
+
return typeof value === "string" && ORG_KEY_PATTERN.test(value);
|
|
18794
|
+
}
|
|
18787
18795
|
var line = (max) => import_zod.z.string().trim().min(1).max(max).nullable();
|
|
18788
18796
|
var ORG_VSP_TWO_STEP_MESSAGE = "vspPrivateNonprofit is step 2 of the HMIS VSP two-step and requires vsp: true";
|
|
18789
18797
|
var OrgIdentityWriteSchema = import_zod.z.object({
|
|
@@ -18804,12 +18812,50 @@ var OrgVspWriteSchema = import_zod.z.object({
|
|
|
18804
18812
|
|
|
18805
18813
|
// src/schemas/organization.ts
|
|
18806
18814
|
var HEX_24 = /^[0-9a-fA-F]{24}$/;
|
|
18815
|
+
var ORG_KEY_INDEX_NAME = "org_key_unique";
|
|
18816
|
+
var ORG_KEY_INDEX_SPEC = Object.freeze({ key: 1 });
|
|
18817
|
+
var ORG_KEY_INDEX_OPTIONS = Object.freeze({
|
|
18818
|
+
name: ORG_KEY_INDEX_NAME,
|
|
18819
|
+
unique: true,
|
|
18820
|
+
partialFilterExpression: Object.freeze({ key: Object.freeze({ $type: "string" }) })
|
|
18821
|
+
});
|
|
18807
18822
|
function isStoredDirectoryId(value) {
|
|
18808
18823
|
if (value == null) return true;
|
|
18809
18824
|
if (typeof value === "string") return value.trim() !== "";
|
|
18810
18825
|
return typeof value === "object" && typeof value.toHexString === "function" && HEX_24.test(value.toHexString());
|
|
18811
18826
|
}
|
|
18812
18827
|
var orgRecordSchemaDefinition = {
|
|
18828
|
+
/**
|
|
18829
|
+
* The Org's identifier (the UDD `id`): the same value in every database.
|
|
18830
|
+
* Never taken from a request body.
|
|
18831
|
+
*
|
|
18832
|
+
* `immutable` means the model stores a key only while it is creating the
|
|
18833
|
+
* row. Measured on Mongoose 9.3.1 against MongoDB (the fill's test file
|
|
18834
|
+
* holds each line):
|
|
18835
|
+
*
|
|
18836
|
+
* - `new Model({ key }).save()` and `Model.create({ key })` store it.
|
|
18837
|
+
* - An upsert stores it when the upsert inserts the row (`$setOnInsert`, or
|
|
18838
|
+
* `$set`, which Mongoose moves to `$setOnInsert`); on a row that already
|
|
18839
|
+
* exists the upsert leaves `key` as it was.
|
|
18840
|
+
* - On a row that already exists, `doc.key = …; doc.save()` and
|
|
18841
|
+
* `updateOne` / `findOneAndUpdate` with `$set: { key }` do NOT write it,
|
|
18842
|
+
* and do not report an error. That holds whether the row has a key or has
|
|
18843
|
+
* none yet, so a model cannot give an old row its first key either.
|
|
18844
|
+
*
|
|
18845
|
+
* So an app stores `key: mintOrgKey(_id)` where it creates the
|
|
18846
|
+
* organization (`new Model().save()`, `create()`, or `$setOnInsert` on an
|
|
18847
|
+
* upsert). Rows that already exist get theirs from the registry fill's key
|
|
18848
|
+
* sheet, which writes with the plain MongoDB driver.
|
|
18849
|
+
*/
|
|
18850
|
+
key: {
|
|
18851
|
+
type: String,
|
|
18852
|
+
trim: true,
|
|
18853
|
+
immutable: true,
|
|
18854
|
+
validate: {
|
|
18855
|
+
validator: (value) => value == null || isOrgKey(value),
|
|
18856
|
+
message: "key must be a lower-case slug (a-z, 0-9, _ and -)"
|
|
18857
|
+
}
|
|
18858
|
+
},
|
|
18813
18859
|
/** The canonical reporting name (HMIS, funders). Readers fall back to `name`. */
|
|
18814
18860
|
legalName: { type: String, trim: true },
|
|
18815
18861
|
/** The name people use, when it differs from `name`. */
|
|
@@ -18858,6 +18904,13 @@ var orgAsBuiltSchemaDefinition = {
|
|
|
18858
18904
|
};
|
|
18859
18905
|
function addOrgRecordFields(schema, options = {}) {
|
|
18860
18906
|
schema.add(orgRecordSchemaDefinition);
|
|
18907
|
+
schema.index(
|
|
18908
|
+
{ ...ORG_KEY_INDEX_SPEC },
|
|
18909
|
+
{
|
|
18910
|
+
...ORG_KEY_INDEX_OPTIONS,
|
|
18911
|
+
partialFilterExpression: { key: { ...ORG_KEY_INDEX_OPTIONS.partialFilterExpression.key } }
|
|
18912
|
+
}
|
|
18913
|
+
);
|
|
18861
18914
|
for (const key of ORG_AS_BUILT_FIELD_NAMES) {
|
|
18862
18915
|
if (schema.pathType(key) === "adhocOrUndefined") {
|
|
18863
18916
|
schema.add({ [key]: orgAsBuiltSchemaDefinition[key] });
|
|
@@ -18866,6 +18919,7 @@ function addOrgRecordFields(schema, options = {}) {
|
|
|
18866
18919
|
return installVspTwoStepHooks(schema, options);
|
|
18867
18920
|
}
|
|
18868
18921
|
var EXPECTED_INSTANCE = {
|
|
18922
|
+
key: "String",
|
|
18869
18923
|
legalName: "String",
|
|
18870
18924
|
commonName: "String",
|
|
18871
18925
|
shortName: "String",
|
|
@@ -74768,6 +74822,9 @@ var CVC_197_VALUES = selectableCodes(
|
|
|
74768
74822
|
NeedsAssessmentChangeTypeKeys,
|
|
74769
74823
|
NeedsResidentialAgainKeys,
|
|
74770
74824
|
ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS,
|
|
74825
|
+
ORG_KEY_INDEX_NAME,
|
|
74826
|
+
ORG_KEY_INDEX_OPTIONS,
|
|
74827
|
+
ORG_KEY_INDEX_SPEC,
|
|
74771
74828
|
ORG_TYPE_FIELD_NAMES,
|
|
74772
74829
|
ORG_TYPE_HEADING_KEYS,
|
|
74773
74830
|
ORG_TYPE_KEYS,
|