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/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "psytools",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "Zero-dependency toolkit for psychological assessments: data models, response validation, scoring, and predefined inventories (PHQ-9, GAD-7, DASS-21, WHO-5, ASRS, AQ-10, AUDIT, Mini-IPIP) in multiple languages.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"psychology",
|
|
@@ -48,6 +48,26 @@
|
|
|
48
48
|
"default": "./dist/cjs/index.js"
|
|
49
49
|
}
|
|
50
50
|
},
|
|
51
|
+
"./locales/*": {
|
|
52
|
+
"import": {
|
|
53
|
+
"types": "./dist/esm/locales/*.d.ts",
|
|
54
|
+
"default": "./dist/esm/locales/*.js"
|
|
55
|
+
},
|
|
56
|
+
"require": {
|
|
57
|
+
"types": "./dist/cjs/locales/*.d.ts",
|
|
58
|
+
"default": "./dist/cjs/locales/*.js"
|
|
59
|
+
}
|
|
60
|
+
},
|
|
61
|
+
"./inventories/*": {
|
|
62
|
+
"import": {
|
|
63
|
+
"types": "./dist/esm/inventories/*.d.ts",
|
|
64
|
+
"default": "./dist/esm/inventories/*.js"
|
|
65
|
+
},
|
|
66
|
+
"require": {
|
|
67
|
+
"types": "./dist/cjs/inventories/*.d.ts",
|
|
68
|
+
"default": "./dist/cjs/inventories/*.js"
|
|
69
|
+
}
|
|
70
|
+
},
|
|
51
71
|
"./package.json": "./package.json"
|
|
52
72
|
},
|
|
53
73
|
"files": [
|
|
@@ -86,6 +86,15 @@
|
|
|
86
86
|
"label": { "$ref": "#/$defs/localizedText" }
|
|
87
87
|
}
|
|
88
88
|
},
|
|
89
|
+
"missingDataPolicy": {
|
|
90
|
+
"type": "object",
|
|
91
|
+
"required": ["strategy"],
|
|
92
|
+
"additionalProperties": false,
|
|
93
|
+
"properties": {
|
|
94
|
+
"strategy": { "enum": ["ignore", "prorate", "require-complete"] },
|
|
95
|
+
"minAnswered": { "type": "number" }
|
|
96
|
+
}
|
|
97
|
+
},
|
|
89
98
|
"sumScoring": {
|
|
90
99
|
"type": "object",
|
|
91
100
|
"required": ["kind"],
|
|
@@ -94,7 +103,8 @@
|
|
|
94
103
|
"kind": { "const": "sum" },
|
|
95
104
|
"multiplier": { "type": "number" },
|
|
96
105
|
"bands": { "type": "array", "items": { "$ref": "#/$defs/scoreBand" } },
|
|
97
|
-
"flags": { "type": "array", "items": { "$ref": "#/$defs/scoreFlag" } }
|
|
106
|
+
"flags": { "type": "array", "items": { "$ref": "#/$defs/scoreFlag" } },
|
|
107
|
+
"missing": { "$ref": "#/$defs/missingDataPolicy" }
|
|
98
108
|
}
|
|
99
109
|
},
|
|
100
110
|
"subscale": {
|
|
@@ -134,7 +144,8 @@
|
|
|
134
144
|
"items": { "$ref": "#/$defs/countScoringItem" }
|
|
135
145
|
},
|
|
136
146
|
"bands": { "type": "array", "items": { "$ref": "#/$defs/scoreBand" } },
|
|
137
|
-
"flags": { "type": "array", "items": { "$ref": "#/$defs/scoreFlag" } }
|
|
147
|
+
"flags": { "type": "array", "items": { "$ref": "#/$defs/scoreFlag" } },
|
|
148
|
+
"missing": { "$ref": "#/$defs/missingDataPolicy" }
|
|
138
149
|
}
|
|
139
150
|
},
|
|
140
151
|
"subscaleScoring": {
|
|
@@ -148,7 +159,8 @@
|
|
|
148
159
|
"minItems": 1,
|
|
149
160
|
"items": { "$ref": "#/$defs/subscale" }
|
|
150
161
|
},
|
|
151
|
-
"flags": { "type": "array", "items": { "$ref": "#/$defs/scoreFlag" } }
|
|
162
|
+
"flags": { "type": "array", "items": { "$ref": "#/$defs/scoreFlag" } },
|
|
163
|
+
"missing": { "$ref": "#/$defs/missingDataPolicy" }
|
|
152
164
|
}
|
|
153
165
|
}
|
|
154
166
|
}
|
package/src/assessment.ts
CHANGED
|
@@ -9,9 +9,9 @@ import type {
|
|
|
9
9
|
ValidationResult,
|
|
10
10
|
} from "./types.ts";
|
|
11
11
|
import { PsytoolsError } from "./errors.ts";
|
|
12
|
-
import { collectLocales,
|
|
12
|
+
import { collectLocales, localizeText } from "./i18n.ts";
|
|
13
13
|
import { AssessmentResponse } from "./response.ts";
|
|
14
|
-
import { evaluate } from "./evaluation.ts";
|
|
14
|
+
import { evaluate, type EvaluateOptions } from "./evaluation.ts";
|
|
15
15
|
|
|
16
16
|
/**
|
|
17
17
|
* Structurally validates an assessment definition (useful before persisting
|
|
@@ -216,20 +216,26 @@ export class Assessment {
|
|
|
216
216
|
|
|
217
217
|
/**
|
|
218
218
|
* Evaluates a response (or raw answers) with the definition's declarative
|
|
219
|
-
* scoring, or with `evaluator` when provided.
|
|
219
|
+
* scoring, or with `options.evaluator` when provided.
|
|
220
220
|
*
|
|
221
221
|
* When given an `AssessmentResponse`, its status must be `complete` or
|
|
222
222
|
* `submitted` — pass `allowIncomplete` to score partial responses anyway.
|
|
223
223
|
* Raw answer maps skip the completeness check, but their values are
|
|
224
|
-
* still validated against the option scales
|
|
224
|
+
* still validated against the option scales, and the scoring definition's
|
|
225
|
+
* missing-data policy still applies.
|
|
225
226
|
*
|
|
226
227
|
* @throws PsytoolsError `incomplete_response` | `unknown_question` | `invalid_value` | `no_scoring`
|
|
227
228
|
*/
|
|
228
229
|
evaluate(
|
|
229
230
|
response: AssessmentResponse | Record<string, number>,
|
|
230
|
-
|
|
231
|
-
options?: { allowIncomplete?: boolean },
|
|
231
|
+
options?: EvaluateOptions & { allowIncomplete?: boolean },
|
|
232
232
|
): EvaluationResult {
|
|
233
|
+
if (typeof options === "function") {
|
|
234
|
+
throw new PsytoolsError(
|
|
235
|
+
"invalid_argument",
|
|
236
|
+
"Pass the evaluator as an option: assessment.evaluate(response, { evaluator })",
|
|
237
|
+
);
|
|
238
|
+
}
|
|
233
239
|
if (response instanceof AssessmentResponse) {
|
|
234
240
|
const scorable = response.status === "complete" || response.status === "submitted";
|
|
235
241
|
if (!scorable && !options?.allowIncomplete) {
|
|
@@ -240,9 +246,9 @@ export class Assessment {
|
|
|
240
246
|
"pass { allowIncomplete: true } to score it anyway",
|
|
241
247
|
);
|
|
242
248
|
}
|
|
243
|
-
return evaluate(this.definition, response.answers, evaluator);
|
|
249
|
+
return evaluate(this.definition, response.answers, { evaluator: options?.evaluator });
|
|
244
250
|
}
|
|
245
|
-
return evaluate(this.definition, response, evaluator);
|
|
251
|
+
return evaluate(this.definition, response, { evaluator: options?.evaluator });
|
|
246
252
|
}
|
|
247
253
|
|
|
248
254
|
/** The plain serializable definition (used by `JSON.stringify`). */
|
|
@@ -272,6 +278,6 @@ export class Assessment {
|
|
|
272
278
|
}
|
|
273
279
|
|
|
274
280
|
private text(text: Record<string, string>, locale?: string): string {
|
|
275
|
-
return
|
|
281
|
+
return localizeText(text, locale ?? this.definition.defaultLocale, this.definition.defaultLocale);
|
|
276
282
|
}
|
|
277
283
|
}
|
package/src/errors.ts
CHANGED
|
@@ -1,8 +1,32 @@
|
|
|
1
|
+
/** Every error code psytools can throw, for exhaustive handling. */
|
|
2
|
+
export type PsytoolsErrorCode =
|
|
3
|
+
// definition problems
|
|
4
|
+
| "malformed"
|
|
5
|
+
| "duplicate_question"
|
|
6
|
+
| "invalid_definition"
|
|
7
|
+
// answer problems
|
|
8
|
+
| "unknown_question"
|
|
9
|
+
| "invalid_value"
|
|
10
|
+
| "missing_answer"
|
|
11
|
+
// response lifecycle
|
|
12
|
+
| "already_submitted"
|
|
13
|
+
| "invalid_response"
|
|
14
|
+
| "incomplete_response"
|
|
15
|
+
| "assessment_mismatch"
|
|
16
|
+
// evaluation
|
|
17
|
+
| "no_scoring"
|
|
18
|
+
// serialization & lookup
|
|
19
|
+
| "invalid_json"
|
|
20
|
+
| "unknown_inventory"
|
|
21
|
+
| "unknown_locale"
|
|
22
|
+
// API misuse
|
|
23
|
+
| "invalid_argument";
|
|
24
|
+
|
|
1
25
|
/** Error thrown by psytools, carrying a stable machine-readable code. */
|
|
2
26
|
export class PsytoolsError extends Error {
|
|
3
|
-
readonly code:
|
|
27
|
+
readonly code: PsytoolsErrorCode;
|
|
4
28
|
|
|
5
|
-
constructor(code:
|
|
29
|
+
constructor(code: PsytoolsErrorCode, message: string) {
|
|
6
30
|
super(message);
|
|
7
31
|
this.name = "PsytoolsError";
|
|
8
32
|
this.code = code;
|
package/src/evaluation.ts
CHANGED
|
@@ -5,6 +5,7 @@ import type {
|
|
|
5
5
|
BandResult,
|
|
6
6
|
EvaluationResult,
|
|
7
7
|
Evaluator,
|
|
8
|
+
MissingDataPolicy,
|
|
8
9
|
MultiScaleResult,
|
|
9
10
|
ScaleResult,
|
|
10
11
|
ScoreBand,
|
|
@@ -14,23 +15,35 @@ import type {
|
|
|
14
15
|
} from "./types.ts";
|
|
15
16
|
import { PsytoolsError } from "./errors.ts";
|
|
16
17
|
|
|
18
|
+
export interface EvaluateOptions {
|
|
19
|
+
/** Custom evaluator used instead of the definition's declarative scoring. */
|
|
20
|
+
evaluator?: Evaluator;
|
|
21
|
+
}
|
|
22
|
+
|
|
17
23
|
/**
|
|
18
24
|
* Evaluates answers against an assessment definition.
|
|
19
25
|
*
|
|
20
26
|
* Every answer is first validated against the assessment: the question must
|
|
21
|
-
* exist and the value must belong to its option scale. Then
|
|
22
|
-
* used when given; otherwise the definition's
|
|
23
|
-
* (`sum` or `
|
|
27
|
+
* exist and the value must belong to its option scale. Then
|
|
28
|
+
* `options.evaluator` is used when given; otherwise the definition's
|
|
29
|
+
* declarative `scoring` (`sum`, `subscales`, or `count`) applies, honoring
|
|
30
|
+
* its missing-data policy.
|
|
24
31
|
*
|
|
25
|
-
* @throws PsytoolsError `unknown_question` | `invalid_value` | `no_scoring`
|
|
32
|
+
* @throws PsytoolsError `unknown_question` | `invalid_value` | `incomplete_response` | `no_scoring`
|
|
26
33
|
*/
|
|
27
34
|
export function evaluate(
|
|
28
35
|
definition: AssessmentDefinition,
|
|
29
36
|
answers: AnswerMap,
|
|
30
|
-
|
|
37
|
+
options?: EvaluateOptions,
|
|
31
38
|
): EvaluationResult {
|
|
39
|
+
if (typeof options === "function") {
|
|
40
|
+
throw new PsytoolsError(
|
|
41
|
+
"invalid_argument",
|
|
42
|
+
"Pass the evaluator as an option: evaluate(definition, answers, { evaluator })",
|
|
43
|
+
);
|
|
44
|
+
}
|
|
32
45
|
assertValidAnswers(definition, answers);
|
|
33
|
-
if (evaluator) return evaluator(definition, answers);
|
|
46
|
+
if (options?.evaluator) return options.evaluator(definition, answers);
|
|
34
47
|
|
|
35
48
|
const scoring = definition.scoring;
|
|
36
49
|
if (!scoring) {
|
|
@@ -43,17 +56,20 @@ export function evaluate(
|
|
|
43
56
|
case "sum":
|
|
44
57
|
return evaluateSum(definition, answers, scoring);
|
|
45
58
|
case "count": {
|
|
46
|
-
|
|
59
|
+
const questions = scoring.items.map((item) => requireQuestion(definition, item.questionId));
|
|
60
|
+
const answered = enforceMissing(questions, answers, scoring.missing);
|
|
61
|
+
let positives = 0;
|
|
47
62
|
for (const item of scoring.items) {
|
|
48
63
|
const question = requireQuestion(definition, item.questionId);
|
|
49
|
-
const
|
|
50
|
-
if (
|
|
64
|
+
const value = answers[question.id];
|
|
65
|
+
if (value === undefined) continue;
|
|
51
66
|
const values = (question.options ?? definition.options).map((o) => o.value);
|
|
52
67
|
const effective = question.reverseScored
|
|
53
|
-
? Math.max(...values) + Math.min(...values) -
|
|
54
|
-
:
|
|
55
|
-
if (effective >= item.minValue)
|
|
68
|
+
? Math.max(...values) + Math.min(...values) - value
|
|
69
|
+
: value;
|
|
70
|
+
if (effective >= item.minValue) positives += 1;
|
|
56
71
|
}
|
|
72
|
+
const score = prorate(positives, answered, questions.length, scoring.missing);
|
|
57
73
|
return {
|
|
58
74
|
kind: "scale",
|
|
59
75
|
score,
|
|
@@ -66,15 +82,12 @@ export function evaluate(
|
|
|
66
82
|
case "subscales": {
|
|
67
83
|
const scales: MultiScaleResult["scales"] = scoring.subscales.map((subscale) => {
|
|
68
84
|
const questions = subscale.questionIds.map((id) => requireQuestion(definition, id));
|
|
69
|
-
const
|
|
70
|
-
const { score, min, max } = sumQuestions(definition, questions, answers, multiplier);
|
|
85
|
+
const scored = scoreQuestionSet(definition, questions, answers, subscale.multiplier ?? 1, scoring.missing, subscale.id);
|
|
71
86
|
return {
|
|
72
87
|
id: subscale.id,
|
|
73
88
|
label: subscale.label,
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
max,
|
|
77
|
-
...bandOf(score, subscale.bands),
|
|
89
|
+
...scored,
|
|
90
|
+
...bandOf(scored.score, subscale.bands),
|
|
78
91
|
};
|
|
79
92
|
});
|
|
80
93
|
return {
|
|
@@ -117,25 +130,36 @@ function evaluateSum(
|
|
|
117
130
|
answers: AnswerMap,
|
|
118
131
|
scoring: SumScoring,
|
|
119
132
|
): ScaleResult {
|
|
120
|
-
const
|
|
121
|
-
|
|
133
|
+
const result = scoreQuestionSet(
|
|
134
|
+
definition,
|
|
135
|
+
definition.questions,
|
|
136
|
+
answers,
|
|
137
|
+
scoring.multiplier ?? 1,
|
|
138
|
+
scoring.missing,
|
|
139
|
+
);
|
|
122
140
|
return {
|
|
123
141
|
kind: "scale",
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
max,
|
|
127
|
-
...bandOf(score, scoring.bands),
|
|
142
|
+
...result,
|
|
143
|
+
...bandOf(result.score, scoring.bands),
|
|
128
144
|
flags: triggeredFlags(answers, scoring.flags),
|
|
129
145
|
};
|
|
130
146
|
}
|
|
131
147
|
|
|
132
|
-
|
|
148
|
+
/**
|
|
149
|
+
* Sums one set of questions (the whole assessment or one subscale),
|
|
150
|
+
* applying reverse scoring, the missing-data policy, and the multiplier.
|
|
151
|
+
*/
|
|
152
|
+
function scoreQuestionSet(
|
|
133
153
|
definition: AssessmentDefinition,
|
|
134
154
|
questions: readonly AssessmentQuestion[],
|
|
135
155
|
answers: AnswerMap,
|
|
136
156
|
multiplier: number,
|
|
157
|
+
missing: MissingDataPolicy | undefined,
|
|
158
|
+
scaleId?: string,
|
|
137
159
|
): { score: number; min: number; max: number } {
|
|
138
|
-
|
|
160
|
+
const answered = enforceMissing(questions, answers, missing, scaleId);
|
|
161
|
+
|
|
162
|
+
let raw = 0;
|
|
139
163
|
let min = 0;
|
|
140
164
|
let max = 0;
|
|
141
165
|
for (const question of questions) {
|
|
@@ -145,11 +169,60 @@ function sumQuestions(
|
|
|
145
169
|
min += lowest;
|
|
146
170
|
max += highest;
|
|
147
171
|
|
|
148
|
-
const
|
|
149
|
-
if (
|
|
150
|
-
|
|
172
|
+
const value = answers[question.id];
|
|
173
|
+
if (value === undefined) continue;
|
|
174
|
+
raw += question.reverseScored ? highest + lowest - value : value;
|
|
151
175
|
}
|
|
152
|
-
|
|
176
|
+
raw = prorate(raw, answered, questions.length, missing);
|
|
177
|
+
return { score: raw * multiplier, min: min * multiplier, max: max * multiplier };
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* Enforces the missing-data policy over one set of contributing questions
|
|
182
|
+
* and returns how many of them are answered.
|
|
183
|
+
*
|
|
184
|
+
* `require-complete` only demands questions that are not marked `optional`.
|
|
185
|
+
*/
|
|
186
|
+
function enforceMissing(
|
|
187
|
+
questions: readonly AssessmentQuestion[],
|
|
188
|
+
answers: AnswerMap,
|
|
189
|
+
missing: MissingDataPolicy | undefined,
|
|
190
|
+
scaleId?: string,
|
|
191
|
+
): number {
|
|
192
|
+
const strategy = missing?.strategy ?? "ignore";
|
|
193
|
+
const minAnswered = missing?.minAnswered ?? (strategy === "prorate" ? 1 : 0);
|
|
194
|
+
const scope = scaleId ? ` in subscale "${scaleId}"` : "";
|
|
195
|
+
|
|
196
|
+
const answered = questions.filter((q) => answers[q.id] !== undefined).length;
|
|
197
|
+
if (strategy === "require-complete") {
|
|
198
|
+
const unanswered = questions
|
|
199
|
+
.filter((q) => !(q.optional ?? false) && answers[q.id] === undefined)
|
|
200
|
+
.map((q) => q.id);
|
|
201
|
+
if (unanswered.length > 0) {
|
|
202
|
+
throw new PsytoolsError(
|
|
203
|
+
"incomplete_response",
|
|
204
|
+
`Scoring requires complete answers${scope}; unanswered: ${unanswered.join(", ")}`,
|
|
205
|
+
);
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
if (answered < minAnswered) {
|
|
209
|
+
throw new PsytoolsError(
|
|
210
|
+
"incomplete_response",
|
|
211
|
+
`Scoring requires at least ${minAnswered} answered item(s)${scope}, got ${answered}`,
|
|
212
|
+
);
|
|
213
|
+
}
|
|
214
|
+
return answered;
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/** Scales a partial raw score up to the full item count (rounded). */
|
|
218
|
+
function prorate(
|
|
219
|
+
raw: number,
|
|
220
|
+
answered: number,
|
|
221
|
+
total: number,
|
|
222
|
+
missing: MissingDataPolicy | undefined,
|
|
223
|
+
): number {
|
|
224
|
+
if (missing?.strategy !== "prorate" || answered === 0 || answered === total) return raw;
|
|
225
|
+
return Math.round((raw * total) / answered);
|
|
153
226
|
}
|
|
154
227
|
|
|
155
228
|
function bandOf(score: number, bands?: ScoreBand[]): { band?: BandResult } {
|
package/src/i18n.ts
CHANGED
|
@@ -1,4 +1,13 @@
|
|
|
1
|
-
import type {
|
|
1
|
+
import type {
|
|
2
|
+
AssessmentDefinition,
|
|
3
|
+
AssessmentOption,
|
|
4
|
+
InventoryLocalePack,
|
|
5
|
+
LocalizedText,
|
|
6
|
+
ScoreBand,
|
|
7
|
+
ScoreFlag,
|
|
8
|
+
ScoringDefinition,
|
|
9
|
+
} from "./types.ts";
|
|
10
|
+
import { PsytoolsError } from "./errors.ts";
|
|
2
11
|
|
|
3
12
|
/**
|
|
4
13
|
* Resolves a `LocalizedText` to a string for the given locale.
|
|
@@ -6,7 +15,7 @@ import type { LocalizedText } from "./types.ts";
|
|
|
6
15
|
* Resolution order: exact locale -> base language of the locale
|
|
7
16
|
* (`"de-AT"` -> `"de"`) -> `fallbackLocale` -> first available entry.
|
|
8
17
|
*/
|
|
9
|
-
export function
|
|
18
|
+
export function localizeText(
|
|
10
19
|
text: LocalizedText,
|
|
11
20
|
locale: string,
|
|
12
21
|
fallbackLocale?: string,
|
|
@@ -27,6 +36,172 @@ export function localize(
|
|
|
27
36
|
return first ?? "";
|
|
28
37
|
}
|
|
29
38
|
|
|
39
|
+
/**
|
|
40
|
+
* Merges a locale pack into a definition, returning a new definition that
|
|
41
|
+
* additionally carries the pack's language in every localized text. The
|
|
42
|
+
* original definition and the pack are not modified.
|
|
43
|
+
*
|
|
44
|
+
* Packs may be partial (untranslated entries keep their existing locales),
|
|
45
|
+
* but entries referencing unknown question/band/flag/subscale ids or
|
|
46
|
+
* mismatched option counts throw `invalid_argument`.
|
|
47
|
+
*/
|
|
48
|
+
export function applyLocale(
|
|
49
|
+
definition: AssessmentDefinition,
|
|
50
|
+
pack: InventoryLocalePack,
|
|
51
|
+
): AssessmentDefinition {
|
|
52
|
+
if (pack.id !== definition.id) {
|
|
53
|
+
throw new PsytoolsError(
|
|
54
|
+
"invalid_argument",
|
|
55
|
+
`Locale pack "${pack.id}" (${pack.locale}) does not belong to assessment "${definition.id}"`,
|
|
56
|
+
);
|
|
57
|
+
}
|
|
58
|
+
const set = (text: LocalizedText, value: string | undefined): LocalizedText =>
|
|
59
|
+
value === undefined ? text : { ...text, [pack.locale]: value };
|
|
60
|
+
const setOptions = (
|
|
61
|
+
options: AssessmentOption[],
|
|
62
|
+
labels: string[] | undefined,
|
|
63
|
+
where: string,
|
|
64
|
+
): AssessmentOption[] => {
|
|
65
|
+
if (!labels) return options;
|
|
66
|
+
if (labels.length !== options.length) {
|
|
67
|
+
throw new PsytoolsError(
|
|
68
|
+
"invalid_argument",
|
|
69
|
+
`Locale pack "${pack.id}/${pack.locale}": ${where} has ${labels.length} labels for ${options.length} options`,
|
|
70
|
+
);
|
|
71
|
+
}
|
|
72
|
+
return options.map((option, i) => ({ ...option, label: set(option.label, labels[i]) }));
|
|
73
|
+
};
|
|
74
|
+
const setBands = (
|
|
75
|
+
bands: ScoreBand[] | undefined,
|
|
76
|
+
packBands: Record<string, string> | undefined,
|
|
77
|
+
): ScoreBand[] | undefined =>
|
|
78
|
+
bands?.map((band) => ({ ...band, label: set(band.label, packBands?.[band.id]) }));
|
|
79
|
+
const setFlags = (
|
|
80
|
+
flags: ScoreFlag[] | undefined,
|
|
81
|
+
packFlags: Record<string, string> | undefined,
|
|
82
|
+
): ScoreFlag[] | undefined =>
|
|
83
|
+
flags?.map((flag) => ({ ...flag, label: set(flag.label, packFlags?.[flag.id]) }));
|
|
84
|
+
|
|
85
|
+
for (const questionId of Object.keys(pack.questions)) {
|
|
86
|
+
if (!definition.questions.some((q) => q.id === questionId)) {
|
|
87
|
+
throw new PsytoolsError(
|
|
88
|
+
"invalid_argument",
|
|
89
|
+
`Locale pack "${pack.id}/${pack.locale}" references unknown question "${questionId}"`,
|
|
90
|
+
);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
let scoring: ScoringDefinition | undefined;
|
|
95
|
+
if (definition.scoring) {
|
|
96
|
+
const s = definition.scoring;
|
|
97
|
+
if (s.kind === "subscales") {
|
|
98
|
+
scoring = {
|
|
99
|
+
...s,
|
|
100
|
+
subscales: s.subscales.map((subscale) => {
|
|
101
|
+
const entry = pack.subscales?.[subscale.id];
|
|
102
|
+
return {
|
|
103
|
+
...subscale,
|
|
104
|
+
label: set(subscale.label, entry?.label),
|
|
105
|
+
...(subscale.bands ? { bands: setBands(subscale.bands, entry?.bands) } : {}),
|
|
106
|
+
};
|
|
107
|
+
}),
|
|
108
|
+
...(s.flags ? { flags: setFlags(s.flags, pack.flags) } : {}),
|
|
109
|
+
};
|
|
110
|
+
} else {
|
|
111
|
+
scoring = {
|
|
112
|
+
...s,
|
|
113
|
+
...(s.bands ? { bands: setBands(s.bands, pack.bands) } : {}),
|
|
114
|
+
...(s.flags ? { flags: setFlags(s.flags, pack.flags) } : {}),
|
|
115
|
+
};
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
return {
|
|
120
|
+
...definition,
|
|
121
|
+
title: set(definition.title, pack.title),
|
|
122
|
+
...(definition.description ? { description: set(definition.description, pack.description) } : {}),
|
|
123
|
+
...(definition.instructions ? { instructions: set(definition.instructions, pack.instructions) } : {}),
|
|
124
|
+
options: setOptions(definition.options, pack.options, "options"),
|
|
125
|
+
questions: definition.questions.map((question) => {
|
|
126
|
+
const entry = pack.questions[question.id];
|
|
127
|
+
if (!entry) return question;
|
|
128
|
+
return {
|
|
129
|
+
...question,
|
|
130
|
+
text: set(question.text, entry.text),
|
|
131
|
+
...(question.options
|
|
132
|
+
? { options: setOptions(question.options, entry.options, `question "${question.id}"`) }
|
|
133
|
+
: {}),
|
|
134
|
+
};
|
|
135
|
+
}),
|
|
136
|
+
...(scoring ? { scoring } : {}),
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* Returns a copy of a definition containing only the given locales in every
|
|
142
|
+
* localized text (questions, options, bands, flags, subscales). The
|
|
143
|
+
* definition's `defaultLocale` is always kept as the fallback.
|
|
144
|
+
*
|
|
145
|
+
* Use this at the server boundary to avoid shipping unused languages to a
|
|
146
|
+
* client: `res.json(pickLocales(phq9, [userLocale]))`. The original
|
|
147
|
+
* definition is not modified.
|
|
148
|
+
*/
|
|
149
|
+
export function pickLocales(
|
|
150
|
+
definition: AssessmentDefinition,
|
|
151
|
+
locales: string[],
|
|
152
|
+
): AssessmentDefinition {
|
|
153
|
+
const keep = new Set([...locales, definition.defaultLocale]);
|
|
154
|
+
const pick = (text: LocalizedText): LocalizedText => {
|
|
155
|
+
const out: LocalizedText = {};
|
|
156
|
+
for (const [locale, value] of Object.entries(text)) {
|
|
157
|
+
if (keep.has(locale)) out[locale] = value;
|
|
158
|
+
}
|
|
159
|
+
return out;
|
|
160
|
+
};
|
|
161
|
+
const pickOptions = (options: AssessmentOption[]): AssessmentOption[] =>
|
|
162
|
+
options.map((option) => ({ ...option, label: pick(option.label) }));
|
|
163
|
+
const pickBands = (bands: ScoreBand[]): ScoreBand[] =>
|
|
164
|
+
bands.map((band) => ({ ...band, label: pick(band.label) }));
|
|
165
|
+
const pickFlags = (flags: ScoreFlag[]): ScoreFlag[] =>
|
|
166
|
+
flags.map((flag) => ({ ...flag, label: pick(flag.label) }));
|
|
167
|
+
|
|
168
|
+
let scoring: ScoringDefinition | undefined;
|
|
169
|
+
if (definition.scoring) {
|
|
170
|
+
const s = definition.scoring;
|
|
171
|
+
if (s.kind === "subscales") {
|
|
172
|
+
scoring = {
|
|
173
|
+
...s,
|
|
174
|
+
subscales: s.subscales.map((subscale) => ({
|
|
175
|
+
...subscale,
|
|
176
|
+
label: pick(subscale.label),
|
|
177
|
+
...(subscale.bands ? { bands: pickBands(subscale.bands) } : {}),
|
|
178
|
+
})),
|
|
179
|
+
...(s.flags ? { flags: pickFlags(s.flags) } : {}),
|
|
180
|
+
};
|
|
181
|
+
} else {
|
|
182
|
+
scoring = {
|
|
183
|
+
...s,
|
|
184
|
+
...(s.bands ? { bands: pickBands(s.bands) } : {}),
|
|
185
|
+
...(s.flags ? { flags: pickFlags(s.flags) } : {}),
|
|
186
|
+
};
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
return {
|
|
191
|
+
...definition,
|
|
192
|
+
title: pick(definition.title),
|
|
193
|
+
...(definition.description ? { description: pick(definition.description) } : {}),
|
|
194
|
+
...(definition.instructions ? { instructions: pick(definition.instructions) } : {}),
|
|
195
|
+
options: pickOptions(definition.options),
|
|
196
|
+
questions: definition.questions.map((question) => ({
|
|
197
|
+
...question,
|
|
198
|
+
text: pick(question.text),
|
|
199
|
+
...(question.options ? { options: pickOptions(question.options) } : {}),
|
|
200
|
+
})),
|
|
201
|
+
...(scoring ? { scoring } : {}),
|
|
202
|
+
};
|
|
203
|
+
}
|
|
204
|
+
|
|
30
205
|
/** Collects the union of locales present in a set of localized texts. */
|
|
31
206
|
export function collectLocales(
|
|
32
207
|
texts: Array<LocalizedText | undefined>,
|
package/src/index.ts
CHANGED
|
@@ -10,8 +10,12 @@ export type {
|
|
|
10
10
|
SubscaleScoring,
|
|
11
11
|
CountScoringItem,
|
|
12
12
|
CountScoring,
|
|
13
|
+
MissingDataPolicy,
|
|
14
|
+
MissingDataStrategy,
|
|
13
15
|
ScoringDefinition,
|
|
16
|
+
ValidationIssueCode,
|
|
14
17
|
AnswerMap,
|
|
18
|
+
InventoryLocalePack,
|
|
15
19
|
ResponseStatus,
|
|
16
20
|
ResponseData,
|
|
17
21
|
ValidationIssue,
|
|
@@ -29,10 +33,14 @@ export type {
|
|
|
29
33
|
} from "./types.ts";
|
|
30
34
|
|
|
31
35
|
export { PsytoolsError } from "./errors.ts";
|
|
32
|
-
export {
|
|
36
|
+
export type { PsytoolsErrorCode } from "./errors.ts";
|
|
37
|
+
export { localizeText, collectLocales, pickLocales, applyLocale } from "./i18n.ts";
|
|
38
|
+
export { localePacks, availableLocales } from "./locales/index.ts";
|
|
39
|
+
export type { LocalePackLoader } from "./locales/index.ts";
|
|
33
40
|
export { Assessment, validateDefinition } from "./assessment.ts";
|
|
34
41
|
export { AssessmentResponse } from "./response.ts";
|
|
35
42
|
export { evaluate } from "./evaluation.ts";
|
|
43
|
+
export type { EvaluateOptions } from "./evaluation.ts";
|
|
36
44
|
export {
|
|
37
45
|
phq9,
|
|
38
46
|
gad7,
|