psytools 0.5.1 → 0.5.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +23 -2
- package/SOURCES.md +2 -0
- package/dist/cjs/inventories/index.d.ts +10 -2
- package/dist/cjs/inventories/index.js +16 -1
- package/dist/cjs/types.d.ts +7 -3
- package/dist/esm/inventories/index.d.ts +10 -2
- package/dist/esm/inventories/index.js +16 -1
- package/dist/esm/types.d.ts +7 -3
- package/package.json +1 -1
- package/src/inventories/index.ts +18 -3
- package/src/types.ts +7 -3
package/README.md
CHANGED
|
@@ -169,6 +169,27 @@ Minimization is the default, at every layer:
|
|
|
169
169
|
|
|
170
170
|
Merged definitions remain one self-contained JSON object — locale loading never breaks the `stringify → DB → parse` round trip.
|
|
171
171
|
|
|
172
|
+
### Local translation overrides
|
|
173
|
+
|
|
174
|
+
The bundled translations are unverified AI output (see [Translation provenance](#important-notes) below) — you may want to reword a specific question, option label, or instruction locally without forking the inventory. `loadInventory` accepts `overrides`: one or more partial locale packs, applied **after** the built-in packs, later-wins:
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
const phq9 = await loadInventory("phq9", {
|
|
178
|
+
locales: ["tr"],
|
|
179
|
+
overrides: {
|
|
180
|
+
id: "phq9",
|
|
181
|
+
locale: "tr",
|
|
182
|
+
// Only the bits you want to change — everything else keeps the
|
|
183
|
+
// bundled tr text (or falls back to English if tr was never loaded).
|
|
184
|
+
questions: {
|
|
185
|
+
"phq9-3": { text: "Uykuya dalmakta veya uykuyu sürdürmekte güçlük" },
|
|
186
|
+
},
|
|
187
|
+
},
|
|
188
|
+
});
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
An override pack has the same shape as a bundled `InventoryLocalePack` (see [`applyLocale`](#data-minimization) above), but every field except `id`/`locale`/`questions` is optional, and `questions` only needs entries for what you're changing. Pass an array to apply several overrides in order; option-count mismatches and unknown question ids still throw `invalid_argument`, same as a bundled pack. This is a local, in-memory concern — psytools doesn't track override provenance or verification status; that's still on you and your own docs.
|
|
192
|
+
|
|
172
193
|
### Missing answers
|
|
173
194
|
|
|
174
195
|
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`):
|
|
@@ -224,7 +245,7 @@ const history = rows
|
|
|
224
245
|
| `AssessmentResponse` | `answer()`, `answerAll()`, `clearAnswer()`, `status`, `progress()`, `validate()`, `submit()`, `stringify()`/`parse()` |
|
|
225
246
|
| `evaluate(definition, answers, { evaluator? })` | Standalone scoring (also available as `Assessment#evaluate`) |
|
|
226
247
|
| `validateDefinition(input)` | Non-throwing structural validation of definitions |
|
|
227
|
-
| `loadInventory(id, { locales? })` / `inventories` | Predefined instruments (async; English-only base definitions also exported by name) |
|
|
248
|
+
| `loadInventory(id, { locales?, overrides? })` / `inventories` | Predefined instruments (async; English-only base definitions also exported by name); `overrides` applies local partial locale packs after the built-in ones |
|
|
228
249
|
| `applyLocale(definition, pack)` / `availableLocales(id)` / `localePacks` | Lazy per-inventory locale packs |
|
|
229
250
|
| `localizeText(text, locale, fallback?)` / `collectLocales(texts)` / `pickLocales(definition, locales)` | Locale helpers |
|
|
230
251
|
| `PsytoolsError` | All errors carry a `code` typed as `PsytoolsErrorCode` (e.g. `invalid_value`, `already_submitted`) |
|
|
@@ -242,7 +263,7 @@ npm run build # ESM + CJS + type declarations into dist/
|
|
|
242
263
|
- **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.
|
|
243
264
|
- **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.
|
|
244
265
|
- **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.
|
|
245
|
-
- **Translation provenance.** English texts are reproduced from the original instruments. Turkish and
|
|
266
|
+
- **Translation provenance.** English texts are reproduced from the original instruments. Turkish, German, Simplified Chinese, and Spanish texts are AI translations (Anthropic Claude, model `claude-fable-5`) of the original English — official translations were **not** consulted and the texts are unverified. This status is documentation-only: psytools does not track or expose per-pack verification programmatically (no `verified` field, no gating option, no status API) — read [SOURCES.md](SOURCES.md) and decide for yourself whether the bundled wording is fit for your use case. If it isn't for a specific item, use [local overrides](#local-translation-overrides) rather than forking the package. Obtain and compare the official version for your language before clinical use. Corrections: <samed@luckys.dev>.
|
|
246
267
|
|
|
247
268
|
## License
|
|
248
269
|
|
package/SOURCES.md
CHANGED
|
@@ -28,6 +28,8 @@ Official validated translations exist for most of these instruments, but they we
|
|
|
28
28
|
|
|
29
29
|
Non-English texts live as one file per inventory per language under [`src/locales/<locale>/`](src/locales) — exactly the unit a native-speaker reviewer needs. Verification contributions are very welcome.
|
|
30
30
|
|
|
31
|
+
This table is the only place translation status is tracked — psytools has no `verified` field, no gating option, and no API to query pack status at runtime; that would overstate a confidence level nobody has confirmed. If you've corrected a specific item's wording for your own use and don't want to wait on an upstream fix, apply it locally with `loadInventory(id, { overrides })` (see the README's [local translation overrides](README.md#local-translation-overrides)) rather than forking the package — or, better, send the correction upstream so everyone benefits.
|
|
32
|
+
|
|
31
33
|
## Missing-data policies
|
|
32
34
|
|
|
33
35
|
Bundled inventories ship with declarative missing-data policies (`scoring.missing`). **The prorating thresholds are implementation choices reflecting common research practice — they are not part of the instruments' official scoring rules.** Override by cloning the definition if your protocol differs.
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { AssessmentDefinition } from "../types.ts";
|
|
1
|
+
import type { AssessmentDefinition, InventoryLocalePack } from "../types.ts";
|
|
2
2
|
import { Assessment } from "../assessment.ts";
|
|
3
3
|
import { phq9 } from "./phq9.ts";
|
|
4
4
|
import { gad7 } from "./gad7.ts";
|
|
@@ -22,8 +22,16 @@ export type InventoryId = "phq9" | "gad7" | "dass21" | "who5" | "asrs6" | "aq10"
|
|
|
22
22
|
* default). The returned assessment's definition is still one complete,
|
|
23
23
|
* serializable JSON object containing exactly the requested locales.
|
|
24
24
|
*
|
|
25
|
-
*
|
|
25
|
+
* `options.overrides` applies one or more local, partial locale packs
|
|
26
|
+
* (same shape as the bundled ones) after the built-in packs, so a consumer
|
|
27
|
+
* can reword specific questions/options/instructions without forking the
|
|
28
|
+
* inventory. Later overrides win over earlier ones and over the built-in
|
|
29
|
+
* text; each is validated exactly like a bundled pack (unknown question
|
|
30
|
+
* ids and option-count mismatches still throw `invalid_argument`).
|
|
31
|
+
*
|
|
32
|
+
* @throws PsytoolsError `unknown_inventory` | `unknown_locale` | `invalid_argument`
|
|
26
33
|
*/
|
|
27
34
|
export declare function loadInventory(id: InventoryId | string, options?: {
|
|
28
35
|
locales?: string[];
|
|
36
|
+
overrides?: InventoryLocalePack | InventoryLocalePack[];
|
|
29
37
|
}): Promise<Assessment>;
|
|
@@ -45,7 +45,14 @@ exports.inventories = {
|
|
|
45
45
|
* default). The returned assessment's definition is still one complete,
|
|
46
46
|
* serializable JSON object containing exactly the requested locales.
|
|
47
47
|
*
|
|
48
|
-
*
|
|
48
|
+
* `options.overrides` applies one or more local, partial locale packs
|
|
49
|
+
* (same shape as the bundled ones) after the built-in packs, so a consumer
|
|
50
|
+
* can reword specific questions/options/instructions without forking the
|
|
51
|
+
* inventory. Later overrides win over earlier ones and over the built-in
|
|
52
|
+
* text; each is validated exactly like a bundled pack (unknown question
|
|
53
|
+
* ids and option-count mismatches still throw `invalid_argument`).
|
|
54
|
+
*
|
|
55
|
+
* @throws PsytoolsError `unknown_inventory` | `unknown_locale` | `invalid_argument`
|
|
49
56
|
*/
|
|
50
57
|
async function loadInventory(id, options) {
|
|
51
58
|
const definition = exports.inventories[id];
|
|
@@ -63,5 +70,13 @@ async function loadInventory(id, options) {
|
|
|
63
70
|
}
|
|
64
71
|
merged = (0, i18n_ts_1.applyLocale)(merged, (await loader()).default);
|
|
65
72
|
}
|
|
73
|
+
const overrides = options?.overrides
|
|
74
|
+
? Array.isArray(options.overrides)
|
|
75
|
+
? options.overrides
|
|
76
|
+
: [options.overrides]
|
|
77
|
+
: [];
|
|
78
|
+
for (const override of overrides) {
|
|
79
|
+
merged = (0, i18n_ts_1.applyLocale)(merged, override);
|
|
80
|
+
}
|
|
66
81
|
return new assessment_ts_1.Assessment(merged);
|
|
67
82
|
}
|
package/dist/cjs/types.d.ts
CHANGED
|
@@ -161,17 +161,21 @@ export interface AssessmentDefinition {
|
|
|
161
161
|
* One language for one inventory, shipped as a separate lazily-loadable
|
|
162
162
|
* module so that only requested locales are bundled and held in memory.
|
|
163
163
|
* Merge into a base definition with `applyLocale`.
|
|
164
|
+
*
|
|
165
|
+
* Packs are partial: every field but `id`/`locale` is optional, so the same
|
|
166
|
+
* shape also works as a small local override (e.g. reword one question) via
|
|
167
|
+
* `loadInventory(id, { overrides })` — no need to restate the whole pack.
|
|
164
168
|
*/
|
|
165
169
|
export interface InventoryLocalePack {
|
|
166
170
|
/** Id of the inventory this pack translates. */
|
|
167
171
|
id: string;
|
|
168
172
|
/** BCP-47 language tag of the pack, e.g. `"tr"`. */
|
|
169
173
|
locale: string;
|
|
170
|
-
title
|
|
174
|
+
title?: string;
|
|
171
175
|
description?: string;
|
|
172
176
|
instructions?: string;
|
|
173
|
-
/** Labels of the assessment-level option scale, by option index. */
|
|
174
|
-
options
|
|
177
|
+
/** Labels of the assessment-level option scale, by option index. Length must match the option scale's when present. */
|
|
178
|
+
options?: string[];
|
|
175
179
|
/** Per-question texts (and option labels for question-level scales), by question id. */
|
|
176
180
|
questions: Record<string, {
|
|
177
181
|
text: string;
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { AssessmentDefinition } from "../types.ts";
|
|
1
|
+
import type { AssessmentDefinition, InventoryLocalePack } from "../types.ts";
|
|
2
2
|
import { Assessment } from "../assessment.ts";
|
|
3
3
|
import { phq9 } from "./phq9.ts";
|
|
4
4
|
import { gad7 } from "./gad7.ts";
|
|
@@ -22,8 +22,16 @@ export type InventoryId = "phq9" | "gad7" | "dass21" | "who5" | "asrs6" | "aq10"
|
|
|
22
22
|
* default). The returned assessment's definition is still one complete,
|
|
23
23
|
* serializable JSON object containing exactly the requested locales.
|
|
24
24
|
*
|
|
25
|
-
*
|
|
25
|
+
* `options.overrides` applies one or more local, partial locale packs
|
|
26
|
+
* (same shape as the bundled ones) after the built-in packs, so a consumer
|
|
27
|
+
* can reword specific questions/options/instructions without forking the
|
|
28
|
+
* inventory. Later overrides win over earlier ones and over the built-in
|
|
29
|
+
* text; each is validated exactly like a bundled pack (unknown question
|
|
30
|
+
* ids and option-count mismatches still throw `invalid_argument`).
|
|
31
|
+
*
|
|
32
|
+
* @throws PsytoolsError `unknown_inventory` | `unknown_locale` | `invalid_argument`
|
|
26
33
|
*/
|
|
27
34
|
export declare function loadInventory(id: InventoryId | string, options?: {
|
|
28
35
|
locales?: string[];
|
|
36
|
+
overrides?: InventoryLocalePack | InventoryLocalePack[];
|
|
29
37
|
}): Promise<Assessment>;
|
|
@@ -32,7 +32,14 @@ export const inventories = {
|
|
|
32
32
|
* default). The returned assessment's definition is still one complete,
|
|
33
33
|
* serializable JSON object containing exactly the requested locales.
|
|
34
34
|
*
|
|
35
|
-
*
|
|
35
|
+
* `options.overrides` applies one or more local, partial locale packs
|
|
36
|
+
* (same shape as the bundled ones) after the built-in packs, so a consumer
|
|
37
|
+
* can reword specific questions/options/instructions without forking the
|
|
38
|
+
* inventory. Later overrides win over earlier ones and over the built-in
|
|
39
|
+
* text; each is validated exactly like a bundled pack (unknown question
|
|
40
|
+
* ids and option-count mismatches still throw `invalid_argument`).
|
|
41
|
+
*
|
|
42
|
+
* @throws PsytoolsError `unknown_inventory` | `unknown_locale` | `invalid_argument`
|
|
36
43
|
*/
|
|
37
44
|
export async function loadInventory(id, options) {
|
|
38
45
|
const definition = inventories[id];
|
|
@@ -50,5 +57,13 @@ export async function loadInventory(id, options) {
|
|
|
50
57
|
}
|
|
51
58
|
merged = applyLocale(merged, (await loader()).default);
|
|
52
59
|
}
|
|
60
|
+
const overrides = options?.overrides
|
|
61
|
+
? Array.isArray(options.overrides)
|
|
62
|
+
? options.overrides
|
|
63
|
+
: [options.overrides]
|
|
64
|
+
: [];
|
|
65
|
+
for (const override of overrides) {
|
|
66
|
+
merged = applyLocale(merged, override);
|
|
67
|
+
}
|
|
53
68
|
return new Assessment(merged);
|
|
54
69
|
}
|
package/dist/esm/types.d.ts
CHANGED
|
@@ -161,17 +161,21 @@ export interface AssessmentDefinition {
|
|
|
161
161
|
* One language for one inventory, shipped as a separate lazily-loadable
|
|
162
162
|
* module so that only requested locales are bundled and held in memory.
|
|
163
163
|
* Merge into a base definition with `applyLocale`.
|
|
164
|
+
*
|
|
165
|
+
* Packs are partial: every field but `id`/`locale` is optional, so the same
|
|
166
|
+
* shape also works as a small local override (e.g. reword one question) via
|
|
167
|
+
* `loadInventory(id, { overrides })` — no need to restate the whole pack.
|
|
164
168
|
*/
|
|
165
169
|
export interface InventoryLocalePack {
|
|
166
170
|
/** Id of the inventory this pack translates. */
|
|
167
171
|
id: string;
|
|
168
172
|
/** BCP-47 language tag of the pack, e.g. `"tr"`. */
|
|
169
173
|
locale: string;
|
|
170
|
-
title
|
|
174
|
+
title?: string;
|
|
171
175
|
description?: string;
|
|
172
176
|
instructions?: string;
|
|
173
|
-
/** Labels of the assessment-level option scale, by option index. */
|
|
174
|
-
options
|
|
177
|
+
/** Labels of the assessment-level option scale, by option index. Length must match the option scale's when present. */
|
|
178
|
+
options?: string[];
|
|
175
179
|
/** Per-question texts (and option labels for question-level scales), by question id. */
|
|
176
180
|
questions: Record<string, {
|
|
177
181
|
text: string;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "psytools",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.2",
|
|
4
4
|
"description": "Zero-dependency toolkit for psychological assessments: data models, response validation, scoring, and predefined inventories (PHQ-9, GAD-7, DASS-21, WHO-5, ASRS, AQ-10, AUDIT, Mini-IPIP) in multiple languages.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"psychology",
|
package/src/inventories/index.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { AssessmentDefinition } from "../types.ts";
|
|
1
|
+
import type { AssessmentDefinition, InventoryLocalePack } from "../types.ts";
|
|
2
2
|
import { Assessment } from "../assessment.ts";
|
|
3
3
|
import { PsytoolsError } from "../errors.ts";
|
|
4
4
|
import { applyLocale } from "../i18n.ts";
|
|
@@ -46,11 +46,18 @@ export type InventoryId =
|
|
|
46
46
|
* default). The returned assessment's definition is still one complete,
|
|
47
47
|
* serializable JSON object containing exactly the requested locales.
|
|
48
48
|
*
|
|
49
|
-
*
|
|
49
|
+
* `options.overrides` applies one or more local, partial locale packs
|
|
50
|
+
* (same shape as the bundled ones) after the built-in packs, so a consumer
|
|
51
|
+
* can reword specific questions/options/instructions without forking the
|
|
52
|
+
* inventory. Later overrides win over earlier ones and over the built-in
|
|
53
|
+
* text; each is validated exactly like a bundled pack (unknown question
|
|
54
|
+
* ids and option-count mismatches still throw `invalid_argument`).
|
|
55
|
+
*
|
|
56
|
+
* @throws PsytoolsError `unknown_inventory` | `unknown_locale` | `invalid_argument`
|
|
50
57
|
*/
|
|
51
58
|
export async function loadInventory(
|
|
52
59
|
id: InventoryId | string,
|
|
53
|
-
options?: { locales?: string[] },
|
|
60
|
+
options?: { locales?: string[]; overrides?: InventoryLocalePack | InventoryLocalePack[] },
|
|
54
61
|
): Promise<Assessment> {
|
|
55
62
|
const definition = inventories[id];
|
|
56
63
|
if (!definition) {
|
|
@@ -69,5 +76,13 @@ export async function loadInventory(
|
|
|
69
76
|
}
|
|
70
77
|
merged = applyLocale(merged, (await loader()).default);
|
|
71
78
|
}
|
|
79
|
+
const overrides = options?.overrides
|
|
80
|
+
? Array.isArray(options.overrides)
|
|
81
|
+
? options.overrides
|
|
82
|
+
: [options.overrides]
|
|
83
|
+
: [];
|
|
84
|
+
for (const override of overrides) {
|
|
85
|
+
merged = applyLocale(merged, override);
|
|
86
|
+
}
|
|
72
87
|
return new Assessment(merged);
|
|
73
88
|
}
|
package/src/types.ts
CHANGED
|
@@ -176,17 +176,21 @@ export interface AssessmentDefinition {
|
|
|
176
176
|
* One language for one inventory, shipped as a separate lazily-loadable
|
|
177
177
|
* module so that only requested locales are bundled and held in memory.
|
|
178
178
|
* Merge into a base definition with `applyLocale`.
|
|
179
|
+
*
|
|
180
|
+
* Packs are partial: every field but `id`/`locale` is optional, so the same
|
|
181
|
+
* shape also works as a small local override (e.g. reword one question) via
|
|
182
|
+
* `loadInventory(id, { overrides })` — no need to restate the whole pack.
|
|
179
183
|
*/
|
|
180
184
|
export interface InventoryLocalePack {
|
|
181
185
|
/** Id of the inventory this pack translates. */
|
|
182
186
|
id: string;
|
|
183
187
|
/** BCP-47 language tag of the pack, e.g. `"tr"`. */
|
|
184
188
|
locale: string;
|
|
185
|
-
title
|
|
189
|
+
title?: string;
|
|
186
190
|
description?: string;
|
|
187
191
|
instructions?: string;
|
|
188
|
-
/** Labels of the assessment-level option scale, by option index. */
|
|
189
|
-
options
|
|
192
|
+
/** Labels of the assessment-level option scale, by option index. Length must match the option scale's when present. */
|
|
193
|
+
options?: string[];
|
|
190
194
|
/** Per-question texts (and option labels for question-level scales), by question id. */
|
|
191
195
|
questions: Record<string, { text: string; options?: string[] }>;
|
|
192
196
|
/** Band labels by band id (sum and count scoring). */
|