psytools 0.3.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/LICENSE +21 -0
- package/README.md +189 -0
- package/dist/cjs/assessment.d.ts +58 -0
- package/dist/cjs/assessment.js +233 -0
- package/dist/cjs/errors.d.ts +5 -0
- package/dist/cjs/errors.js +13 -0
- package/dist/cjs/evaluation.d.ts +10 -0
- package/dist/cjs/evaluation.js +102 -0
- package/dist/cjs/i18n.d.ts +10 -0
- package/dist/cjs/i18n.js +35 -0
- package/dist/cjs/index.d.ts +8 -0
- package/dist/cjs/index.js +23 -0
- package/dist/cjs/inventories/common.d.ts +8 -0
- package/dist/cjs/inventories/common.js +47 -0
- package/dist/cjs/inventories/dass21.d.ts +11 -0
- package/dist/cjs/inventories/dass21.js +288 -0
- package/dist/cjs/inventories/gad7.d.ts +10 -0
- package/dist/cjs/inventories/gad7.js +121 -0
- package/dist/cjs/inventories/index.d.ts +15 -0
- package/dist/cjs/inventories/index.js +33 -0
- package/dist/cjs/inventories/phq9.d.ts +11 -0
- package/dist/cjs/inventories/phq9.js +156 -0
- package/dist/cjs/package.json +3 -0
- package/dist/cjs/response.d.ts +77 -0
- package/dist/cjs/response.js +231 -0
- package/dist/cjs/types.d.ts +219 -0
- package/dist/cjs/types.js +10 -0
- package/dist/esm/assessment.d.ts +58 -0
- package/dist/esm/assessment.js +228 -0
- package/dist/esm/errors.d.ts +5 -0
- package/dist/esm/errors.js +9 -0
- package/dist/esm/evaluation.d.ts +10 -0
- package/dist/esm/evaluation.js +99 -0
- package/dist/esm/i18n.d.ts +10 -0
- package/dist/esm/i18n.js +31 -0
- package/dist/esm/index.d.ts +8 -0
- package/dist/esm/index.js +6 -0
- package/dist/esm/inventories/common.d.ts +8 -0
- package/dist/esm/inventories/common.js +44 -0
- package/dist/esm/inventories/dass21.d.ts +11 -0
- package/dist/esm/inventories/dass21.js +285 -0
- package/dist/esm/inventories/gad7.d.ts +10 -0
- package/dist/esm/inventories/gad7.js +118 -0
- package/dist/esm/inventories/index.d.ts +15 -0
- package/dist/esm/inventories/index.js +25 -0
- package/dist/esm/inventories/phq9.d.ts +11 -0
- package/dist/esm/inventories/phq9.js +153 -0
- package/dist/esm/response.d.ts +77 -0
- package/dist/esm/response.js +227 -0
- package/dist/esm/types.d.ts +219 -0
- package/dist/esm/types.js +9 -0
- package/package.json +64 -0
- package/schema/assessment-definition.schema.json +129 -0
- package/src/assessment.ts +266 -0
- package/src/errors.ts +10 -0
- package/src/evaluation.ts +140 -0
- package/src/i18n.ts +40 -0
- package/src/index.ts +43 -0
- package/src/inventories/common.ts +47 -0
- package/src/inventories/dass21.ts +291 -0
- package/src/inventories/gad7.ts +121 -0
- package/src/inventories/index.ts +31 -0
- package/src/inventories/phq9.ts +156 -0
- package/src/response.ts +263 -0
- package/src/types.ts +250 -0
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Core data model for psytools.
|
|
4
|
+
*
|
|
5
|
+
* Everything here is plain, JSON-serializable data. Scoring rules are
|
|
6
|
+
* declarative (not functions) so that a full assessment definition survives
|
|
7
|
+
* `JSON.stringify` -> database -> `JSON.parse` round trips without losing
|
|
8
|
+
* behavior.
|
|
9
|
+
*/
|
|
10
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import type { AssessmentDefinition, AssessmentOption, AssessmentQuestion, EvaluationResult, Evaluator, LocalizedAssessmentView, ValidationResult } from "./types.ts";
|
|
2
|
+
import { AssessmentResponse } from "./response.ts";
|
|
3
|
+
/**
|
|
4
|
+
* Structurally validates an assessment definition (useful before persisting
|
|
5
|
+
* user-created assessments). Returns issues instead of throwing.
|
|
6
|
+
*/
|
|
7
|
+
export declare function validateDefinition(input: unknown): ValidationResult;
|
|
8
|
+
/**
|
|
9
|
+
* An assessment: questions plus an enumerated option scale, with helpers for
|
|
10
|
+
* localization, serialization, response creation, and evaluation.
|
|
11
|
+
*/
|
|
12
|
+
export declare class Assessment {
|
|
13
|
+
readonly definition: AssessmentDefinition;
|
|
14
|
+
private readonly questionIndex;
|
|
15
|
+
/** @throws PsytoolsError `invalid_definition` when the definition is malformed. */
|
|
16
|
+
constructor(definition: AssessmentDefinition);
|
|
17
|
+
get id(): string;
|
|
18
|
+
get questions(): readonly AssessmentQuestion[];
|
|
19
|
+
/** Locales for which at least one text of this assessment is available. */
|
|
20
|
+
get locales(): string[];
|
|
21
|
+
question(questionId: string): AssessmentQuestion | undefined;
|
|
22
|
+
/** The option scale that applies to a question (its own or the default). */
|
|
23
|
+
optionsFor(questionId: string): readonly AssessmentOption[];
|
|
24
|
+
title(locale?: string): string;
|
|
25
|
+
/**
|
|
26
|
+
* Flat, render-ready projection in one locale — hand this straight to a
|
|
27
|
+
* frontend to display the questionnaire.
|
|
28
|
+
*/
|
|
29
|
+
localize(locale?: string): LocalizedAssessmentView;
|
|
30
|
+
/** Starts a new (empty) response for this assessment. */
|
|
31
|
+
createResponse(options?: {
|
|
32
|
+
respondentId?: string;
|
|
33
|
+
meta?: Record<string, unknown>;
|
|
34
|
+
}): AssessmentResponse;
|
|
35
|
+
/**
|
|
36
|
+
* Evaluates a response (or raw answers) with the definition's declarative
|
|
37
|
+
* scoring, or with `evaluator` when provided.
|
|
38
|
+
*
|
|
39
|
+
* When given an `AssessmentResponse`, its status must be `complete` or
|
|
40
|
+
* `submitted` — pass `allowIncomplete` to score partial responses anyway.
|
|
41
|
+
* Raw answer maps are scored as-is (low-level escape hatch).
|
|
42
|
+
*
|
|
43
|
+
* @throws PsytoolsError `incomplete_response` | `no_scoring`
|
|
44
|
+
*/
|
|
45
|
+
evaluate(response: AssessmentResponse | Record<string, number>, evaluator?: Evaluator, options?: {
|
|
46
|
+
allowIncomplete?: boolean;
|
|
47
|
+
}): EvaluationResult;
|
|
48
|
+
/** The plain serializable definition (used by `JSON.stringify`). */
|
|
49
|
+
toJSON(): AssessmentDefinition;
|
|
50
|
+
/** Serializes the definition to a JSON string (for DB storage etc.). */
|
|
51
|
+
stringify(space?: number): string;
|
|
52
|
+
/**
|
|
53
|
+
* Parses and validates a definition from a JSON string or plain object.
|
|
54
|
+
* @throws PsytoolsError `invalid_json` | `invalid_definition`
|
|
55
|
+
*/
|
|
56
|
+
static parse(input: string | object): Assessment;
|
|
57
|
+
private text;
|
|
58
|
+
}
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
import { PsytoolsError } from "./errors.js";
|
|
2
|
+
import { collectLocales, localize } from "./i18n.js";
|
|
3
|
+
import { AssessmentResponse } from "./response.js";
|
|
4
|
+
import { evaluate } from "./evaluation.js";
|
|
5
|
+
/**
|
|
6
|
+
* Structurally validates an assessment definition (useful before persisting
|
|
7
|
+
* user-created assessments). Returns issues instead of throwing.
|
|
8
|
+
*/
|
|
9
|
+
export function validateDefinition(input) {
|
|
10
|
+
const issues = [];
|
|
11
|
+
const malformed = (message) => ({
|
|
12
|
+
valid: false,
|
|
13
|
+
issues: [{ code: "malformed", message }],
|
|
14
|
+
});
|
|
15
|
+
if (typeof input !== "object" || input === null || Array.isArray(input)) {
|
|
16
|
+
return malformed("definition must be an object");
|
|
17
|
+
}
|
|
18
|
+
const def = input;
|
|
19
|
+
if (typeof def.id !== "string" || def.id.length === 0) {
|
|
20
|
+
issues.push({ code: "malformed", message: "id must be a non-empty string" });
|
|
21
|
+
}
|
|
22
|
+
if (!isLocalizedText(def.title)) {
|
|
23
|
+
issues.push({ code: "malformed", message: "title must map locales to strings" });
|
|
24
|
+
}
|
|
25
|
+
if (typeof def.defaultLocale !== "string" || def.defaultLocale.length === 0) {
|
|
26
|
+
issues.push({ code: "malformed", message: "defaultLocale must be a non-empty string" });
|
|
27
|
+
}
|
|
28
|
+
if (!Array.isArray(def.options) || def.options.length === 0) {
|
|
29
|
+
issues.push({ code: "malformed", message: "options must be a non-empty array" });
|
|
30
|
+
}
|
|
31
|
+
else {
|
|
32
|
+
def.options.forEach((option, i) => {
|
|
33
|
+
if (!isOption(option)) {
|
|
34
|
+
issues.push({ code: "malformed", message: `options[${i}] must have a numeric value and a localized label` });
|
|
35
|
+
}
|
|
36
|
+
});
|
|
37
|
+
}
|
|
38
|
+
if (!Array.isArray(def.questions) || def.questions.length === 0) {
|
|
39
|
+
issues.push({ code: "malformed", message: "questions must be a non-empty array" });
|
|
40
|
+
}
|
|
41
|
+
else {
|
|
42
|
+
const seen = new Set();
|
|
43
|
+
def.questions.forEach((question, i) => {
|
|
44
|
+
if (typeof question !== "object" || question === null) {
|
|
45
|
+
issues.push({ code: "malformed", message: `questions[${i}] must be an object` });
|
|
46
|
+
return;
|
|
47
|
+
}
|
|
48
|
+
const q = question;
|
|
49
|
+
if (typeof q.id !== "string" || q.id.length === 0) {
|
|
50
|
+
issues.push({ code: "malformed", message: `questions[${i}].id must be a non-empty string` });
|
|
51
|
+
}
|
|
52
|
+
else if (seen.has(q.id)) {
|
|
53
|
+
issues.push({ code: "duplicate_question", message: `duplicate question id "${q.id}"`, questionId: q.id });
|
|
54
|
+
}
|
|
55
|
+
else {
|
|
56
|
+
seen.add(q.id);
|
|
57
|
+
}
|
|
58
|
+
if (!isLocalizedText(q.text)) {
|
|
59
|
+
issues.push({ code: "malformed", message: `questions[${i}].text must map locales to strings`, questionId: typeof q.id === "string" ? q.id : undefined });
|
|
60
|
+
}
|
|
61
|
+
if (q.options !== undefined && (!Array.isArray(q.options) || q.options.length === 0 || !q.options.every(isOption))) {
|
|
62
|
+
issues.push({ code: "malformed", message: `questions[${i}].options, when present, must be a non-empty array of options`, questionId: typeof q.id === "string" ? q.id : undefined });
|
|
63
|
+
}
|
|
64
|
+
});
|
|
65
|
+
if (def.scoring && typeof def.scoring === "object") {
|
|
66
|
+
const scoring = def.scoring;
|
|
67
|
+
if (scoring.kind === "subscales" && Array.isArray(scoring.subscales)) {
|
|
68
|
+
for (const subscale of scoring.subscales) {
|
|
69
|
+
for (const questionId of subscale.questionIds ?? []) {
|
|
70
|
+
if (!seen.has(questionId)) {
|
|
71
|
+
issues.push({ code: "unknown_question", message: `subscale "${subscale.id}" references unknown question "${questionId}"`, questionId });
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
const flags = scoring.kind === "sum" || scoring.kind === "subscales" ? scoring.flags ?? [] : [];
|
|
77
|
+
for (const flag of flags) {
|
|
78
|
+
if (!seen.has(flag.questionId)) {
|
|
79
|
+
issues.push({ code: "unknown_question", message: `flag "${flag.id}" references unknown question "${flag.questionId}"`, questionId: flag.questionId });
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
return { valid: issues.length === 0, issues };
|
|
85
|
+
}
|
|
86
|
+
function isLocalizedText(value) {
|
|
87
|
+
return (typeof value === "object" &&
|
|
88
|
+
value !== null &&
|
|
89
|
+
!Array.isArray(value) &&
|
|
90
|
+
Object.keys(value).length > 0 &&
|
|
91
|
+
Object.values(value).every((entry) => typeof entry === "string"));
|
|
92
|
+
}
|
|
93
|
+
function isOption(value) {
|
|
94
|
+
return (typeof value === "object" &&
|
|
95
|
+
value !== null &&
|
|
96
|
+
typeof value.value === "number" &&
|
|
97
|
+
Number.isFinite(value.value) &&
|
|
98
|
+
isLocalizedText(value.label));
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* An assessment: questions plus an enumerated option scale, with helpers for
|
|
102
|
+
* localization, serialization, response creation, and evaluation.
|
|
103
|
+
*/
|
|
104
|
+
export class Assessment {
|
|
105
|
+
definition;
|
|
106
|
+
questionIndex;
|
|
107
|
+
/** @throws PsytoolsError `invalid_definition` when the definition is malformed. */
|
|
108
|
+
constructor(definition) {
|
|
109
|
+
const result = validateDefinition(definition);
|
|
110
|
+
if (!result.valid) {
|
|
111
|
+
const details = result.issues.map((issue) => issue.message).join("; ");
|
|
112
|
+
throw new PsytoolsError("invalid_definition", `Invalid assessment definition: ${details}`);
|
|
113
|
+
}
|
|
114
|
+
this.definition = definition;
|
|
115
|
+
this.questionIndex = new Map(definition.questions.map((q) => [q.id, q]));
|
|
116
|
+
}
|
|
117
|
+
get id() {
|
|
118
|
+
return this.definition.id;
|
|
119
|
+
}
|
|
120
|
+
get questions() {
|
|
121
|
+
return this.definition.questions;
|
|
122
|
+
}
|
|
123
|
+
/** Locales for which at least one text of this assessment is available. */
|
|
124
|
+
get locales() {
|
|
125
|
+
return collectLocales([
|
|
126
|
+
this.definition.title,
|
|
127
|
+
this.definition.description,
|
|
128
|
+
this.definition.instructions,
|
|
129
|
+
...this.definition.questions.map((q) => q.text),
|
|
130
|
+
]);
|
|
131
|
+
}
|
|
132
|
+
question(questionId) {
|
|
133
|
+
return this.questionIndex.get(questionId);
|
|
134
|
+
}
|
|
135
|
+
/** The option scale that applies to a question (its own or the default). */
|
|
136
|
+
optionsFor(questionId) {
|
|
137
|
+
const question = this.questionIndex.get(questionId);
|
|
138
|
+
if (!question) {
|
|
139
|
+
throw new PsytoolsError("unknown_question", `Unknown question "${questionId}" in assessment "${this.id}"`);
|
|
140
|
+
}
|
|
141
|
+
return question.options ?? this.definition.options;
|
|
142
|
+
}
|
|
143
|
+
title(locale) {
|
|
144
|
+
return this.text(this.definition.title, locale);
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* Flat, render-ready projection in one locale — hand this straight to a
|
|
148
|
+
* frontend to display the questionnaire.
|
|
149
|
+
*/
|
|
150
|
+
localize(locale) {
|
|
151
|
+
const resolved = locale ?? this.definition.defaultLocale;
|
|
152
|
+
const view = {
|
|
153
|
+
id: this.id,
|
|
154
|
+
locale: resolved,
|
|
155
|
+
title: this.text(this.definition.title, resolved),
|
|
156
|
+
questions: this.definition.questions.map((question, i) => ({
|
|
157
|
+
id: question.id,
|
|
158
|
+
index: i + 1,
|
|
159
|
+
text: this.text(question.text, resolved),
|
|
160
|
+
optional: question.optional ?? false,
|
|
161
|
+
options: (question.options ?? this.definition.options).map((option) => ({
|
|
162
|
+
value: option.value,
|
|
163
|
+
label: this.text(option.label, resolved),
|
|
164
|
+
})),
|
|
165
|
+
})),
|
|
166
|
+
};
|
|
167
|
+
if (this.definition.description) {
|
|
168
|
+
view.description = this.text(this.definition.description, resolved);
|
|
169
|
+
}
|
|
170
|
+
if (this.definition.instructions) {
|
|
171
|
+
view.instructions = this.text(this.definition.instructions, resolved);
|
|
172
|
+
}
|
|
173
|
+
return view;
|
|
174
|
+
}
|
|
175
|
+
/** Starts a new (empty) response for this assessment. */
|
|
176
|
+
createResponse(options) {
|
|
177
|
+
return new AssessmentResponse(this, options);
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* Evaluates a response (or raw answers) with the definition's declarative
|
|
181
|
+
* scoring, or with `evaluator` when provided.
|
|
182
|
+
*
|
|
183
|
+
* When given an `AssessmentResponse`, its status must be `complete` or
|
|
184
|
+
* `submitted` — pass `allowIncomplete` to score partial responses anyway.
|
|
185
|
+
* Raw answer maps are scored as-is (low-level escape hatch).
|
|
186
|
+
*
|
|
187
|
+
* @throws PsytoolsError `incomplete_response` | `no_scoring`
|
|
188
|
+
*/
|
|
189
|
+
evaluate(response, evaluator, options) {
|
|
190
|
+
if (response instanceof AssessmentResponse) {
|
|
191
|
+
const scorable = response.status === "complete" || response.status === "submitted";
|
|
192
|
+
if (!scorable && !options?.allowIncomplete) {
|
|
193
|
+
const missing = response.unanswered().join(", ");
|
|
194
|
+
throw new PsytoolsError("incomplete_response", `Cannot evaluate a response with status "${response.status}" (unanswered: ${missing}); ` +
|
|
195
|
+
"pass { allowIncomplete: true } to score it anyway");
|
|
196
|
+
}
|
|
197
|
+
return evaluate(this.definition, response.answers, evaluator);
|
|
198
|
+
}
|
|
199
|
+
return evaluate(this.definition, response, evaluator);
|
|
200
|
+
}
|
|
201
|
+
/** The plain serializable definition (used by `JSON.stringify`). */
|
|
202
|
+
toJSON() {
|
|
203
|
+
return this.definition;
|
|
204
|
+
}
|
|
205
|
+
/** Serializes the definition to a JSON string (for DB storage etc.). */
|
|
206
|
+
stringify(space) {
|
|
207
|
+
return JSON.stringify(this.definition, null, space);
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* Parses and validates a definition from a JSON string or plain object.
|
|
211
|
+
* @throws PsytoolsError `invalid_json` | `invalid_definition`
|
|
212
|
+
*/
|
|
213
|
+
static parse(input) {
|
|
214
|
+
let raw = input;
|
|
215
|
+
if (typeof input === "string") {
|
|
216
|
+
try {
|
|
217
|
+
raw = JSON.parse(input);
|
|
218
|
+
}
|
|
219
|
+
catch (error) {
|
|
220
|
+
throw new PsytoolsError("invalid_json", `Not valid JSON: ${error.message}`);
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
return new Assessment(raw);
|
|
224
|
+
}
|
|
225
|
+
text(text, locale) {
|
|
226
|
+
return localize(text, locale ?? this.definition.defaultLocale, this.definition.defaultLocale);
|
|
227
|
+
}
|
|
228
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { AnswerMap, AssessmentDefinition, EvaluationResult, Evaluator } from "./types.ts";
|
|
2
|
+
/**
|
|
3
|
+
* Evaluates answers against an assessment definition.
|
|
4
|
+
*
|
|
5
|
+
* Uses `evaluator` when given; otherwise applies the definition's
|
|
6
|
+
* declarative `scoring` (`sum` or `subscales`).
|
|
7
|
+
*
|
|
8
|
+
* @throws PsytoolsError `no_scoring` when neither is available.
|
|
9
|
+
*/
|
|
10
|
+
export declare function evaluate(definition: AssessmentDefinition, answers: AnswerMap, evaluator?: Evaluator): EvaluationResult;
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
import { PsytoolsError } from "./errors.js";
|
|
2
|
+
/**
|
|
3
|
+
* Evaluates answers against an assessment definition.
|
|
4
|
+
*
|
|
5
|
+
* Uses `evaluator` when given; otherwise applies the definition's
|
|
6
|
+
* declarative `scoring` (`sum` or `subscales`).
|
|
7
|
+
*
|
|
8
|
+
* @throws PsytoolsError `no_scoring` when neither is available.
|
|
9
|
+
*/
|
|
10
|
+
export function evaluate(definition, answers, evaluator) {
|
|
11
|
+
if (evaluator)
|
|
12
|
+
return evaluator(definition, answers);
|
|
13
|
+
const scoring = definition.scoring;
|
|
14
|
+
if (!scoring) {
|
|
15
|
+
throw new PsytoolsError("no_scoring", `Assessment "${definition.id}" has no scoring definition; pass a custom evaluator`);
|
|
16
|
+
}
|
|
17
|
+
switch (scoring.kind) {
|
|
18
|
+
case "sum":
|
|
19
|
+
return evaluateSum(definition, answers, scoring.bands, scoring.flags);
|
|
20
|
+
case "subscales": {
|
|
21
|
+
const scales = scoring.subscales.map((subscale) => {
|
|
22
|
+
const questions = subscale.questionIds.map((id) => requireQuestion(definition, id));
|
|
23
|
+
const multiplier = subscale.multiplier ?? 1;
|
|
24
|
+
const { score, min, max } = sumQuestions(definition, questions, answers, multiplier);
|
|
25
|
+
return {
|
|
26
|
+
id: subscale.id,
|
|
27
|
+
label: subscale.label,
|
|
28
|
+
score,
|
|
29
|
+
min,
|
|
30
|
+
max,
|
|
31
|
+
...bandOf(score, subscale.bands),
|
|
32
|
+
};
|
|
33
|
+
});
|
|
34
|
+
return {
|
|
35
|
+
kind: "multiscale",
|
|
36
|
+
scales,
|
|
37
|
+
flags: triggeredFlags(answers, scoring.flags),
|
|
38
|
+
};
|
|
39
|
+
}
|
|
40
|
+
default:
|
|
41
|
+
throw new PsytoolsError("no_scoring", `Unsupported scoring kind "${scoring.kind}"`);
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
function evaluateSum(definition, answers, bands, flags) {
|
|
45
|
+
const { score, min, max } = sumQuestions(definition, definition.questions, answers, 1);
|
|
46
|
+
return {
|
|
47
|
+
kind: "scale",
|
|
48
|
+
score,
|
|
49
|
+
min,
|
|
50
|
+
max,
|
|
51
|
+
...bandOf(score, bands),
|
|
52
|
+
flags: triggeredFlags(answers, flags),
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
function sumQuestions(definition, questions, answers, multiplier) {
|
|
56
|
+
let score = 0;
|
|
57
|
+
let min = 0;
|
|
58
|
+
let max = 0;
|
|
59
|
+
for (const question of questions) {
|
|
60
|
+
const values = (question.options ?? definition.options).map((o) => o.value);
|
|
61
|
+
const lowest = Math.min(...values);
|
|
62
|
+
const highest = Math.max(...values);
|
|
63
|
+
min += lowest;
|
|
64
|
+
max += highest;
|
|
65
|
+
const answered = answers[question.id];
|
|
66
|
+
if (answered === undefined)
|
|
67
|
+
continue;
|
|
68
|
+
score += question.reverseScored ? highest + lowest - answered : answered;
|
|
69
|
+
}
|
|
70
|
+
return { score: score * multiplier, min: min * multiplier, max: max * multiplier };
|
|
71
|
+
}
|
|
72
|
+
function bandOf(score, bands) {
|
|
73
|
+
const match = bands?.find((band) => score >= band.min && score <= band.max);
|
|
74
|
+
return match ? { band: { id: match.id, label: match.label } } : {};
|
|
75
|
+
}
|
|
76
|
+
function triggeredFlags(answers, flags) {
|
|
77
|
+
if (!flags)
|
|
78
|
+
return [];
|
|
79
|
+
const triggered = [];
|
|
80
|
+
for (const flag of flags) {
|
|
81
|
+
const value = answers[flag.questionId];
|
|
82
|
+
if (value !== undefined && value >= flag.minValue) {
|
|
83
|
+
triggered.push({
|
|
84
|
+
id: flag.id,
|
|
85
|
+
questionId: flag.questionId,
|
|
86
|
+
value,
|
|
87
|
+
label: flag.label,
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
return triggered;
|
|
92
|
+
}
|
|
93
|
+
function requireQuestion(definition, questionId) {
|
|
94
|
+
const question = definition.questions.find((q) => q.id === questionId);
|
|
95
|
+
if (!question) {
|
|
96
|
+
throw new PsytoolsError("unknown_question", `Scoring references unknown question "${questionId}" in assessment "${definition.id}"`);
|
|
97
|
+
}
|
|
98
|
+
return question;
|
|
99
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { LocalizedText } from "./types.ts";
|
|
2
|
+
/**
|
|
3
|
+
* Resolves a `LocalizedText` to a string for the given locale.
|
|
4
|
+
*
|
|
5
|
+
* Resolution order: exact locale -> base language of the locale
|
|
6
|
+
* (`"de-AT"` -> `"de"`) -> `fallbackLocale` -> first available entry.
|
|
7
|
+
*/
|
|
8
|
+
export declare function localize(text: LocalizedText, locale: string, fallbackLocale?: string): string;
|
|
9
|
+
/** Collects the union of locales present in a set of localized texts. */
|
|
10
|
+
export declare function collectLocales(texts: Array<LocalizedText | undefined>): string[];
|
package/dist/esm/i18n.js
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resolves a `LocalizedText` to a string for the given locale.
|
|
3
|
+
*
|
|
4
|
+
* Resolution order: exact locale -> base language of the locale
|
|
5
|
+
* (`"de-AT"` -> `"de"`) -> `fallbackLocale` -> first available entry.
|
|
6
|
+
*/
|
|
7
|
+
export function localize(text, locale, fallbackLocale) {
|
|
8
|
+
const exact = text[locale];
|
|
9
|
+
if (exact !== undefined)
|
|
10
|
+
return exact;
|
|
11
|
+
const base = locale.split("-")[0];
|
|
12
|
+
if (base !== undefined && base !== locale && text[base] !== undefined) {
|
|
13
|
+
return text[base];
|
|
14
|
+
}
|
|
15
|
+
if (fallbackLocale !== undefined && text[fallbackLocale] !== undefined) {
|
|
16
|
+
return text[fallbackLocale];
|
|
17
|
+
}
|
|
18
|
+
const first = Object.values(text)[0];
|
|
19
|
+
return first ?? "";
|
|
20
|
+
}
|
|
21
|
+
/** Collects the union of locales present in a set of localized texts. */
|
|
22
|
+
export function collectLocales(texts) {
|
|
23
|
+
const locales = new Set();
|
|
24
|
+
for (const text of texts) {
|
|
25
|
+
if (!text)
|
|
26
|
+
continue;
|
|
27
|
+
for (const locale of Object.keys(text))
|
|
28
|
+
locales.add(locale);
|
|
29
|
+
}
|
|
30
|
+
return [...locales].sort();
|
|
31
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
export type { LocalizedText, AssessmentOption, AssessmentQuestion, AssessmentDefinition, ScoreBand, ScoreFlag, SumScoring, SubscaleDefinition, SubscaleScoring, ScoringDefinition, AnswerMap, ResponseStatus, ResponseData, ValidationIssue, ValidationResult, BandResult, TriggeredFlag, ScaleScore, ScaleResult, MultiScaleResult, CategoricalResult, CustomResult, EvaluationResult, Evaluator, LocalizedAssessmentView, } from "./types.ts";
|
|
2
|
+
export { PsytoolsError } from "./errors.ts";
|
|
3
|
+
export { localize, collectLocales } from "./i18n.ts";
|
|
4
|
+
export { Assessment, validateDefinition } from "./assessment.ts";
|
|
5
|
+
export { AssessmentResponse } from "./response.ts";
|
|
6
|
+
export { evaluate } from "./evaluation.ts";
|
|
7
|
+
export { phq9, gad7, dass21, inventories, loadInventory, twoWeekFrequencyOptions, twoWeekInstructions, } from "./inventories/index.ts";
|
|
8
|
+
export type { InventoryId } from "./inventories/index.ts";
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export { PsytoolsError } from "./errors.js";
|
|
2
|
+
export { localize, collectLocales } from "./i18n.js";
|
|
3
|
+
export { Assessment, validateDefinition } from "./assessment.js";
|
|
4
|
+
export { AssessmentResponse } from "./response.js";
|
|
5
|
+
export { evaluate } from "./evaluation.js";
|
|
6
|
+
export { phq9, gad7, dass21, inventories, loadInventory, twoWeekFrequencyOptions, twoWeekInstructions, } from "./inventories/index.js";
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { AssessmentOption, LocalizedText } from "../types.ts";
|
|
2
|
+
/**
|
|
3
|
+
* The 0–3 frequency scale ("over the last 2 weeks") shared by PHQ-9 and
|
|
4
|
+
* GAD-7.
|
|
5
|
+
*/
|
|
6
|
+
export declare const twoWeekFrequencyOptions: AssessmentOption[];
|
|
7
|
+
/** Instructions shared by PHQ-9 and GAD-7. */
|
|
8
|
+
export declare const twoWeekInstructions: LocalizedText;
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The 0–3 frequency scale ("over the last 2 weeks") shared by PHQ-9 and
|
|
3
|
+
* GAD-7.
|
|
4
|
+
*/
|
|
5
|
+
export const twoWeekFrequencyOptions = [
|
|
6
|
+
{
|
|
7
|
+
value: 0,
|
|
8
|
+
label: {
|
|
9
|
+
en: "Not at all",
|
|
10
|
+
tr: "Hiç",
|
|
11
|
+
de: "Überhaupt nicht",
|
|
12
|
+
},
|
|
13
|
+
},
|
|
14
|
+
{
|
|
15
|
+
value: 1,
|
|
16
|
+
label: {
|
|
17
|
+
en: "Several days",
|
|
18
|
+
tr: "Birkaç gün",
|
|
19
|
+
de: "An einzelnen Tagen",
|
|
20
|
+
},
|
|
21
|
+
},
|
|
22
|
+
{
|
|
23
|
+
value: 2,
|
|
24
|
+
label: {
|
|
25
|
+
en: "More than half the days",
|
|
26
|
+
tr: "Günlerin yarısından fazlasında",
|
|
27
|
+
de: "An mehr als der Hälfte der Tage",
|
|
28
|
+
},
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
value: 3,
|
|
32
|
+
label: {
|
|
33
|
+
en: "Nearly every day",
|
|
34
|
+
tr: "Hemen hemen her gün",
|
|
35
|
+
de: "Beinahe jeden Tag",
|
|
36
|
+
},
|
|
37
|
+
},
|
|
38
|
+
];
|
|
39
|
+
/** Instructions shared by PHQ-9 and GAD-7. */
|
|
40
|
+
export const twoWeekInstructions = {
|
|
41
|
+
en: "Over the last 2 weeks, how often have you been bothered by any of the following problems?",
|
|
42
|
+
tr: "Son 2 hafta içinde, aşağıdaki sorunlardan herhangi biri sizi ne sıklıkta rahatsız etti?",
|
|
43
|
+
de: "Wie oft fühlten Sie sich im Verlauf der letzten 2 Wochen durch die folgenden Beschwerden beeinträchtigt?",
|
|
44
|
+
};
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { AssessmentDefinition } from "../types.ts";
|
|
2
|
+
/**
|
|
3
|
+
* DASS-21 — Depression Anxiety Stress Scales, short form.
|
|
4
|
+
*
|
|
5
|
+
* 21 items, 0–3 applicability scale, three subscales (depression, anxiety,
|
|
6
|
+
* stress) of 7 items each. Subscale sums are multiplied by 2 so severity
|
|
7
|
+
* cutoffs match the full DASS-42. The DASS is in the public domain
|
|
8
|
+
* (Lovibond & Lovibond, 1995). Translations follow published validated
|
|
9
|
+
* versions — verify against the official wording before clinical use.
|
|
10
|
+
*/
|
|
11
|
+
export declare const dass21: AssessmentDefinition;
|