psytools 0.3.1 → 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 (66) hide show
  1. package/README.md +31 -14
  2. package/SOURCES.md +63 -33
  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 +5 -3
  11. package/dist/cjs/index.js +4 -2
  12. package/dist/cjs/inventories/aq10.js +37 -5
  13. package/dist/cjs/inventories/asrs6.js +30 -6
  14. package/dist/cjs/inventories/audit.d.ts +10 -0
  15. package/dist/cjs/inventories/audit.js +322 -0
  16. package/dist/cjs/inventories/common.js +10 -0
  17. package/dist/cjs/inventories/dass21.js +77 -19
  18. package/dist/cjs/inventories/gad7.js +25 -5
  19. package/dist/cjs/inventories/index.d.ts +4 -2
  20. package/dist/cjs/inventories/index.js +7 -1
  21. package/dist/cjs/inventories/mini-ipip.d.ts +11 -0
  22. package/dist/cjs/inventories/mini-ipip.js +370 -0
  23. package/dist/cjs/inventories/phq9.js +32 -6
  24. package/dist/cjs/inventories/who5.js +33 -5
  25. package/dist/cjs/types.d.ts +30 -1
  26. package/dist/esm/assessment.d.ts +6 -4
  27. package/dist/esm/assessment.js +11 -7
  28. package/dist/esm/errors.d.ts +4 -2
  29. package/dist/esm/evaluation.d.ts +10 -5
  30. package/dist/esm/evaluation.js +68 -31
  31. package/dist/esm/i18n.d.ts +1 -1
  32. package/dist/esm/i18n.js +1 -1
  33. package/dist/esm/index.d.ts +5 -3
  34. package/dist/esm/index.js +2 -2
  35. package/dist/esm/inventories/aq10.js +37 -5
  36. package/dist/esm/inventories/asrs6.js +30 -6
  37. package/dist/esm/inventories/audit.d.ts +10 -0
  38. package/dist/esm/inventories/audit.js +319 -0
  39. package/dist/esm/inventories/common.js +10 -0
  40. package/dist/esm/inventories/dass21.js +77 -19
  41. package/dist/esm/inventories/gad7.js +25 -5
  42. package/dist/esm/inventories/index.d.ts +4 -2
  43. package/dist/esm/inventories/index.js +5 -1
  44. package/dist/esm/inventories/mini-ipip.d.ts +11 -0
  45. package/dist/esm/inventories/mini-ipip.js +367 -0
  46. package/dist/esm/inventories/phq9.js +32 -6
  47. package/dist/esm/inventories/who5.js +33 -5
  48. package/dist/esm/types.d.ts +30 -1
  49. package/package.json +6 -2
  50. package/schema/assessment-definition.schema.json +15 -3
  51. package/src/assessment.ts +15 -9
  52. package/src/errors.ts +25 -2
  53. package/src/evaluation.ts +103 -30
  54. package/src/i18n.ts +1 -1
  55. package/src/index.ts +8 -1
  56. package/src/inventories/aq10.ts +39 -5
  57. package/src/inventories/asrs6.ts +32 -6
  58. package/src/inventories/audit.ts +325 -0
  59. package/src/inventories/common.ts +10 -0
  60. package/src/inventories/dass21.ts +78 -19
  61. package/src/inventories/gad7.ts +26 -5
  62. package/src/inventories/index.ts +14 -2
  63. package/src/inventories/mini-ipip.ts +372 -0
  64. package/src/inventories/phq9.ts +33 -6
  65. package/src/inventories/who5.ts +34 -5
  66. 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,12 +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 |
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 |
90
92
 
91
93
  ```ts
92
94
  import { loadInventory, inventories, dass21 } from "psytools";
@@ -145,6 +147,20 @@ Questions may also carry their own `options` to override the default scale, and
145
147
 
146
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/`).
147
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
+
148
164
  ## Custom evaluation
149
165
 
150
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:
@@ -161,7 +177,7 @@ const attachmentStyle: Evaluator = (definition, answers) => {
161
177
  };
162
178
  };
163
179
 
164
- assessment.evaluate(response, attachmentStyle);
180
+ assessment.evaluate(response, { evaluator: attachmentStyle });
165
181
  ```
166
182
 
167
183
  Result shapes: `scale` (single score + band + flags), `multiscale` (named subscales), `categorical`, and `custom` (escape hatch).
@@ -182,11 +198,11 @@ const history = rows
182
198
  | --- | --- |
183
199
  | `Assessment` | Wraps a definition: validation, `localize()`, `createResponse()`, `evaluate()`, `stringify()`/`parse()` |
184
200
  | `AssessmentResponse` | `answer()`, `answerAll()`, `clearAnswer()`, `status`, `progress()`, `validate()`, `submit()`, `stringify()`/`parse()` |
185
- | `evaluate(definition, answers, evaluator?)` | Standalone scoring (also available as `Assessment#evaluate`) |
201
+ | `evaluate(definition, answers, { evaluator? })` | Standalone scoring (also available as `Assessment#evaluate`) |
186
202
  | `validateDefinition(input)` | Non-throwing structural validation of definitions |
187
- | `loadInventory(id)` / `inventories` / `phq9`, `gad7`, `dass21` | Predefined instruments |
188
- | `localize(text, locale, fallback?)` / `collectLocales(texts)` | Locale helpers |
189
- | `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`) |
190
206
 
191
207
  ## Development
192
208
 
@@ -200,7 +216,8 @@ npm run build # ESM + CJS + type declarations into dist/
200
216
 
201
217
  - **Not a diagnostic tool.** Scores, severity bands, and flags implement the published scoring rules of screening instruments; they are not diagnoses and do not replace clinical judgment.
202
218
  - **Crisis-relevant answers.** PHQ-9 item 9 raises a `suicidality` flag — applications should surface this to a responsible clinician and provide crisis resources to respondents.
203
- - **Instrument licensing & provenance.** All bundled instruments are free to use; [SOURCES.md](SOURCES.md) lists the original citation, usage terms, and translation notes for each. Bundled translations follow published validated versions — verify wording against the official versions before clinical use. Corrections and requests: <samed@luckys.dev>.
219
+ - **Instrument licensing.** [SOURCES.md](SOURCES.md) flags every bundled instrument as **Free** (PHQ-9, GAD-7, DASS-21, WHO-5 — usable without permission, including commercially) or **Free with conditions** (ASRS v1.1, AQ-10 — free for clinical/research use; verify with the rights holder before embedding in commercial products). Each inventory's `meta.licenseFlag` carries the same flag programmatically.
220
+ - **Translation provenance.** English texts are reproduced from the original instruments. Turkish and German texts are AI translations (Anthropic Claude, model `claude-fable-5`) of the original English — official translations were **not** consulted and the texts are unverified; see [SOURCES.md](SOURCES.md). Obtain and compare the official version for your language before clinical use. Corrections: <samed@luckys.dev>.
204
221
 
205
222
  ## License
206
223
 
package/SOURCES.md CHANGED
@@ -1,53 +1,83 @@
1
- # Sources & credits
1
+ # Sources, licenses & translations
2
2
 
3
- The inventories bundled with psytools implement published, freely usable instruments. This file records where each one comes from, its usage terms, and how the bundled translations were prepared — so you can judge their provenance and cite the original authors properly.
3
+ psytools is integrated into real products, so this file states precisely — per instrument — where every text comes from, who holds the rights, and what you are allowed to do with it. Each inventory also carries a machine-readable summary in its `meta` field.
4
4
 
5
- **Corrections and requests:** if you find a wording that deviates from an official version, hold rights to an instrument, or want an instrument added or removed, please email <samed@luckys.dev> or open an issue at <https://github.com/urtuba/psytools/issues>.
5
+ **Corrections and requests:** if you find a wording that deviates from an official version, hold rights to an instrument, or want an instrument added, corrected, or removed, email <samed@luckys.dev> or open an issue at <https://github.com/urtuba/psytools/issues>.
6
6
 
7
- ## Translation policy
7
+ ## License flags
8
8
 
9
- - English texts follow the original published instruments.
10
- - Turkish and German texts follow published validated translations where available; minor editorial normalization (punctuation, quotation style) may have been applied.
11
- - Translations have **not** been re-validated in this packaged form. Before clinical or research use, verify the wording against the official version for your language and population.
9
+ | Flag | Meaning |
10
+ | --- | --- |
11
+ | **Free** | Public domain or explicitly free for any use, including commercial products, without permission. |
12
+ | **Free with conditions** | Free for clinical and research use as distributed; embedding in commercial products is not explicitly licensed — verify with the rights holder before shipping. |
13
+ | **Research only** | Usable in research contexts only. *(No bundled instrument currently carries this flag, and none will be added without it being stated here.)* |
14
+
15
+ ## Translation provenance — read this before clinical use
16
+
17
+ The same provenance applies to every bundled inventory. If an inventory ever deviates (e.g. an official translation is adopted and verified), it will be stated in its section below.
18
+
19
+ | Language | Text source | Verified against an official version |
20
+ | --- | --- | --- |
21
+ | en | Reproduced from the original published instrument | Yes |
22
+ | tr | AI translation (Anthropic Claude, `claude-fable-5`) from the original English | No |
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 |
26
+
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.
12
28
 
13
29
  ## PHQ-9 — Patient Health Questionnaire-9 (`phq9`)
14
30
 
15
- - **Original:** Kroenke, K., Spitzer, R. L., & Williams, J. B. W. (2001). The PHQ-9: Validity of a brief depression severity measure. *Journal of General Internal Medicine, 16*(9), 606–613.
16
- - **Rights:** Developed with an educational grant from Pfizer Inc.; free to use, no permission required. Official screener repository: <https://www.phqscreeners.com>.
17
- - **Translations:** Turkish and German texts follow the validated translations distributed via the official PHQ screeners; the German wording follows the PHQ-D (Löwe et al.).
18
- - **Scoring:** Sum of 9 items (0–27); severity bands per Kroenke et al. (2001). Item 9 (self-harm ideation) raises a `suicidality` flag — this threshold behavior is an implementation aid, not part of the published instrument.
31
+ **License: Free.** Developed with an educational grant from Pfizer Inc. The copyright holders state that no permission is required to reproduce, translate, display, or distribute the PHQ screeners. Official repository: <https://www.phqscreeners.com>.
32
+
33
+ - **Citation:** Kroenke, K., Spitzer, R. L., & Williams, J. B. W. (2001). The PHQ-9: Validity of a brief depression severity measure. *Journal of General Internal Medicine, 16*(9), 606–613.
34
+ - **Scoring:** Sum 0–27; severity bands per Kroenke et al. (2001). The item-9 `suicidality` flag is an implementation aid, not part of the published instrument.
19
35
 
20
36
  ## GAD-7 — Generalized Anxiety Disorder Scale (`gad7`)
21
37
 
22
- - **Original:** Spitzer, R. L., Kroenke, K., Williams, J. B. W., & Löwe, B. (2006). A brief measure for assessing generalized anxiety disorder: The GAD-7. *Archives of Internal Medicine, 166*(10), 1092–1097.
23
- - **Rights:** Developed with an educational grant from Pfizer Inc.; free to use, no permission required. Official screener repository: <https://www.phqscreeners.com>.
24
- - **Translations:** Turkish text follows the validated Turkish adaptation (Konkan et al., 2013); German text follows the validated German version (Löwe et al., 2008).
25
- - **Scoring:** Sum of 7 items (0–21); severity bands per Spitzer et al. (2006).
38
+ **License: Free.** Same rights statement and repository as the PHQ-9 (Pfizer educational grant; no permission required).
39
+
40
+ - **Citation:** Spitzer, R. L., Kroenke, K., Williams, J. B. W., & Löwe, B. (2006). A brief measure for assessing generalized anxiety disorder: The GAD-7. *Archives of Internal Medicine, 166*(10), 1092–1097.
41
+ - **Scoring:** Sum 0–21; severity bands per Spitzer et al. (2006).
42
+
43
+ ## DASS-21 — Depression Anxiety Stress Scales, short form (`dass21`)
44
+
45
+ **License: Free.** The official DASS site states the questionnaires and their translations are in the public domain and may be used without permission. Official site: <http://www2.psy.unsw.edu.au/dass/>.
46
+
47
+ - **Citation:** Lovibond, S. H., & Lovibond, P. F. (1995). *Manual for the Depression Anxiety Stress Scales* (2nd ed.). Sydney: Psychology Foundation of Australia.
48
+ - **Scoring:** Three 7-item subscales; sums doubled to match DASS-42 severity cutoffs, per the DASS manual.
26
49
 
27
50
  ## WHO-5 — World Health Organization Well-Being Index (`who5`)
28
51
 
29
- - **Original:** WHO Regional Office for Europe / Psychiatric Research Unit, Hillerød (1998 revision). Review: Topp, C. W., Østergaard, S. D., Søndergaard, S., & Bech, P. (2015). The WHO-5 Well-Being Index: A systematic review of the literature. *Psychotherapy and Psychosomatics, 84*(3), 167–176.
30
- - **Rights:** Free to use without permission; official translations are distributed by the Psychiatric Research Unit.
31
- - **Translations:** Turkish text follows the validated Turkish version (Eser et al., 2019); German text follows the official German version distributed by the Psychiatric Research Unit.
32
- - **Scoring:** Raw sum (0–25) multiplied by 4 and reported as 0–100; higher is better. Cutoffs (≤50 reduced well-being, ≤28 likely depression) per Topp et al. (2015).
52
+ **License: Free.** The WHO-5 may be used without permission; official versions and translations are distributed by the Psychiatric Research Unit, Mental Health Centre North Zealand (on behalf of the WHO Regional Office for Europe).
53
+
54
+ - **Citation:** Topp, C. W., Østergaard, S. D., Søndergaard, S., & Bech, P. (2015). The WHO-5 Well-Being Index: A systematic review of the literature. *Psychotherapy and Psychosomatics, 84*(3), 167–176.
55
+ - **Scoring:** Raw sum (0–25) × 4, reported 0–100 (higher is better); cutoffs (≤50 reduced well-being, ≤28 likely depression) per Topp et al. (2015).
56
+
57
+ ## AUDIT — Alcohol Use Disorders Identification Test (`audit`)
58
+
59
+ **License: Free.** Developed by the World Health Organization; the WHO's AUDIT manual permits reproduction and use of the questionnaire without permission.
60
+
61
+ - **Citation:** Babor, T. F., Higgins-Biddle, J. C., Saunders, J. B., & Monteiro, M. G. (2001). *AUDIT: The Alcohol Use Disorders Identification Test — Guidelines for Use in Primary Care* (2nd ed.). Geneva: World Health Organization.
62
+ - **Scoring:** Sum 0–40 with item-specific point systems (items 1–8 score 0–4, items 9–10 score 0/2/4); interpreted in the four risk zones of the WHO manual.
63
+
64
+ ## Mini-IPIP — Big Five personality scale (`mini-ipip`)
65
+
66
+ **License: Free.** The International Personality Item Pool (Lewis Goldberg; <https://ipip.ori.org>) was created explicitly as a public-domain alternative to copyrighted commercial personality tests — items are free for any use, including commercial, without permission.
67
+
68
+ - **Citation:** Donnellan, M. B., Oswald, F. L., Baird, B. M., & Lucas, R. E. (2006). The Mini-IPIP scales: Tiny-yet-effective measures of the Big Five factors of personality. *Psychological Assessment, 18*(2), 192–203.
69
+ - **Scoring:** Five trait subscales (extraversion, agreeableness, conscientiousness, neuroticism, openness) of 4 items each on a 1–5 accuracy scale, half reverse-keyed; scores 4–20 per trait are descriptive — no clinical cutoffs exist, so no bands are defined.
33
70
 
34
71
  ## ASRS v1.1 — Adult ADHD Self-Report Scale, 6-item screener (`asrs6`)
35
72
 
36
- - **Original:** Kessler, R. C., Adler, L., Ames, M., Demler, O., Faraone, S., Hiripi, E., et al. (2005). The World Health Organization Adult ADHD Self-Report Scale (ASRS): A short screening scale for use in the general population. *Psychological Medicine, 35*(2), 245–256. Developed by the WHO and the Workgroup on Adult ADHD.
37
- - **Rights:** Free to reproduce, distribute, and score.
38
- - **Translations:** Turkish text follows the validated Turkish adaptation (Doğan et al., 2009); German text follows the WHO's German ASRS-v1.1 distribution.
39
- - **Scoring:** Count of screen-positive items — items 1–3 from "Sometimes", items 4–6 from "Often"; 4 or more positives indicate symptoms highly consistent with adult ADHD, per the ASRS-v1.1 screener key.
73
+ **License: Free with conditions.** Copyright is held by the World Health Organization and the Workgroup on Adult ADHD (Harvard Medical School / NYU). The screener is distributed free of charge for clinical and research use. Embedding in commercial products is not explicitly covered by the public distribution terms — verify with the rights holders (Harvard NCS/ASRS distribution) before shipping commercially.
40
74
 
41
- ## AQ-10 — Autism Spectrum Quotient, 10-item adult version (`aq10`)
75
+ - **Citation:** Kessler, R. C., Adler, L., Ames, M., Demler, O., Faraone, S., Hiripi, E., et al. (2005). The World Health Organization Adult ADHD Self-Report Scale (ASRS): A short screening scale for use in the general population. *Psychological Medicine, 35*(2), 245–256.
76
+ - **Scoring:** Count of screen-positive items (items 1–3 from "Sometimes", items 4–6 from "Often"); ≥4 positives = positive screen, per the ASRS-v1.1 screener key.
42
77
 
43
- - **Original:** 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. Distributed by the Autism Research Centre, University of Cambridge; recommended by NICE (CG142) for adult screening.
44
- - **Rights:** Free to use for clinical and research purposes.
45
- - **Translations:** Turkish text follows the Turkish adaptation of the Autism Spectrum Quotient (Köse et al.); German text follows the published German AQ translations. Both were condensed to the AQ-10 item set — treat them as provisional and verify before clinical use.
46
- - **Scoring:** 1 point per item answered in the trait direction (agree on items 1, 7, 8, 10; disagree on items 2–6 and 9); a total of 6 or more suggests referral for specialist assessment, per Allison et al. (2012).
78
+ ## AQ-10 — Autism Spectrum Quotient, 10-item adult version (`aq10`)
47
79
 
48
- ## DASS-21 — Depression Anxiety Stress Scales, short form (`dass21`)
80
+ **License: Free with conditions.** Copyright is held by the Autism Research Centre (ARC), University of Cambridge. ARC distributes its measures free of charge and the AQ-10 is recommended by NICE (CG142) for adult screening in clinical practice. Commercial redistribution is not explicitly licensed — verify with ARC before shipping commercially.
49
81
 
50
- - **Original:** Lovibond, S. H., & Lovibond, P. F. (1995). *Manual for the Depression Anxiety Stress Scales* (2nd ed.). Sydney: Psychology Foundation of Australia.
51
- - **Rights:** Public domain per the authors; official site and translation index: <http://www2.psy.unsw.edu.au/dass/>.
52
- - **Translations:** Turkish text follows the validated short-form adaptation (Sarıçam, 2018); German text follows the published German DASS (Nilges & Essau, 2015).
53
- - **Scoring:** Three 7-item subscales (depression, anxiety, stress); sums doubled to match DASS-42 severity cutoffs, per the DASS manual.
82
+ - **Citation:** 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.
83
+ - **Scoring:** 1 point per item in the trait direction (agree on items 1, 7, 8, 10; disagree on the rest); ≥6 suggests specialist referral, per Allison et al. (2012).
@@ -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";
7
- export { phq9, gad7, dass21, who5, asrs6, aq10, inventories, loadInventory, twoWeekFrequencyOptions, twoWeekInstructions, } from "./inventories/index.ts";
8
+ export type { EvaluateOptions } from "./evaluation.ts";
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.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; } });
@@ -20,6 +20,8 @@ Object.defineProperty(exports, "dass21", { enumerable: true, get: function () {
20
20
  Object.defineProperty(exports, "who5", { enumerable: true, get: function () { return index_ts_1.who5; } });
21
21
  Object.defineProperty(exports, "asrs6", { enumerable: true, get: function () { return index_ts_1.asrs6; } });
22
22
  Object.defineProperty(exports, "aq10", { enumerable: true, get: function () { return index_ts_1.aq10; } });
23
+ Object.defineProperty(exports, "audit", { enumerable: true, get: function () { return index_ts_1.audit; } });
24
+ Object.defineProperty(exports, "miniIpip", { enumerable: true, get: function () { return index_ts_1.miniIpip; } });
23
25
  Object.defineProperty(exports, "inventories", { enumerable: true, get: function () { return index_ts_1.inventories; } });
24
26
  Object.defineProperty(exports, "loadInventory", { enumerable: true, get: function () { return index_ts_1.loadInventory; } });
25
27
  Object.defineProperty(exports, "twoWeekFrequencyOptions", { enumerable: true, get: function () { return index_ts_1.twoWeekFrequencyOptions; } });