psytools 0.3.2 → 0.4.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.
Files changed (57) hide show
  1. package/README.md +29 -15
  2. package/SOURCES.md +2 -0
  3. package/dist/cjs/assessment.d.ts +6 -4
  4. package/dist/cjs/assessment.js +10 -6
  5. package/dist/cjs/errors.d.ts +4 -2
  6. package/dist/cjs/evaluation.d.ts +10 -5
  7. package/dist/cjs/evaluation.js +68 -31
  8. package/dist/cjs/i18n.d.ts +1 -1
  9. package/dist/cjs/i18n.js +2 -2
  10. package/dist/cjs/index.d.ts +4 -2
  11. package/dist/cjs/index.js +2 -2
  12. package/dist/cjs/inventories/aq10.js +35 -5
  13. package/dist/cjs/inventories/asrs6.js +28 -6
  14. package/dist/cjs/inventories/audit.js +107 -16
  15. package/dist/cjs/inventories/common.js +10 -0
  16. package/dist/cjs/inventories/dass21.js +75 -19
  17. package/dist/cjs/inventories/gad7.js +23 -5
  18. package/dist/cjs/inventories/mini-ipip.js +107 -9
  19. package/dist/cjs/inventories/phq9.js +30 -6
  20. package/dist/cjs/inventories/who5.js +31 -5
  21. package/dist/cjs/types.d.ts +30 -1
  22. package/dist/esm/assessment.d.ts +6 -4
  23. package/dist/esm/assessment.js +11 -7
  24. package/dist/esm/errors.d.ts +4 -2
  25. package/dist/esm/evaluation.d.ts +10 -5
  26. package/dist/esm/evaluation.js +68 -31
  27. package/dist/esm/i18n.d.ts +1 -1
  28. package/dist/esm/i18n.js +1 -1
  29. package/dist/esm/index.d.ts +4 -2
  30. package/dist/esm/index.js +1 -1
  31. package/dist/esm/inventories/aq10.js +35 -5
  32. package/dist/esm/inventories/asrs6.js +28 -6
  33. package/dist/esm/inventories/audit.js +107 -16
  34. package/dist/esm/inventories/common.js +10 -0
  35. package/dist/esm/inventories/dass21.js +75 -19
  36. package/dist/esm/inventories/gad7.js +23 -5
  37. package/dist/esm/inventories/mini-ipip.js +107 -9
  38. package/dist/esm/inventories/phq9.js +30 -6
  39. package/dist/esm/inventories/who5.js +31 -5
  40. package/dist/esm/types.d.ts +30 -1
  41. package/package.json +1 -1
  42. package/schema/assessment-definition.schema.json +15 -3
  43. package/src/assessment.ts +15 -9
  44. package/src/errors.ts +25 -2
  45. package/src/evaluation.ts +103 -30
  46. package/src/i18n.ts +1 -1
  47. package/src/index.ts +6 -1
  48. package/src/inventories/aq10.ts +35 -5
  49. package/src/inventories/asrs6.ts +28 -6
  50. package/src/inventories/audit.ts +107 -16
  51. package/src/inventories/common.ts +10 -0
  52. package/src/inventories/dass21.ts +75 -19
  53. package/src/inventories/gad7.ts +23 -5
  54. package/src/inventories/mini-ipip.ts +107 -9
  55. package/src/inventories/phq9.ts +30 -6
  56. package/src/inventories/who5.ts +31 -5
  57. package/src/types.ts +38 -6
package/README.md CHANGED
@@ -19,7 +19,7 @@ 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, and DASS-21 ship ready to use in English, Turkish, and German, with published scoring rules and citations.
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.
@@ -61,7 +61,7 @@ const result = phq9.evaluate(response);
61
61
 
62
62
  // evaluate() refuses responses that are not complete/submitted;
63
63
  // score partial data explicitly:
64
- phq9.evaluate(inProgressResponse, undefined, { allowIncomplete: true });
64
+ phq9.evaluate(inProgressResponse, { allowIncomplete: true });
65
65
 
66
66
  // 4. Persist — both sides are plain JSON.
67
67
  db.save(response.stringify()); // response -> DB
@@ -81,14 +81,14 @@ const response = AssessmentResponse.parse(assessment, rowFromDb); // answers re-
81
81
 
82
82
  | Id | Instrument | Items | Scoring | Locales |
83
83
  | --- | --- | --- | --- | --- |
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 |
84
+ | `phq9` | Patient Health Questionnaire-9 (depression) | 9 | Sum 0–27, 5 severity bands, item-9 suicidality flag | en, tr, de, zh, es |
85
+ | `gad7` | Generalized Anxiety Disorder-7 | 7 | Sum 0–21, 4 severity bands | en, tr, de, zh, es |
86
+ | `dass21` | Depression Anxiety Stress Scales (short form) | 21 | 3 subscales × 7 items, sums doubled, banded per subscale | en, tr, de, zh, es |
87
+ | `who5` | WHO-5 Well-Being Index | 5 | Sum × 4 → 0–100 (higher is better), 3 well-being bands | en, tr, de, zh, es |
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, zh, es |
89
+ | `aq10` | Autism Spectrum Quotient (AQ-10, adult) | 10 | 1 point per item in trait direction (agree/disagree), ≥6 refer | en, tr, de, zh, es |
90
+ | `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 |
91
+ | `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
92
 
93
93
  ```ts
94
94
  import { loadInventory, inventories, dass21 } from "psytools";
@@ -147,6 +147,20 @@ Questions may also carry their own `options` to override the default scale, and
147
147
 
148
148
  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
149
 
150
+ ### Missing answers
151
+
152
+ 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`):
153
+
154
+ ```ts
155
+ scoring: {
156
+ kind: "sum",
157
+ missing: { strategy: "prorate", minAnswered: 7 }, // or "ignore" (default) / "require-complete"
158
+ ...
159
+ }
160
+ ```
161
+
162
+ `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.
163
+
150
164
  ## Custom evaluation
151
165
 
152
166
  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 +177,7 @@ const attachmentStyle: Evaluator = (definition, answers) => {
163
177
  };
164
178
  };
165
179
 
166
- assessment.evaluate(response, attachmentStyle);
180
+ assessment.evaluate(response, { evaluator: attachmentStyle });
167
181
  ```
168
182
 
169
183
  Result shapes: `scale` (single score + band + flags), `multiscale` (named subscales), `categorical`, and `custom` (escape hatch).
@@ -184,11 +198,11 @@ const history = rows
184
198
  | --- | --- |
185
199
  | `Assessment` | Wraps a definition: validation, `localize()`, `createResponse()`, `evaluate()`, `stringify()`/`parse()` |
186
200
  | `AssessmentResponse` | `answer()`, `answerAll()`, `clearAnswer()`, `status`, `progress()`, `validate()`, `submit()`, `stringify()`/`parse()` |
187
- | `evaluate(definition, answers, evaluator?)` | Standalone scoring (also available as `Assessment#evaluate`) |
201
+ | `evaluate(definition, answers, { evaluator? })` | Standalone scoring (also available as `Assessment#evaluate`) |
188
202
  | `validateDefinition(input)` | Non-throwing structural validation of definitions |
189
- | `loadInventory(id)` / `inventories` / `phq9`, `gad7`, `dass21` | Predefined instruments |
190
- | `localize(text, locale, fallback?)` / `collectLocales(texts)` | Locale helpers |
191
- | `PsytoolsError` | All errors carry a stable `code` (e.g. `invalid_value`, `already_submitted`) |
203
+ | `loadInventory(id)` / `inventories` | Predefined instruments (definitions also exported by name) |
204
+ | `localizeText(text, locale, fallback?)` / `collectLocales(texts)` | Locale helpers |
205
+ | `PsytoolsError` | All errors carry a `code` typed as `PsytoolsErrorCode` (e.g. `invalid_value`, `already_submitted`) |
192
206
 
193
207
  ## Development
194
208
 
package/SOURCES.md CHANGED
@@ -21,6 +21,8 @@ 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
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 Turkish and German 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. Verification contributions from native speakers are very welcome.
26
28
 
@@ -1,5 +1,6 @@
1
- import type { AssessmentDefinition, AssessmentOption, AssessmentQuestion, EvaluationResult, Evaluator, LocalizedAssessmentView, ValidationResult } from "./types.ts";
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>, evaluator?: Evaluator, options?: {
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`). */
@@ -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, evaluator, options) {
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.localize)(text, locale ?? this.definition.defaultLocale, this.definition.defaultLocale);
244
+ return (0, i18n_ts_1.localizeText)(text, locale ?? this.definition.defaultLocale, this.definition.defaultLocale);
241
245
  }
242
246
  }
243
247
  exports.Assessment = Assessment;
@@ -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" | "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: string;
4
- constructor(code: string, message: string);
5
+ readonly code: PsytoolsErrorCode;
6
+ constructor(code: PsytoolsErrorCode, message: string);
5
7
  }
@@ -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 `evaluator` is
7
- * used when given; otherwise the definition's declarative `scoring`
8
- * (`sum` or `subscales`) applies.
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, evaluator?: Evaluator): EvaluationResult;
17
+ export declare function evaluate(definition: AssessmentDefinition, answers: AnswerMap, options?: EvaluateOptions): EvaluationResult;
@@ -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 `evaluator` is
10
- * used when given; otherwise the definition's declarative `scoring`
11
- * (`sum` or `subscales`) applies.
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, evaluator) {
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
- let score = 0;
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 answered = answers[question.id];
31
- if (answered === undefined)
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) - answered
36
- : answered;
41
+ ? Math.max(...values) + Math.min(...values) - value
42
+ : value;
37
43
  if (effective >= item.minValue)
38
- score += 1;
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 multiplier = subscale.multiplier ?? 1;
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
- score,
58
- min,
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 multiplier = scoring.multiplier ?? 1;
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
- score,
93
- min,
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
- function sumQuestions(definition, questions, answers, multiplier) {
100
- let score = 0;
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 answered = answers[question.id];
110
- if (answered === undefined)
115
+ const value = answers[question.id];
116
+ if (value === undefined)
111
117
  continue;
112
- score += question.reverseScored ? highest + lowest - answered : answered;
118
+ raw += question.reverseScored ? highest + lowest - value : value;
113
119
  }
114
- return { score: score * multiplier, min: min * multiplier, max: max * multiplier };
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);
@@ -5,6 +5,6 @@ import type { LocalizedText } from "./types.ts";
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 localize(text: LocalizedText, locale: string, fallbackLocale?: string): string;
8
+ export declare function localizeText(text: LocalizedText, locale: string, fallbackLocale?: string): string;
9
9
  /** Collects the union of locales present in a set of localized texts. */
10
10
  export declare function collectLocales(texts: Array<LocalizedText | undefined>): string[];
package/dist/cjs/i18n.js CHANGED
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.localize = localize;
3
+ exports.localizeText = localizeText;
4
4
  exports.collectLocales = collectLocales;
5
5
  /**
6
6
  * Resolves a `LocalizedText` to a string for the given locale.
@@ -8,7 +8,7 @@ exports.collectLocales = collectLocales;
8
8
  * Resolution order: exact locale -> base language of the locale
9
9
  * (`"de-AT"` -> `"de"`) -> `fallbackLocale` -> first available entry.
10
10
  */
11
- function localize(text, locale, fallbackLocale) {
11
+ function localizeText(text, locale, fallbackLocale) {
12
12
  const exact = text[locale];
13
13
  if (exact !== undefined)
14
14
  return exact;
@@ -1,8 +1,10 @@
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, 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 { localize, collectLocales } from "./i18n.ts";
3
+ export type { PsytoolsErrorCode } from "./errors.ts";
4
+ export { localizeText, collectLocales } from "./i18n.ts";
4
5
  export { Assessment, validateDefinition } from "./assessment.ts";
5
6
  export { AssessmentResponse } from "./response.ts";
6
7
  export { evaluate } from "./evaluation.ts";
8
+ export type { EvaluateOptions } from "./evaluation.ts";
7
9
  export { phq9, gad7, dass21, who5, asrs6, aq10, audit, miniIpip, inventories, loadInventory, twoWeekFrequencyOptions, twoWeekInstructions, } from "./inventories/index.ts";
8
10
  export type { InventoryId } from "./inventories/index.ts";
package/dist/cjs/index.js CHANGED
@@ -1,10 +1,10 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.twoWeekInstructions = exports.twoWeekFrequencyOptions = exports.loadInventory = exports.inventories = exports.miniIpip = exports.audit = exports.aq10 = exports.asrs6 = exports.who5 = exports.dass21 = exports.gad7 = exports.phq9 = exports.evaluate = exports.AssessmentResponse = exports.validateDefinition = exports.Assessment = exports.collectLocales = exports.localize = exports.PsytoolsError = void 0;
3
+ exports.twoWeekInstructions = exports.twoWeekFrequencyOptions = exports.loadInventory = exports.inventories = exports.miniIpip = exports.audit = exports.aq10 = exports.asrs6 = exports.who5 = exports.dass21 = exports.gad7 = exports.phq9 = exports.evaluate = exports.AssessmentResponse = exports.validateDefinition = exports.Assessment = exports.collectLocales = exports.localizeText = exports.PsytoolsError = void 0;
4
4
  var errors_ts_1 = require("./errors.js");
5
5
  Object.defineProperty(exports, "PsytoolsError", { enumerable: true, get: function () { return errors_ts_1.PsytoolsError; } });
6
6
  var i18n_ts_1 = require("./i18n.js");
7
- Object.defineProperty(exports, "localize", { enumerable: true, get: function () { return i18n_ts_1.localize; } });
7
+ Object.defineProperty(exports, "localizeText", { enumerable: true, get: function () { return i18n_ts_1.localizeText; } });
8
8
  Object.defineProperty(exports, "collectLocales", { enumerable: true, get: function () { return i18n_ts_1.collectLocales; } });
9
9
  var assessment_ts_1 = require("./assessment.js");
10
10
  Object.defineProperty(exports, "Assessment", { enumerable: true, get: function () { return assessment_ts_1.Assessment; } });
@@ -18,34 +18,40 @@ exports.aq10 = {
18
18
  en: "Autism Spectrum Quotient (AQ-10) — Adult",
19
19
  tr: "Otizm Spektrum Anketi (AQ-10) — Yetişkin",
20
20
  de: "Autismus-Spektrum-Quotient (AQ-10) — Erwachsene",
21
+ zh: "自闭症谱系商数问卷(AQ-10)— 成人版",
22
+ es: "Cociente del Espectro Autista (AQ-10) — Adultos",
21
23
  },
22
24
  description: {
23
25
  en: "A 10-item screening questionnaire for autistic traits in adults, condensed from the 50-item Autism Spectrum Quotient.",
24
26
  tr: "50 maddelik Otizm Spektrum Anketi'nden kısaltılmış, yetişkinlerde otistik özellikleri taramak için 10 maddelik bir ölçek.",
25
27
  de: "Ein 10-Item-Screeningfragebogen für autistische Merkmale bei Erwachsenen, verkürzt aus dem 50-Item-Autismus-Spektrum-Quotienten.",
28
+ zh: "一份用于筛查成人自闭症特质的10条目问卷,由50条目的自闭症谱系商数量表精简而成。",
29
+ es: "Un cuestionario de cribado de 10 ítems para rasgos autistas en adultos, condensado a partir del Cociente del Espectro Autista de 50 ítems.",
26
30
  },
27
31
  instructions: {
28
32
  en: "For each statement, select the answer that best describes you.",
29
33
  tr: "Her ifade için sizi en iyi tanımlayan yanıtı işaretleyin.",
30
34
  de: "Wählen Sie zu jeder Aussage die Antwort, die Sie am besten beschreibt.",
35
+ zh: "请针对每条陈述,选择最符合您情况的答案。",
36
+ es: "Para cada afirmación, seleccione la respuesta que mejor lo describa.",
31
37
  },
32
38
  defaultLocale: "en",
33
39
  options: [
34
40
  {
35
41
  value: 0,
36
- label: { en: "Definitely disagree", tr: "Kesinlikle katılmıyorum", de: "Stimme überhaupt nicht zu" },
42
+ label: { en: "Definitely disagree", tr: "Kesinlikle katılmıyorum", de: "Stimme überhaupt nicht zu", zh: "完全不同意", es: "Totalmente en desacuerdo" },
37
43
  },
38
44
  {
39
45
  value: 1,
40
- label: { en: "Slightly disagree", tr: "Biraz katılmıyorum", de: "Stimme eher nicht zu" },
46
+ label: { en: "Slightly disagree", tr: "Biraz katılmıyorum", de: "Stimme eher nicht zu", zh: "有点不同意", es: "Ligeramente en desacuerdo" },
41
47
  },
42
48
  {
43
49
  value: 2,
44
- label: { en: "Slightly agree", tr: "Biraz katılıyorum", de: "Stimme eher zu" },
50
+ label: { en: "Slightly agree", tr: "Biraz katılıyorum", de: "Stimme eher zu", zh: "有点同意", es: "Ligeramente de acuerdo" },
45
51
  },
46
52
  {
47
53
  value: 3,
48
- label: { en: "Definitely agree", tr: "Kesinlikle katılıyorum", de: "Stimme voll und ganz zu" },
54
+ label: { en: "Definitely agree", tr: "Kesinlikle katılıyorum", de: "Stimme voll und ganz zu", zh: "完全同意", es: "Totalmente de acuerdo" },
49
55
  },
50
56
  ],
51
57
  questions: [
@@ -55,6 +61,8 @@ exports.aq10 = {
55
61
  en: "I often notice small sounds when others do not",
56
62
  tr: "Başkalarının fark etmediği küçük sesleri sıklıkla fark ederim",
57
63
  de: "Ich nehme oft leise Geräusche wahr, die andere nicht bemerken",
64
+ zh: "我经常注意到别人注意不到的微小声音",
65
+ es: "A menudo noto pequeños sonidos que otras personas no perciben",
58
66
  },
59
67
  },
60
68
  {
@@ -63,6 +71,8 @@ exports.aq10 = {
63
71
  en: "I usually concentrate more on the whole picture, rather than the small details",
64
72
  tr: "Genellikle küçük ayrıntılardan çok resmin bütününe odaklanırım",
65
73
  de: "Ich konzentriere mich meist mehr auf das Gesamtbild als auf die kleinen Details",
74
+ zh: "我通常更关注事情的整体,而不是小细节",
75
+ es: "Normalmente me concentro más en la imagen global que en los pequeños detalles",
66
76
  },
67
77
  reverseScored: true,
68
78
  },
@@ -72,6 +82,8 @@ exports.aq10 = {
72
82
  en: "I find it easy to do more than one thing at once",
73
83
  tr: "Aynı anda birden fazla iş yapmak benim için kolaydır",
74
84
  de: "Es fällt mir leicht, mehrere Dinge gleichzeitig zu tun",
85
+ zh: "我觉得同时做几件事情很容易",
86
+ es: "Me resulta fácil hacer más de una cosa a la vez",
75
87
  },
76
88
  reverseScored: true,
77
89
  },
@@ -81,6 +93,8 @@ exports.aq10 = {
81
93
  en: "If there is an interruption, I can switch back to what I was doing very quickly",
82
94
  tr: "Bir kesinti olursa, yapmakta olduğum işe çok hızlı bir şekilde geri dönebilirim",
83
95
  de: "Wenn ich unterbrochen werde, kann ich sehr schnell zu meiner Tätigkeit zurückkehren",
96
+ zh: "如果被打断,我能很快回到原来正在做的事情上",
97
+ es: "Si hay una interrupción, puedo volver muy rápidamente a lo que estaba haciendo",
84
98
  },
85
99
  reverseScored: true,
86
100
  },
@@ -90,6 +104,8 @@ exports.aq10 = {
90
104
  en: "I find it easy to 'read between the lines' when someone is talking to me",
91
105
  tr: "Biri benimle konuşurken 'satır aralarını okumak' benim için kolaydır",
92
106
  de: "Es fällt mir leicht, 'zwischen den Zeilen zu lesen', wenn jemand mit mir spricht",
107
+ zh: "当别人和我说话时,我觉得'听出言外之意'很容易",
108
+ es: "Me resulta fácil 'leer entre líneas' cuando alguien me está hablando",
93
109
  },
94
110
  reverseScored: true,
95
111
  },
@@ -99,6 +115,8 @@ exports.aq10 = {
99
115
  en: "I know how to tell if someone listening to me is getting bored",
100
116
  tr: "Beni dinleyen birinin sıkılmaya başladığını nasıl anlayacağımı bilirim",
101
117
  de: "Ich erkenne, ob jemand, der mir zuhört, sich zu langweilen beginnt",
118
+ zh: "我知道如何判断听我说话的人是否开始感到厌烦",
119
+ es: "Sé darme cuenta de si la persona que me escucha se está aburriendo",
102
120
  },
103
121
  reverseScored: true,
104
122
  },
@@ -108,6 +126,8 @@ exports.aq10 = {
108
126
  en: "When I'm reading a story I find it difficult to work out the characters' intentions",
109
127
  tr: "Bir öykü okurken karakterlerin niyetlerini anlamakta zorlanırım",
110
128
  de: "Wenn ich eine Geschichte lese, fällt es mir schwer, die Absichten der Figuren zu erkennen",
129
+ zh: "读故事时,我很难弄清人物的意图",
130
+ es: "Cuando leo una historia, me resulta difícil deducir las intenciones de los personajes",
111
131
  },
112
132
  },
113
133
  {
@@ -116,6 +136,8 @@ exports.aq10 = {
116
136
  en: "I like to collect information about categories of things (e.g. types of car, types of bird, types of train, types of plant etc)",
117
137
  tr: "Belirli kategorilerdeki şeyler hakkında bilgi toplamayı severim (örneğin araba türleri, kuş türleri, tren türleri, bitki türleri vb.)",
118
138
  de: "Ich sammle gern Informationen über Kategorien von Dingen (z. B. Auto-, Vogel-, Zug- oder Pflanzenarten)",
139
+ zh: "我喜欢收集各类事物的信息(例如汽车的类型、鸟的种类、火车的类型、植物的种类等)",
140
+ es: "Me gusta recopilar información sobre categorías de cosas (p. ej., tipos de coches, de aves, de trenes, de plantas, etc.)",
119
141
  },
120
142
  },
121
143
  {
@@ -124,6 +146,8 @@ exports.aq10 = {
124
146
  en: "I find it easy to work out what someone is thinking or feeling just by looking at their face",
125
147
  tr: "Sadece yüzüne bakarak birinin ne düşündüğünü ya da hissettiğini anlamak benim için kolaydır",
126
148
  de: "Es fällt mir leicht, allein am Gesicht abzulesen, was jemand denkt oder fühlt",
149
+ zh: "我觉得只看别人的脸就能轻松看出对方在想什么或有什么感受",
150
+ es: "Me resulta fácil deducir lo que alguien piensa o siente con solo mirarle la cara",
127
151
  },
128
152
  reverseScored: true,
129
153
  },
@@ -133,6 +157,8 @@ exports.aq10 = {
133
157
  en: "I find it difficult to work out people's intentions",
134
158
  tr: "İnsanların niyetlerini anlamakta zorlanırım",
135
159
  de: "Es fällt mir schwer, die Absichten anderer Menschen zu erkennen",
160
+ zh: "我很难弄清别人的意图",
161
+ es: "Me resulta difícil deducir las intenciones de las personas",
136
162
  },
137
163
  },
138
164
  ],
@@ -159,6 +185,8 @@ exports.aq10 = {
159
185
  en: "Below screening threshold",
160
186
  tr: "Tarama eşiğinin altında",
161
187
  de: "Unterhalb der Screening-Schwelle",
188
+ zh: "低于筛查阈值",
189
+ es: "Por debajo del umbral de cribado",
162
190
  },
163
191
  },
164
192
  {
@@ -169,6 +197,8 @@ exports.aq10 = {
169
197
  en: "At or above threshold — consider referral for a specialist autism assessment",
170
198
  tr: "Eşikte ya da üzerinde — uzman otizm değerlendirmesine yönlendirme düşünülmelidir",
171
199
  de: "An oder über der Schwelle — Überweisung zu einer spezialisierten Autismus-Diagnostik erwägen",
200
+ zh: "达到或超过阈值——建议考虑转介进行自闭症专科评估",
201
+ es: "En el umbral o por encima — considere la derivación para una evaluación especializada de autismo",
172
202
  },
173
203
  },
174
204
  ],
@@ -177,7 +207,7 @@ exports.aq10 = {
177
207
  reference: "Allison, C., Auyeung, B., & Baron-Cohen, S. (2012). Toward brief \"Red Flags\" for autism screening: The Short Autism Spectrum Quotient and the Short Quantitative Checklist in 1,000 cases and 3,000 controls. Journal of the American Academy of Child & Adolescent Psychiatry, 51(2), 202-212.",
178
208
  license: "Free with conditions — (c) Autism Research Centre, University of Cambridge; distributed free of charge, NICE-recommended for clinical screening. Verify licensing with ARC before embedding in commercial products.",
179
209
  licenseFlag: "free-with-conditions",
180
- translationProvenance: "en: reproduced from the original. tr/de: AI translation (Anthropic Claude, claude-fable-5) from the original English; official translations were not consulted and the texts are unverified. See SOURCES.md.",
210
+ translationProvenance: "en: reproduced from the original. Other locales (tr, de, zh, es): AI translation (Anthropic Claude, claude-fable-5) from the original English; official translations were not consulted and the texts are unverified. See SOURCES.md.",
181
211
  note: "Each item scores 1 point in the trait direction; disagree-scored items are modeled as reverseScored.",
182
212
  },
183
213
  };