psytools 0.3.2 → 0.5.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 +54 -17
- package/SOURCES.md +5 -1
- package/dist/cjs/assessment.d.ts +6 -4
- package/dist/cjs/assessment.js +10 -6
- package/dist/cjs/errors.d.ts +4 -2
- package/dist/cjs/evaluation.d.ts +10 -5
- package/dist/cjs/evaluation.js +68 -31
- package/dist/cjs/i18n.d.ts +22 -2
- package/dist/cjs/i18n.js +138 -2
- package/dist/cjs/index.d.ts +6 -2
- package/dist/cjs/index.js +20 -15
- package/dist/cjs/inventories/aq10.js +5 -35
- package/dist/cjs/inventories/asrs6.js +6 -28
- package/dist/cjs/inventories/audit.js +39 -56
- package/dist/cjs/inventories/common.js +0 -10
- package/dist/cjs/inventories/dass21.js +19 -75
- package/dist/cjs/inventories/gad7.js +5 -23
- package/dist/cjs/inventories/index.d.ts +11 -2
- package/dist/cjs/inventories/index.js +22 -3
- package/dist/cjs/inventories/mini-ipip.js +25 -59
- package/dist/cjs/inventories/phq9.js +6 -30
- package/dist/cjs/inventories/who5.js +5 -31
- package/dist/cjs/locales/de/aq10.d.ts +4 -0
- package/dist/cjs/locales/de/aq10.js +53 -0
- package/dist/cjs/locales/de/asrs6.d.ts +4 -0
- package/dist/cjs/locales/de/asrs6.js +42 -0
- package/dist/cjs/locales/de/audit.d.ts +4 -0
- package/dist/cjs/locales/de/audit.js +80 -0
- package/dist/cjs/locales/de/dass21.d.ts +4 -0
- package/dist/cjs/locales/de/dass21.js +114 -0
- package/dist/cjs/locales/de/gad7.d.ts +4 -0
- package/dist/cjs/locales/de/gad7.js +46 -0
- package/dist/cjs/locales/de/mini-ipip.d.ts +4 -0
- package/dist/cjs/locales/de/mini-ipip.js +97 -0
- package/dist/cjs/locales/de/phq9.d.ts +4 -0
- package/dist/cjs/locales/de/phq9.js +56 -0
- package/dist/cjs/locales/de/who5.d.ts +4 -0
- package/dist/cjs/locales/de/who5.js +41 -0
- package/dist/cjs/locales/es/aq10.d.ts +4 -0
- package/dist/cjs/locales/es/aq10.js +53 -0
- package/dist/cjs/locales/es/asrs6.d.ts +4 -0
- package/dist/cjs/locales/es/asrs6.js +42 -0
- package/dist/cjs/locales/es/audit.d.ts +4 -0
- package/dist/cjs/locales/es/audit.js +80 -0
- package/dist/cjs/locales/es/dass21.d.ts +4 -0
- package/dist/cjs/locales/es/dass21.js +114 -0
- package/dist/cjs/locales/es/gad7.d.ts +4 -0
- package/dist/cjs/locales/es/gad7.js +46 -0
- package/dist/cjs/locales/es/mini-ipip.d.ts +4 -0
- package/dist/cjs/locales/es/mini-ipip.js +97 -0
- package/dist/cjs/locales/es/phq9.d.ts +4 -0
- package/dist/cjs/locales/es/phq9.js +56 -0
- package/dist/cjs/locales/es/who5.d.ts +4 -0
- package/dist/cjs/locales/es/who5.js +41 -0
- package/dist/cjs/locales/index.d.ts +12 -0
- package/dist/cjs/locales/index.js +63 -0
- package/dist/cjs/locales/tr/aq10.d.ts +4 -0
- package/dist/cjs/locales/tr/aq10.js +53 -0
- package/dist/cjs/locales/tr/asrs6.d.ts +4 -0
- package/dist/cjs/locales/tr/asrs6.js +42 -0
- package/dist/cjs/locales/tr/audit.d.ts +4 -0
- package/dist/cjs/locales/tr/audit.js +80 -0
- package/dist/cjs/locales/tr/dass21.d.ts +4 -0
- package/dist/cjs/locales/tr/dass21.js +114 -0
- package/dist/cjs/locales/tr/gad7.d.ts +4 -0
- package/dist/cjs/locales/tr/gad7.js +46 -0
- package/dist/cjs/locales/tr/mini-ipip.d.ts +4 -0
- package/dist/cjs/locales/tr/mini-ipip.js +97 -0
- package/dist/cjs/locales/tr/phq9.d.ts +4 -0
- package/dist/cjs/locales/tr/phq9.js +56 -0
- package/dist/cjs/locales/tr/who5.d.ts +4 -0
- package/dist/cjs/locales/tr/who5.js +41 -0
- package/dist/cjs/locales/zh/aq10.d.ts +4 -0
- package/dist/cjs/locales/zh/aq10.js +53 -0
- package/dist/cjs/locales/zh/asrs6.d.ts +4 -0
- package/dist/cjs/locales/zh/asrs6.js +42 -0
- package/dist/cjs/locales/zh/audit.d.ts +4 -0
- package/dist/cjs/locales/zh/audit.js +80 -0
- package/dist/cjs/locales/zh/dass21.d.ts +4 -0
- package/dist/cjs/locales/zh/dass21.js +114 -0
- package/dist/cjs/locales/zh/gad7.d.ts +4 -0
- package/dist/cjs/locales/zh/gad7.js +46 -0
- package/dist/cjs/locales/zh/mini-ipip.d.ts +4 -0
- package/dist/cjs/locales/zh/mini-ipip.js +97 -0
- package/dist/cjs/locales/zh/phq9.d.ts +4 -0
- package/dist/cjs/locales/zh/phq9.js +56 -0
- package/dist/cjs/locales/zh/who5.d.ts +4 -0
- package/dist/cjs/locales/zh/who5.js +41 -0
- package/dist/cjs/types.d.ts +60 -1
- package/dist/esm/assessment.d.ts +6 -4
- package/dist/esm/assessment.js +11 -7
- package/dist/esm/errors.d.ts +4 -2
- package/dist/esm/evaluation.d.ts +10 -5
- package/dist/esm/evaluation.js +68 -31
- package/dist/esm/i18n.d.ts +22 -2
- package/dist/esm/i18n.js +135 -1
- package/dist/esm/index.d.ts +6 -2
- package/dist/esm/index.js +2 -1
- package/dist/esm/inventories/aq10.js +5 -35
- package/dist/esm/inventories/asrs6.js +6 -28
- package/dist/esm/inventories/audit.js +39 -56
- package/dist/esm/inventories/common.js +0 -10
- package/dist/esm/inventories/dass21.js +19 -75
- package/dist/esm/inventories/gad7.js +5 -23
- package/dist/esm/inventories/index.d.ts +11 -2
- package/dist/esm/inventories/index.js +22 -3
- package/dist/esm/inventories/mini-ipip.js +25 -59
- package/dist/esm/inventories/phq9.js +6 -30
- package/dist/esm/inventories/who5.js +5 -31
- package/dist/esm/locales/de/aq10.d.ts +4 -0
- package/dist/esm/locales/de/aq10.js +51 -0
- package/dist/esm/locales/de/asrs6.d.ts +4 -0
- package/dist/esm/locales/de/asrs6.js +40 -0
- package/dist/esm/locales/de/audit.d.ts +4 -0
- package/dist/esm/locales/de/audit.js +78 -0
- package/dist/esm/locales/de/dass21.d.ts +4 -0
- package/dist/esm/locales/de/dass21.js +112 -0
- package/dist/esm/locales/de/gad7.d.ts +4 -0
- package/dist/esm/locales/de/gad7.js +44 -0
- package/dist/esm/locales/de/mini-ipip.d.ts +4 -0
- package/dist/esm/locales/de/mini-ipip.js +95 -0
- package/dist/esm/locales/de/phq9.d.ts +4 -0
- package/dist/esm/locales/de/phq9.js +54 -0
- package/dist/esm/locales/de/who5.d.ts +4 -0
- package/dist/esm/locales/de/who5.js +39 -0
- package/dist/esm/locales/es/aq10.d.ts +4 -0
- package/dist/esm/locales/es/aq10.js +51 -0
- package/dist/esm/locales/es/asrs6.d.ts +4 -0
- package/dist/esm/locales/es/asrs6.js +40 -0
- package/dist/esm/locales/es/audit.d.ts +4 -0
- package/dist/esm/locales/es/audit.js +78 -0
- package/dist/esm/locales/es/dass21.d.ts +4 -0
- package/dist/esm/locales/es/dass21.js +112 -0
- package/dist/esm/locales/es/gad7.d.ts +4 -0
- package/dist/esm/locales/es/gad7.js +44 -0
- package/dist/esm/locales/es/mini-ipip.d.ts +4 -0
- package/dist/esm/locales/es/mini-ipip.js +95 -0
- package/dist/esm/locales/es/phq9.d.ts +4 -0
- package/dist/esm/locales/es/phq9.js +54 -0
- package/dist/esm/locales/es/who5.d.ts +4 -0
- package/dist/esm/locales/es/who5.js +39 -0
- package/dist/esm/locales/index.d.ts +12 -0
- package/dist/esm/locales/index.js +59 -0
- package/dist/esm/locales/tr/aq10.d.ts +4 -0
- package/dist/esm/locales/tr/aq10.js +51 -0
- package/dist/esm/locales/tr/asrs6.d.ts +4 -0
- package/dist/esm/locales/tr/asrs6.js +40 -0
- package/dist/esm/locales/tr/audit.d.ts +4 -0
- package/dist/esm/locales/tr/audit.js +78 -0
- package/dist/esm/locales/tr/dass21.d.ts +4 -0
- package/dist/esm/locales/tr/dass21.js +112 -0
- package/dist/esm/locales/tr/gad7.d.ts +4 -0
- package/dist/esm/locales/tr/gad7.js +44 -0
- package/dist/esm/locales/tr/mini-ipip.d.ts +4 -0
- package/dist/esm/locales/tr/mini-ipip.js +95 -0
- package/dist/esm/locales/tr/phq9.d.ts +4 -0
- package/dist/esm/locales/tr/phq9.js +54 -0
- package/dist/esm/locales/tr/who5.d.ts +4 -0
- package/dist/esm/locales/tr/who5.js +39 -0
- package/dist/esm/locales/zh/aq10.d.ts +4 -0
- package/dist/esm/locales/zh/aq10.js +51 -0
- package/dist/esm/locales/zh/asrs6.d.ts +4 -0
- package/dist/esm/locales/zh/asrs6.js +40 -0
- package/dist/esm/locales/zh/audit.d.ts +4 -0
- package/dist/esm/locales/zh/audit.js +78 -0
- package/dist/esm/locales/zh/dass21.d.ts +4 -0
- package/dist/esm/locales/zh/dass21.js +112 -0
- package/dist/esm/locales/zh/gad7.d.ts +4 -0
- package/dist/esm/locales/zh/gad7.js +44 -0
- package/dist/esm/locales/zh/mini-ipip.d.ts +4 -0
- package/dist/esm/locales/zh/mini-ipip.js +95 -0
- package/dist/esm/locales/zh/phq9.d.ts +4 -0
- package/dist/esm/locales/zh/phq9.js +54 -0
- package/dist/esm/locales/zh/who5.d.ts +4 -0
- package/dist/esm/locales/zh/who5.js +39 -0
- package/dist/esm/types.d.ts +60 -1
- package/package.json +21 -1
- package/schema/assessment-definition.schema.json +15 -3
- package/src/assessment.ts +15 -9
- package/src/errors.ts +26 -2
- package/src/evaluation.ts +103 -30
- package/src/i18n.ts +177 -2
- package/src/index.ts +9 -1
- package/src/inventories/aq10.ts +5 -35
- package/src/inventories/asrs6.ts +6 -28
- package/src/inventories/audit.ts +39 -56
- package/src/inventories/common.ts +0 -10
- package/src/inventories/dass21.ts +19 -75
- package/src/inventories/gad7.ts +5 -23
- package/src/inventories/index.ts +27 -3
- package/src/inventories/mini-ipip.ts +25 -59
- package/src/inventories/phq9.ts +6 -30
- package/src/inventories/who5.ts +5 -31
- package/src/locales/de/aq10.ts +54 -0
- package/src/locales/de/asrs6.ts +43 -0
- package/src/locales/de/audit.ts +81 -0
- package/src/locales/de/dass21.ts +115 -0
- package/src/locales/de/gad7.ts +47 -0
- package/src/locales/de/mini-ipip.ts +98 -0
- package/src/locales/de/phq9.ts +57 -0
- package/src/locales/de/who5.ts +42 -0
- package/src/locales/es/aq10.ts +54 -0
- package/src/locales/es/asrs6.ts +43 -0
- package/src/locales/es/audit.ts +81 -0
- package/src/locales/es/dass21.ts +115 -0
- package/src/locales/es/gad7.ts +47 -0
- package/src/locales/es/mini-ipip.ts +98 -0
- package/src/locales/es/phq9.ts +57 -0
- package/src/locales/es/who5.ts +42 -0
- package/src/locales/index.ts +64 -0
- package/src/locales/tr/aq10.ts +54 -0
- package/src/locales/tr/asrs6.ts +43 -0
- package/src/locales/tr/audit.ts +81 -0
- package/src/locales/tr/dass21.ts +115 -0
- package/src/locales/tr/gad7.ts +47 -0
- package/src/locales/tr/mini-ipip.ts +98 -0
- package/src/locales/tr/phq9.ts +57 -0
- package/src/locales/tr/who5.ts +42 -0
- package/src/locales/zh/aq10.ts +54 -0
- package/src/locales/zh/asrs6.ts +43 -0
- package/src/locales/zh/audit.ts +81 -0
- package/src/locales/zh/dass21.ts +115 -0
- package/src/locales/zh/gad7.ts +47 -0
- package/src/locales/zh/mini-ipip.ts +98 -0
- package/src/locales/zh/phq9.ts +57 -0
- package/src/locales/zh/who5.ts +42 -0
- package/src/types.ts +63 -6
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@ Give your app a validated psychological questionnaire — rendered, collected, a
|
|
|
5
5
|
```ts
|
|
6
6
|
import { loadInventory } from "psytools";
|
|
7
7
|
|
|
8
|
-
const phq9 = loadInventory("phq9");
|
|
8
|
+
const phq9 = await loadInventory("phq9"); // Patient Health Questionnaire-9
|
|
9
9
|
phq9.localize("en"); // render-ready questions & options for your UI
|
|
10
10
|
|
|
11
11
|
const response = phq9.createResponse();
|
|
@@ -19,10 +19,11 @@ That's a complete depression screening: standardized items, answer validation, p
|
|
|
19
19
|
|
|
20
20
|
## Why psytools
|
|
21
21
|
|
|
22
|
-
- **Batteries included** — PHQ-9, GAD-7,
|
|
22
|
+
- **Batteries included** — eight instruments (PHQ-9, GAD-7, DASS-21, WHO-5, ASRS, AQ-10, AUDIT, Mini-IPIP) ship ready to use in English, Turkish, German, Chinese, and Spanish, with published scoring rules and citations.
|
|
23
23
|
- **Your tests too** — therapists and researchers can define their own instruments as one plain JSON object; psytools validates, localizes, and scores them the same way.
|
|
24
24
|
- **Everything is plain JSON** — assessments and responses `stringify()`/`parse()` losslessly, so definitions live in your database and travel between backend and frontend. Scoring rules are data, not code, and survive the round trip.
|
|
25
25
|
- **Safe by default** — every answer is validated against the option scale, incomplete responses can't be scored accidentally, and submitted responses are immutable.
|
|
26
|
+
- **Data minimization by default** — base definitions carry English only; other languages ship as per-inventory locale packs that are lazily imported (and only then enter memory or your bundle) when you request them.
|
|
26
27
|
- **Runs anywhere** — zero runtime dependencies; Node (>= 18), browsers, and edge runtimes; ESM + CommonJS with full TypeScript declarations.
|
|
27
28
|
|
|
28
29
|
## Install
|
|
@@ -36,7 +37,8 @@ npm install psytools
|
|
|
36
37
|
```ts
|
|
37
38
|
import { loadInventory } from "psytools";
|
|
38
39
|
|
|
39
|
-
|
|
40
|
+
// Locales are lazy: only the requested packs are loaded.
|
|
41
|
+
const phq9 = await loadInventory("phq9", { locales: ["tr"] });
|
|
40
42
|
|
|
41
43
|
// 1. Render — get a flat, single-locale view for your UI.
|
|
42
44
|
const view = phq9.localize("tr");
|
|
@@ -61,7 +63,7 @@ const result = phq9.evaluate(response);
|
|
|
61
63
|
|
|
62
64
|
// evaluate() refuses responses that are not complete/submitted;
|
|
63
65
|
// score partial data explicitly:
|
|
64
|
-
phq9.evaluate(inProgressResponse,
|
|
66
|
+
phq9.evaluate(inProgressResponse, { allowIncomplete: true });
|
|
65
67
|
|
|
66
68
|
// 4. Persist — both sides are plain JSON.
|
|
67
69
|
db.save(response.stringify()); // response -> DB
|
|
@@ -81,14 +83,14 @@ const response = AssessmentResponse.parse(assessment, rowFromDb); // answers re-
|
|
|
81
83
|
|
|
82
84
|
| Id | Instrument | Items | Scoring | Locales |
|
|
83
85
|
| --- | --- | --- | --- | --- |
|
|
84
|
-
| `phq9` | Patient Health Questionnaire-9 (depression) | 9 | Sum 0–27, 5 severity bands, item-9 suicidality flag | en, tr, de |
|
|
85
|
-
| `gad7` | Generalized Anxiety Disorder-7 | 7 | Sum 0–21, 4 severity bands | en, tr, de |
|
|
86
|
-
| `dass21` | Depression Anxiety Stress Scales (short form) | 21 | 3 subscales × 7 items, sums doubled, banded per subscale | en, tr, de |
|
|
87
|
-
| `who5` | WHO-5 Well-Being Index | 5 | Sum × 4 → 0–100 (higher is better), 3 well-being bands | en, tr, de |
|
|
88
|
-
| `asrs6` | Adult ADHD Self-Report Scale (ASRS-v1.1) screener | 6 | Count of screen-positive items (per-item thresholds), ≥4 positive | en, tr, de |
|
|
89
|
-
| `aq10` | Autism Spectrum Quotient (AQ-10, adult) | 10 | 1 point per item in trait direction (agree/disagree), ≥6 refer | en, tr, de |
|
|
90
|
-
| `audit` | Alcohol Use Disorders Identification Test (WHO) | 10 | Sum 0–40 with per-question point systems, 4 WHO risk zones | en, tr, de |
|
|
91
|
-
| `mini-ipip` | Mini-IPIP Big Five personality scale | 20 | 5 trait subscales (4–20 each), reverse-keyed items, no cutoffs | en, tr, de |
|
|
86
|
+
| `phq9` | Patient Health Questionnaire-9 (depression) | 9 | Sum 0–27, 5 severity bands, item-9 suicidality flag | en, tr, de, zh, es |
|
|
87
|
+
| `gad7` | Generalized Anxiety Disorder-7 | 7 | Sum 0–21, 4 severity bands | en, tr, de, zh, es |
|
|
88
|
+
| `dass21` | Depression Anxiety Stress Scales (short form) | 21 | 3 subscales × 7 items, sums doubled, banded per subscale | en, tr, de, zh, es |
|
|
89
|
+
| `who5` | WHO-5 Well-Being Index | 5 | Sum × 4 → 0–100 (higher is better), 3 well-being bands | en, tr, de, zh, es |
|
|
90
|
+
| `asrs6` | Adult ADHD Self-Report Scale (ASRS-v1.1) screener | 6 | Count of screen-positive items (per-item thresholds), ≥4 positive | en, tr, de, zh, es |
|
|
91
|
+
| `aq10` | Autism Spectrum Quotient (AQ-10, adult) | 10 | 1 point per item in trait direction (agree/disagree), ≥6 refer | en, tr, de, zh, es |
|
|
92
|
+
| `audit` | Alcohol Use Disorders Identification Test (WHO) | 10 | Sum 0–40 with per-question point systems, 4 WHO risk zones | en, tr, de, zh, es |
|
|
93
|
+
| `mini-ipip` | Mini-IPIP Big Five personality scale | 20 | 5 trait subscales (4–20 each), reverse-keyed items, no cutoffs | en, tr, de, zh, es |
|
|
92
94
|
|
|
93
95
|
```ts
|
|
94
96
|
import { loadInventory, inventories, dass21 } from "psytools";
|
|
@@ -147,6 +149,40 @@ Questions may also carry their own `options` to override the default scale, and
|
|
|
147
149
|
|
|
148
150
|
Non-JavaScript backends can validate stored definitions against the published [JSON Schema](schema/assessment-definition.schema.json) (shipped in the npm package under `schema/`).
|
|
149
151
|
|
|
152
|
+
### Data minimization
|
|
153
|
+
|
|
154
|
+
Minimization is the default, at every layer:
|
|
155
|
+
|
|
156
|
+
- **Memory / runtime**: base definitions are English-only. `loadInventory(id, { locales })` dynamically imports just the requested locale packs and merges them — nothing else is ever loaded. `availableLocales(id)` lists what exists.
|
|
157
|
+
- **Bundles**: import a single inventory via `psytools/inventories/<id>` (~2 kB gzipped) and, for static bundling, a specific pack via `psytools/locales/<locale>/<id>`, merged with `applyLocale`:
|
|
158
|
+
|
|
159
|
+
```ts
|
|
160
|
+
import { phq9 } from "psytools/inventories/phq9"; // en base
|
|
161
|
+
import tr from "psytools/locales/tr/phq9"; // one language pack
|
|
162
|
+
import { Assessment, applyLocale } from "psytools";
|
|
163
|
+
|
|
164
|
+
const assessment = new Assessment(applyLocale(phq9, tr));
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Named root imports also tree-shake (`sideEffects: false`).
|
|
168
|
+
- **Payloads**: a loaded definition contains exactly the locales you asked for, so `res.json(assessment.definition)` is already minimal. To slim an existing multi-locale definition (e.g. a stored custom test), use `pickLocales(definition, [userLocale])`.
|
|
169
|
+
|
|
170
|
+
Merged definitions remain one self-contained JSON object — locale loading never breaks the `stringify → DB → parse` round trip.
|
|
171
|
+
|
|
172
|
+
### Missing answers
|
|
173
|
+
|
|
174
|
+
Declarative scoring takes an optional missing-data policy governing how incomplete answer sets are scored (they reach the scorer via raw answer maps or `allowIncomplete`):
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
scoring: {
|
|
178
|
+
kind: "sum",
|
|
179
|
+
missing: { strategy: "prorate", minAnswered: 7 }, // or "ignore" (default) / "require-complete"
|
|
180
|
+
...
|
|
181
|
+
}
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
`ignore` sums what is answered (partial totals understate severity — use deliberately); `prorate` scales the raw score up to the full item count (rounded) and refuses to score below `minAnswered`; `require-complete` throws unless every contributing non-optional item is answered. For subscale scoring the policy applies to each subscale independently.
|
|
185
|
+
|
|
150
186
|
## Custom evaluation
|
|
151
187
|
|
|
152
188
|
Declarative scoring is optional. Pass an evaluator for anything beyond sums and subscales — it can return a single scale, multiple scales, a category, or arbitrary data:
|
|
@@ -163,7 +199,7 @@ const attachmentStyle: Evaluator = (definition, answers) => {
|
|
|
163
199
|
};
|
|
164
200
|
};
|
|
165
201
|
|
|
166
|
-
assessment.evaluate(response, attachmentStyle);
|
|
202
|
+
assessment.evaluate(response, { evaluator: attachmentStyle });
|
|
167
203
|
```
|
|
168
204
|
|
|
169
205
|
Result shapes: `scale` (single score + band + flags), `multiscale` (named subscales), `categorical`, and `custom` (escape hatch).
|
|
@@ -184,11 +220,12 @@ const history = rows
|
|
|
184
220
|
| --- | --- |
|
|
185
221
|
| `Assessment` | Wraps a definition: validation, `localize()`, `createResponse()`, `evaluate()`, `stringify()`/`parse()` |
|
|
186
222
|
| `AssessmentResponse` | `answer()`, `answerAll()`, `clearAnswer()`, `status`, `progress()`, `validate()`, `submit()`, `stringify()`/`parse()` |
|
|
187
|
-
| `evaluate(definition, answers, evaluator?)` | Standalone scoring (also available as `Assessment#evaluate`) |
|
|
223
|
+
| `evaluate(definition, answers, { evaluator? })` | Standalone scoring (also available as `Assessment#evaluate`) |
|
|
188
224
|
| `validateDefinition(input)` | Non-throwing structural validation of definitions |
|
|
189
|
-
| `loadInventory(id)` / `inventories`
|
|
190
|
-
| `
|
|
191
|
-
| `
|
|
225
|
+
| `loadInventory(id, { locales? })` / `inventories` | Predefined instruments (async; English-only base definitions also exported by name) |
|
|
226
|
+
| `applyLocale(definition, pack)` / `availableLocales(id)` / `localePacks` | Lazy per-inventory locale packs |
|
|
227
|
+
| `localizeText(text, locale, fallback?)` / `collectLocales(texts)` / `pickLocales(definition, locales)` | Locale helpers |
|
|
228
|
+
| `PsytoolsError` | All errors carry a `code` typed as `PsytoolsErrorCode` (e.g. `invalid_value`, `already_submitted`) |
|
|
192
229
|
|
|
193
230
|
## Development
|
|
194
231
|
|
package/SOURCES.md
CHANGED
|
@@ -21,8 +21,12 @@ The same provenance applies to every bundled inventory. If an inventory ever dev
|
|
|
21
21
|
| en | Reproduced from the original published instrument | Yes |
|
|
22
22
|
| tr | AI translation (Anthropic Claude, `claude-fable-5`) from the original English | No |
|
|
23
23
|
| de | AI translation (Anthropic Claude, `claude-fable-5`) from the original English | No |
|
|
24
|
+
| zh | AI translation (Anthropic Claude, `claude-fable-5`) from the original English | No |
|
|
25
|
+
| es | AI translation (Anthropic Claude, `claude-fable-5`) from the original English | No |
|
|
24
26
|
|
|
25
|
-
Official validated translations exist for most of these instruments, but they were **not consulted** in preparing the bundled texts, so they are deliberately not cited as sources. The packaged
|
|
27
|
+
Official validated translations exist for most of these instruments, but they were **not consulted** in preparing the bundled texts, so they are deliberately not cited as sources. The packaged non-English wording has not been checked against them and has not been psychometrically validated. Validated instruments are only validated for their exact wording — before clinical or research use, obtain the official version for your language and compare or replace the text.
|
|
28
|
+
|
|
29
|
+
Non-English texts live as one file per inventory per language under [`src/locales/<locale>/`](src/locales) — exactly the unit a native-speaker reviewer needs. Verification contributions are very welcome.
|
|
26
30
|
|
|
27
31
|
## PHQ-9 — Patient Health Questionnaire-9 (`phq9`)
|
|
28
32
|
|
package/dist/cjs/assessment.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
import type { AssessmentDefinition, AssessmentOption, AssessmentQuestion, EvaluationResult,
|
|
1
|
+
import type { AssessmentDefinition, AssessmentOption, AssessmentQuestion, EvaluationResult, LocalizedAssessmentView, ValidationResult } from "./types.ts";
|
|
2
2
|
import { AssessmentResponse } from "./response.ts";
|
|
3
|
+
import { type EvaluateOptions } from "./evaluation.ts";
|
|
3
4
|
/**
|
|
4
5
|
* Structurally validates an assessment definition (useful before persisting
|
|
5
6
|
* user-created assessments). Returns issues instead of throwing.
|
|
@@ -34,16 +35,17 @@ export declare class Assessment {
|
|
|
34
35
|
}): AssessmentResponse;
|
|
35
36
|
/**
|
|
36
37
|
* Evaluates a response (or raw answers) with the definition's declarative
|
|
37
|
-
* scoring, or with `evaluator` when provided.
|
|
38
|
+
* scoring, or with `options.evaluator` when provided.
|
|
38
39
|
*
|
|
39
40
|
* When given an `AssessmentResponse`, its status must be `complete` or
|
|
40
41
|
* `submitted` — pass `allowIncomplete` to score partial responses anyway.
|
|
41
42
|
* Raw answer maps skip the completeness check, but their values are
|
|
42
|
-
* still validated against the option scales
|
|
43
|
+
* still validated against the option scales, and the scoring definition's
|
|
44
|
+
* missing-data policy still applies.
|
|
43
45
|
*
|
|
44
46
|
* @throws PsytoolsError `incomplete_response` | `unknown_question` | `invalid_value` | `no_scoring`
|
|
45
47
|
*/
|
|
46
|
-
evaluate(response: AssessmentResponse | Record<string, number>,
|
|
48
|
+
evaluate(response: AssessmentResponse | Record<string, number>, options?: EvaluateOptions & {
|
|
47
49
|
allowIncomplete?: boolean;
|
|
48
50
|
}): EvaluationResult;
|
|
49
51
|
/** The plain serializable definition (used by `JSON.stringify`). */
|
package/dist/cjs/assessment.js
CHANGED
|
@@ -191,16 +191,20 @@ class Assessment {
|
|
|
191
191
|
}
|
|
192
192
|
/**
|
|
193
193
|
* Evaluates a response (or raw answers) with the definition's declarative
|
|
194
|
-
* scoring, or with `evaluator` when provided.
|
|
194
|
+
* scoring, or with `options.evaluator` when provided.
|
|
195
195
|
*
|
|
196
196
|
* When given an `AssessmentResponse`, its status must be `complete` or
|
|
197
197
|
* `submitted` — pass `allowIncomplete` to score partial responses anyway.
|
|
198
198
|
* Raw answer maps skip the completeness check, but their values are
|
|
199
|
-
* still validated against the option scales
|
|
199
|
+
* still validated against the option scales, and the scoring definition's
|
|
200
|
+
* missing-data policy still applies.
|
|
200
201
|
*
|
|
201
202
|
* @throws PsytoolsError `incomplete_response` | `unknown_question` | `invalid_value` | `no_scoring`
|
|
202
203
|
*/
|
|
203
|
-
evaluate(response,
|
|
204
|
+
evaluate(response, options) {
|
|
205
|
+
if (typeof options === "function") {
|
|
206
|
+
throw new errors_ts_1.PsytoolsError("invalid_argument", "Pass the evaluator as an option: assessment.evaluate(response, { evaluator })");
|
|
207
|
+
}
|
|
204
208
|
if (response instanceof response_ts_1.AssessmentResponse) {
|
|
205
209
|
const scorable = response.status === "complete" || response.status === "submitted";
|
|
206
210
|
if (!scorable && !options?.allowIncomplete) {
|
|
@@ -208,9 +212,9 @@ class Assessment {
|
|
|
208
212
|
throw new errors_ts_1.PsytoolsError("incomplete_response", `Cannot evaluate a response with status "${response.status}" (unanswered: ${missing}); ` +
|
|
209
213
|
"pass { allowIncomplete: true } to score it anyway");
|
|
210
214
|
}
|
|
211
|
-
return (0, evaluation_ts_1.evaluate)(this.definition, response.answers, evaluator);
|
|
215
|
+
return (0, evaluation_ts_1.evaluate)(this.definition, response.answers, { evaluator: options?.evaluator });
|
|
212
216
|
}
|
|
213
|
-
return (0, evaluation_ts_1.evaluate)(this.definition, response, evaluator);
|
|
217
|
+
return (0, evaluation_ts_1.evaluate)(this.definition, response, { evaluator: options?.evaluator });
|
|
214
218
|
}
|
|
215
219
|
/** The plain serializable definition (used by `JSON.stringify`). */
|
|
216
220
|
toJSON() {
|
|
@@ -237,7 +241,7 @@ class Assessment {
|
|
|
237
241
|
return new Assessment(raw);
|
|
238
242
|
}
|
|
239
243
|
text(text, locale) {
|
|
240
|
-
return (0, i18n_ts_1.
|
|
244
|
+
return (0, i18n_ts_1.localizeText)(text, locale ?? this.definition.defaultLocale, this.definition.defaultLocale);
|
|
241
245
|
}
|
|
242
246
|
}
|
|
243
247
|
exports.Assessment = Assessment;
|
package/dist/cjs/errors.d.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
|
+
/** Every error code psytools can throw, for exhaustive handling. */
|
|
2
|
+
export type PsytoolsErrorCode = "malformed" | "duplicate_question" | "invalid_definition" | "unknown_question" | "invalid_value" | "missing_answer" | "already_submitted" | "invalid_response" | "incomplete_response" | "assessment_mismatch" | "no_scoring" | "invalid_json" | "unknown_inventory" | "unknown_locale" | "invalid_argument";
|
|
1
3
|
/** Error thrown by psytools, carrying a stable machine-readable code. */
|
|
2
4
|
export declare class PsytoolsError extends Error {
|
|
3
|
-
readonly code:
|
|
4
|
-
constructor(code:
|
|
5
|
+
readonly code: PsytoolsErrorCode;
|
|
6
|
+
constructor(code: PsytoolsErrorCode, message: string);
|
|
5
7
|
}
|
package/dist/cjs/evaluation.d.ts
CHANGED
|
@@ -1,12 +1,17 @@
|
|
|
1
1
|
import type { AnswerMap, AssessmentDefinition, EvaluationResult, Evaluator } from "./types.ts";
|
|
2
|
+
export interface EvaluateOptions {
|
|
3
|
+
/** Custom evaluator used instead of the definition's declarative scoring. */
|
|
4
|
+
evaluator?: Evaluator;
|
|
5
|
+
}
|
|
2
6
|
/**
|
|
3
7
|
* Evaluates answers against an assessment definition.
|
|
4
8
|
*
|
|
5
9
|
* Every answer is first validated against the assessment: the question must
|
|
6
|
-
* exist and the value must belong to its option scale. Then
|
|
7
|
-
* used when given; otherwise the definition's
|
|
8
|
-
* (`sum` or `
|
|
10
|
+
* exist and the value must belong to its option scale. Then
|
|
11
|
+
* `options.evaluator` is used when given; otherwise the definition's
|
|
12
|
+
* declarative `scoring` (`sum`, `subscales`, or `count`) applies, honoring
|
|
13
|
+
* its missing-data policy.
|
|
9
14
|
*
|
|
10
|
-
* @throws PsytoolsError `unknown_question` | `invalid_value` | `no_scoring`
|
|
15
|
+
* @throws PsytoolsError `unknown_question` | `invalid_value` | `incomplete_response` | `no_scoring`
|
|
11
16
|
*/
|
|
12
|
-
export declare function evaluate(definition: AssessmentDefinition, answers: AnswerMap,
|
|
17
|
+
export declare function evaluate(definition: AssessmentDefinition, answers: AnswerMap, options?: EvaluateOptions): EvaluationResult;
|
package/dist/cjs/evaluation.js
CHANGED
|
@@ -6,16 +6,20 @@ const errors_ts_1 = require("./errors.js");
|
|
|
6
6
|
* Evaluates answers against an assessment definition.
|
|
7
7
|
*
|
|
8
8
|
* Every answer is first validated against the assessment: the question must
|
|
9
|
-
* exist and the value must belong to its option scale. Then
|
|
10
|
-
* used when given; otherwise the definition's
|
|
11
|
-
* (`sum` or `
|
|
9
|
+
* exist and the value must belong to its option scale. Then
|
|
10
|
+
* `options.evaluator` is used when given; otherwise the definition's
|
|
11
|
+
* declarative `scoring` (`sum`, `subscales`, or `count`) applies, honoring
|
|
12
|
+
* its missing-data policy.
|
|
12
13
|
*
|
|
13
|
-
* @throws PsytoolsError `unknown_question` | `invalid_value` | `no_scoring`
|
|
14
|
+
* @throws PsytoolsError `unknown_question` | `invalid_value` | `incomplete_response` | `no_scoring`
|
|
14
15
|
*/
|
|
15
|
-
function evaluate(definition, answers,
|
|
16
|
+
function evaluate(definition, answers, options) {
|
|
17
|
+
if (typeof options === "function") {
|
|
18
|
+
throw new errors_ts_1.PsytoolsError("invalid_argument", "Pass the evaluator as an option: evaluate(definition, answers, { evaluator })");
|
|
19
|
+
}
|
|
16
20
|
assertValidAnswers(definition, answers);
|
|
17
|
-
if (evaluator)
|
|
18
|
-
return evaluator(definition, answers);
|
|
21
|
+
if (options?.evaluator)
|
|
22
|
+
return options.evaluator(definition, answers);
|
|
19
23
|
const scoring = definition.scoring;
|
|
20
24
|
if (!scoring) {
|
|
21
25
|
throw new errors_ts_1.PsytoolsError("no_scoring", `Assessment "${definition.id}" has no scoring definition; pass a custom evaluator`);
|
|
@@ -24,19 +28,22 @@ function evaluate(definition, answers, evaluator) {
|
|
|
24
28
|
case "sum":
|
|
25
29
|
return evaluateSum(definition, answers, scoring);
|
|
26
30
|
case "count": {
|
|
27
|
-
|
|
31
|
+
const questions = scoring.items.map((item) => requireQuestion(definition, item.questionId));
|
|
32
|
+
const answered = enforceMissing(questions, answers, scoring.missing);
|
|
33
|
+
let positives = 0;
|
|
28
34
|
for (const item of scoring.items) {
|
|
29
35
|
const question = requireQuestion(definition, item.questionId);
|
|
30
|
-
const
|
|
31
|
-
if (
|
|
36
|
+
const value = answers[question.id];
|
|
37
|
+
if (value === undefined)
|
|
32
38
|
continue;
|
|
33
39
|
const values = (question.options ?? definition.options).map((o) => o.value);
|
|
34
40
|
const effective = question.reverseScored
|
|
35
|
-
? Math.max(...values) + Math.min(...values) -
|
|
36
|
-
:
|
|
41
|
+
? Math.max(...values) + Math.min(...values) - value
|
|
42
|
+
: value;
|
|
37
43
|
if (effective >= item.minValue)
|
|
38
|
-
|
|
44
|
+
positives += 1;
|
|
39
45
|
}
|
|
46
|
+
const score = prorate(positives, answered, questions.length, scoring.missing);
|
|
40
47
|
return {
|
|
41
48
|
kind: "scale",
|
|
42
49
|
score,
|
|
@@ -49,15 +56,12 @@ function evaluate(definition, answers, evaluator) {
|
|
|
49
56
|
case "subscales": {
|
|
50
57
|
const scales = scoring.subscales.map((subscale) => {
|
|
51
58
|
const questions = subscale.questionIds.map((id) => requireQuestion(definition, id));
|
|
52
|
-
const
|
|
53
|
-
const { score, min, max } = sumQuestions(definition, questions, answers, multiplier);
|
|
59
|
+
const scored = scoreQuestionSet(definition, questions, answers, subscale.multiplier ?? 1, scoring.missing, subscale.id);
|
|
54
60
|
return {
|
|
55
61
|
id: subscale.id,
|
|
56
62
|
label: subscale.label,
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
max,
|
|
60
|
-
...bandOf(score, subscale.bands),
|
|
63
|
+
...scored,
|
|
64
|
+
...bandOf(scored.score, subscale.bands),
|
|
61
65
|
};
|
|
62
66
|
});
|
|
63
67
|
return {
|
|
@@ -85,19 +89,21 @@ function assertValidAnswers(definition, answers) {
|
|
|
85
89
|
}
|
|
86
90
|
}
|
|
87
91
|
function evaluateSum(definition, answers, scoring) {
|
|
88
|
-
const
|
|
89
|
-
const { score, min, max } = sumQuestions(definition, definition.questions, answers, multiplier);
|
|
92
|
+
const result = scoreQuestionSet(definition, definition.questions, answers, scoring.multiplier ?? 1, scoring.missing);
|
|
90
93
|
return {
|
|
91
94
|
kind: "scale",
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
max,
|
|
95
|
-
...bandOf(score, scoring.bands),
|
|
95
|
+
...result,
|
|
96
|
+
...bandOf(result.score, scoring.bands),
|
|
96
97
|
flags: triggeredFlags(answers, scoring.flags),
|
|
97
98
|
};
|
|
98
99
|
}
|
|
99
|
-
|
|
100
|
-
|
|
100
|
+
/**
|
|
101
|
+
* Sums one set of questions (the whole assessment or one subscale),
|
|
102
|
+
* applying reverse scoring, the missing-data policy, and the multiplier.
|
|
103
|
+
*/
|
|
104
|
+
function scoreQuestionSet(definition, questions, answers, multiplier, missing, scaleId) {
|
|
105
|
+
const answered = enforceMissing(questions, answers, missing, scaleId);
|
|
106
|
+
let raw = 0;
|
|
101
107
|
let min = 0;
|
|
102
108
|
let max = 0;
|
|
103
109
|
for (const question of questions) {
|
|
@@ -106,12 +112,43 @@ function sumQuestions(definition, questions, answers, multiplier) {
|
|
|
106
112
|
const highest = Math.max(...values);
|
|
107
113
|
min += lowest;
|
|
108
114
|
max += highest;
|
|
109
|
-
const
|
|
110
|
-
if (
|
|
115
|
+
const value = answers[question.id];
|
|
116
|
+
if (value === undefined)
|
|
111
117
|
continue;
|
|
112
|
-
|
|
118
|
+
raw += question.reverseScored ? highest + lowest - value : value;
|
|
113
119
|
}
|
|
114
|
-
|
|
120
|
+
raw = prorate(raw, answered, questions.length, missing);
|
|
121
|
+
return { score: raw * multiplier, min: min * multiplier, max: max * multiplier };
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* Enforces the missing-data policy over one set of contributing questions
|
|
125
|
+
* and returns how many of them are answered.
|
|
126
|
+
*
|
|
127
|
+
* `require-complete` only demands questions that are not marked `optional`.
|
|
128
|
+
*/
|
|
129
|
+
function enforceMissing(questions, answers, missing, scaleId) {
|
|
130
|
+
const strategy = missing?.strategy ?? "ignore";
|
|
131
|
+
const minAnswered = missing?.minAnswered ?? (strategy === "prorate" ? 1 : 0);
|
|
132
|
+
const scope = scaleId ? ` in subscale "${scaleId}"` : "";
|
|
133
|
+
const answered = questions.filter((q) => answers[q.id] !== undefined).length;
|
|
134
|
+
if (strategy === "require-complete") {
|
|
135
|
+
const unanswered = questions
|
|
136
|
+
.filter((q) => !(q.optional ?? false) && answers[q.id] === undefined)
|
|
137
|
+
.map((q) => q.id);
|
|
138
|
+
if (unanswered.length > 0) {
|
|
139
|
+
throw new errors_ts_1.PsytoolsError("incomplete_response", `Scoring requires complete answers${scope}; unanswered: ${unanswered.join(", ")}`);
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
if (answered < minAnswered) {
|
|
143
|
+
throw new errors_ts_1.PsytoolsError("incomplete_response", `Scoring requires at least ${minAnswered} answered item(s)${scope}, got ${answered}`);
|
|
144
|
+
}
|
|
145
|
+
return answered;
|
|
146
|
+
}
|
|
147
|
+
/** Scales a partial raw score up to the full item count (rounded). */
|
|
148
|
+
function prorate(raw, answered, total, missing) {
|
|
149
|
+
if (missing?.strategy !== "prorate" || answered === 0 || answered === total)
|
|
150
|
+
return raw;
|
|
151
|
+
return Math.round((raw * total) / answered);
|
|
115
152
|
}
|
|
116
153
|
function bandOf(score, bands) {
|
|
117
154
|
const match = bands?.find((band) => score >= band.min && score <= band.max);
|
package/dist/cjs/i18n.d.ts
CHANGED
|
@@ -1,10 +1,30 @@
|
|
|
1
|
-
import type { LocalizedText } from "./types.ts";
|
|
1
|
+
import type { AssessmentDefinition, InventoryLocalePack, LocalizedText } from "./types.ts";
|
|
2
2
|
/**
|
|
3
3
|
* Resolves a `LocalizedText` to a string for the given locale.
|
|
4
4
|
*
|
|
5
5
|
* Resolution order: exact locale -> base language of the locale
|
|
6
6
|
* (`"de-AT"` -> `"de"`) -> `fallbackLocale` -> first available entry.
|
|
7
7
|
*/
|
|
8
|
-
export declare function
|
|
8
|
+
export declare function localizeText(text: LocalizedText, locale: string, fallbackLocale?: string): string;
|
|
9
|
+
/**
|
|
10
|
+
* Merges a locale pack into a definition, returning a new definition that
|
|
11
|
+
* additionally carries the pack's language in every localized text. The
|
|
12
|
+
* original definition and the pack are not modified.
|
|
13
|
+
*
|
|
14
|
+
* Packs may be partial (untranslated entries keep their existing locales),
|
|
15
|
+
* but entries referencing unknown question/band/flag/subscale ids or
|
|
16
|
+
* mismatched option counts throw `invalid_argument`.
|
|
17
|
+
*/
|
|
18
|
+
export declare function applyLocale(definition: AssessmentDefinition, pack: InventoryLocalePack): AssessmentDefinition;
|
|
19
|
+
/**
|
|
20
|
+
* Returns a copy of a definition containing only the given locales in every
|
|
21
|
+
* localized text (questions, options, bands, flags, subscales). The
|
|
22
|
+
* definition's `defaultLocale` is always kept as the fallback.
|
|
23
|
+
*
|
|
24
|
+
* Use this at the server boundary to avoid shipping unused languages to a
|
|
25
|
+
* client: `res.json(pickLocales(phq9, [userLocale]))`. The original
|
|
26
|
+
* definition is not modified.
|
|
27
|
+
*/
|
|
28
|
+
export declare function pickLocales(definition: AssessmentDefinition, locales: string[]): AssessmentDefinition;
|
|
9
29
|
/** Collects the union of locales present in a set of localized texts. */
|
|
10
30
|
export declare function collectLocales(texts: Array<LocalizedText | undefined>): string[];
|
package/dist/cjs/i18n.js
CHANGED
|
@@ -1,14 +1,17 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.
|
|
3
|
+
exports.localizeText = localizeText;
|
|
4
|
+
exports.applyLocale = applyLocale;
|
|
5
|
+
exports.pickLocales = pickLocales;
|
|
4
6
|
exports.collectLocales = collectLocales;
|
|
7
|
+
const errors_ts_1 = require("./errors.js");
|
|
5
8
|
/**
|
|
6
9
|
* Resolves a `LocalizedText` to a string for the given locale.
|
|
7
10
|
*
|
|
8
11
|
* Resolution order: exact locale -> base language of the locale
|
|
9
12
|
* (`"de-AT"` -> `"de"`) -> `fallbackLocale` -> first available entry.
|
|
10
13
|
*/
|
|
11
|
-
function
|
|
14
|
+
function localizeText(text, locale, fallbackLocale) {
|
|
12
15
|
const exact = text[locale];
|
|
13
16
|
if (exact !== undefined)
|
|
14
17
|
return exact;
|
|
@@ -22,6 +25,139 @@ function localize(text, locale, fallbackLocale) {
|
|
|
22
25
|
const first = Object.values(text)[0];
|
|
23
26
|
return first ?? "";
|
|
24
27
|
}
|
|
28
|
+
/**
|
|
29
|
+
* Merges a locale pack into a definition, returning a new definition that
|
|
30
|
+
* additionally carries the pack's language in every localized text. The
|
|
31
|
+
* original definition and the pack are not modified.
|
|
32
|
+
*
|
|
33
|
+
* Packs may be partial (untranslated entries keep their existing locales),
|
|
34
|
+
* but entries referencing unknown question/band/flag/subscale ids or
|
|
35
|
+
* mismatched option counts throw `invalid_argument`.
|
|
36
|
+
*/
|
|
37
|
+
function applyLocale(definition, pack) {
|
|
38
|
+
if (pack.id !== definition.id) {
|
|
39
|
+
throw new errors_ts_1.PsytoolsError("invalid_argument", `Locale pack "${pack.id}" (${pack.locale}) does not belong to assessment "${definition.id}"`);
|
|
40
|
+
}
|
|
41
|
+
const set = (text, value) => value === undefined ? text : { ...text, [pack.locale]: value };
|
|
42
|
+
const setOptions = (options, labels, where) => {
|
|
43
|
+
if (!labels)
|
|
44
|
+
return options;
|
|
45
|
+
if (labels.length !== options.length) {
|
|
46
|
+
throw new errors_ts_1.PsytoolsError("invalid_argument", `Locale pack "${pack.id}/${pack.locale}": ${where} has ${labels.length} labels for ${options.length} options`);
|
|
47
|
+
}
|
|
48
|
+
return options.map((option, i) => ({ ...option, label: set(option.label, labels[i]) }));
|
|
49
|
+
};
|
|
50
|
+
const setBands = (bands, packBands) => bands?.map((band) => ({ ...band, label: set(band.label, packBands?.[band.id]) }));
|
|
51
|
+
const setFlags = (flags, packFlags) => flags?.map((flag) => ({ ...flag, label: set(flag.label, packFlags?.[flag.id]) }));
|
|
52
|
+
for (const questionId of Object.keys(pack.questions)) {
|
|
53
|
+
if (!definition.questions.some((q) => q.id === questionId)) {
|
|
54
|
+
throw new errors_ts_1.PsytoolsError("invalid_argument", `Locale pack "${pack.id}/${pack.locale}" references unknown question "${questionId}"`);
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
let scoring;
|
|
58
|
+
if (definition.scoring) {
|
|
59
|
+
const s = definition.scoring;
|
|
60
|
+
if (s.kind === "subscales") {
|
|
61
|
+
scoring = {
|
|
62
|
+
...s,
|
|
63
|
+
subscales: s.subscales.map((subscale) => {
|
|
64
|
+
const entry = pack.subscales?.[subscale.id];
|
|
65
|
+
return {
|
|
66
|
+
...subscale,
|
|
67
|
+
label: set(subscale.label, entry?.label),
|
|
68
|
+
...(subscale.bands ? { bands: setBands(subscale.bands, entry?.bands) } : {}),
|
|
69
|
+
};
|
|
70
|
+
}),
|
|
71
|
+
...(s.flags ? { flags: setFlags(s.flags, pack.flags) } : {}),
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
else {
|
|
75
|
+
scoring = {
|
|
76
|
+
...s,
|
|
77
|
+
...(s.bands ? { bands: setBands(s.bands, pack.bands) } : {}),
|
|
78
|
+
...(s.flags ? { flags: setFlags(s.flags, pack.flags) } : {}),
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
return {
|
|
83
|
+
...definition,
|
|
84
|
+
title: set(definition.title, pack.title),
|
|
85
|
+
...(definition.description ? { description: set(definition.description, pack.description) } : {}),
|
|
86
|
+
...(definition.instructions ? { instructions: set(definition.instructions, pack.instructions) } : {}),
|
|
87
|
+
options: setOptions(definition.options, pack.options, "options"),
|
|
88
|
+
questions: definition.questions.map((question) => {
|
|
89
|
+
const entry = pack.questions[question.id];
|
|
90
|
+
if (!entry)
|
|
91
|
+
return question;
|
|
92
|
+
return {
|
|
93
|
+
...question,
|
|
94
|
+
text: set(question.text, entry.text),
|
|
95
|
+
...(question.options
|
|
96
|
+
? { options: setOptions(question.options, entry.options, `question "${question.id}"`) }
|
|
97
|
+
: {}),
|
|
98
|
+
};
|
|
99
|
+
}),
|
|
100
|
+
...(scoring ? { scoring } : {}),
|
|
101
|
+
};
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* Returns a copy of a definition containing only the given locales in every
|
|
105
|
+
* localized text (questions, options, bands, flags, subscales). The
|
|
106
|
+
* definition's `defaultLocale` is always kept as the fallback.
|
|
107
|
+
*
|
|
108
|
+
* Use this at the server boundary to avoid shipping unused languages to a
|
|
109
|
+
* client: `res.json(pickLocales(phq9, [userLocale]))`. The original
|
|
110
|
+
* definition is not modified.
|
|
111
|
+
*/
|
|
112
|
+
function pickLocales(definition, locales) {
|
|
113
|
+
const keep = new Set([...locales, definition.defaultLocale]);
|
|
114
|
+
const pick = (text) => {
|
|
115
|
+
const out = {};
|
|
116
|
+
for (const [locale, value] of Object.entries(text)) {
|
|
117
|
+
if (keep.has(locale))
|
|
118
|
+
out[locale] = value;
|
|
119
|
+
}
|
|
120
|
+
return out;
|
|
121
|
+
};
|
|
122
|
+
const pickOptions = (options) => options.map((option) => ({ ...option, label: pick(option.label) }));
|
|
123
|
+
const pickBands = (bands) => bands.map((band) => ({ ...band, label: pick(band.label) }));
|
|
124
|
+
const pickFlags = (flags) => flags.map((flag) => ({ ...flag, label: pick(flag.label) }));
|
|
125
|
+
let scoring;
|
|
126
|
+
if (definition.scoring) {
|
|
127
|
+
const s = definition.scoring;
|
|
128
|
+
if (s.kind === "subscales") {
|
|
129
|
+
scoring = {
|
|
130
|
+
...s,
|
|
131
|
+
subscales: s.subscales.map((subscale) => ({
|
|
132
|
+
...subscale,
|
|
133
|
+
label: pick(subscale.label),
|
|
134
|
+
...(subscale.bands ? { bands: pickBands(subscale.bands) } : {}),
|
|
135
|
+
})),
|
|
136
|
+
...(s.flags ? { flags: pickFlags(s.flags) } : {}),
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
else {
|
|
140
|
+
scoring = {
|
|
141
|
+
...s,
|
|
142
|
+
...(s.bands ? { bands: pickBands(s.bands) } : {}),
|
|
143
|
+
...(s.flags ? { flags: pickFlags(s.flags) } : {}),
|
|
144
|
+
};
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
return {
|
|
148
|
+
...definition,
|
|
149
|
+
title: pick(definition.title),
|
|
150
|
+
...(definition.description ? { description: pick(definition.description) } : {}),
|
|
151
|
+
...(definition.instructions ? { instructions: pick(definition.instructions) } : {}),
|
|
152
|
+
options: pickOptions(definition.options),
|
|
153
|
+
questions: definition.questions.map((question) => ({
|
|
154
|
+
...question,
|
|
155
|
+
text: pick(question.text),
|
|
156
|
+
...(question.options ? { options: pickOptions(question.options) } : {}),
|
|
157
|
+
})),
|
|
158
|
+
...(scoring ? { scoring } : {}),
|
|
159
|
+
};
|
|
160
|
+
}
|
|
25
161
|
/** Collects the union of locales present in a set of localized texts. */
|
|
26
162
|
function collectLocales(texts) {
|
|
27
163
|
const locales = new Set();
|
package/dist/cjs/index.d.ts
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
|
-
export type { LocalizedText, AssessmentOption, AssessmentQuestion, AssessmentDefinition, ScoreBand, ScoreFlag, SumScoring, SubscaleDefinition, SubscaleScoring, CountScoringItem, CountScoring, ScoringDefinition, AnswerMap, ResponseStatus, ResponseData, ValidationIssue, ValidationResult, BandResult, TriggeredFlag, ScaleScore, ScaleResult, MultiScaleResult, CategoricalResult, CustomResult, EvaluationResult, Evaluator, LocalizedAssessmentView, } from "./types.ts";
|
|
1
|
+
export type { LocalizedText, AssessmentOption, AssessmentQuestion, AssessmentDefinition, ScoreBand, ScoreFlag, SumScoring, SubscaleDefinition, SubscaleScoring, CountScoringItem, CountScoring, MissingDataPolicy, MissingDataStrategy, ScoringDefinition, ValidationIssueCode, AnswerMap, InventoryLocalePack, ResponseStatus, ResponseData, ValidationIssue, ValidationResult, BandResult, TriggeredFlag, ScaleScore, ScaleResult, MultiScaleResult, CategoricalResult, CustomResult, EvaluationResult, Evaluator, LocalizedAssessmentView, } from "./types.ts";
|
|
2
2
|
export { PsytoolsError } from "./errors.ts";
|
|
3
|
-
export {
|
|
3
|
+
export type { PsytoolsErrorCode } from "./errors.ts";
|
|
4
|
+
export { localizeText, collectLocales, pickLocales, applyLocale } from "./i18n.ts";
|
|
5
|
+
export { localePacks, availableLocales } from "./locales/index.ts";
|
|
6
|
+
export type { LocalePackLoader } from "./locales/index.ts";
|
|
4
7
|
export { Assessment, validateDefinition } from "./assessment.ts";
|
|
5
8
|
export { AssessmentResponse } from "./response.ts";
|
|
6
9
|
export { evaluate } from "./evaluation.ts";
|
|
10
|
+
export type { EvaluateOptions } from "./evaluation.ts";
|
|
7
11
|
export { phq9, gad7, dass21, who5, asrs6, aq10, audit, miniIpip, inventories, loadInventory, twoWeekFrequencyOptions, twoWeekInstructions, } from "./inventories/index.ts";
|
|
8
12
|
export type { InventoryId } from "./inventories/index.ts";
|