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/src/types.ts CHANGED
@@ -63,6 +63,30 @@ export interface ScoreFlag {
63
63
  label: LocalizedText;
64
64
  }
65
65
 
66
+ /** How a scorer treats unanswered items among the ones it uses. */
67
+ export type MissingDataStrategy = "ignore" | "prorate" | "require-complete";
68
+
69
+ /**
70
+ * Missing-data policy for declarative scoring. Applies when incomplete
71
+ * answers reach the scorer (raw answer maps, or `allowIncomplete`).
72
+ *
73
+ * - `ignore` (default): unanswered items contribute nothing — partial
74
+ * totals understate severity, so use deliberately.
75
+ * - `prorate`: the raw score is scaled up by totalItems / answeredItems
76
+ * and rounded before any multiplier, per scale/subscale.
77
+ * - `require-complete`: evaluation throws `incomplete_response` when any
78
+ * contributing item is unanswered.
79
+ */
80
+ export interface MissingDataPolicy {
81
+ strategy: MissingDataStrategy;
82
+ /**
83
+ * Minimum answered contributing items (per scale/subscale) needed to
84
+ * produce a score; below it evaluation throws `incomplete_response`.
85
+ * Defaults to 1 for `prorate`, 0 otherwise.
86
+ */
87
+ minAnswered?: number;
88
+ }
89
+
66
90
  /** Sums all answers into a single total score (PHQ-9, GAD-7, ...). */
67
91
  export interface SumScoring {
68
92
  kind: "sum";
@@ -71,6 +95,7 @@ export interface SumScoring {
71
95
  /** Severity bands the (multiplied) total is matched against. */
72
96
  bands?: ScoreBand[];
73
97
  flags?: ScoreFlag[];
98
+ missing?: MissingDataPolicy;
74
99
  }
75
100
 
76
101
  /** One subscale of a multi-scale scoring definition. */
@@ -90,6 +115,8 @@ export interface SubscaleScoring {
90
115
  kind: "subscales";
91
116
  subscales: SubscaleDefinition[];
92
117
  flags?: ScoreFlag[];
118
+ /** Applied to each subscale independently. */
119
+ missing?: MissingDataPolicy;
93
120
  }
94
121
 
95
122
  /** One item of a `count` scoring: when it counts as screen-positive. */
@@ -112,6 +139,8 @@ export interface CountScoring {
112
139
  /** Bands the positive-item count is matched against. */
113
140
  bands?: ScoreBand[];
114
141
  flags?: ScoreFlag[];
142
+ /** `prorate` scales the positive count by totalItems / answeredItems. */
143
+ missing?: MissingDataPolicy;
115
144
  }
116
145
 
117
146
  /** Declarative, serializable scoring rules built into psytools. */
@@ -172,14 +201,17 @@ export interface ResponseData {
172
201
  meta?: Record<string, unknown>;
173
202
  }
174
203
 
204
+ /** Codes a validation issue can carry (a subset of `PsytoolsErrorCode`). */
205
+ export type ValidationIssueCode =
206
+ | "unknown_question"
207
+ | "invalid_value"
208
+ | "missing_answer"
209
+ | "duplicate_question"
210
+ | "malformed";
211
+
175
212
  /** A single validation problem. */
176
213
  export interface ValidationIssue {
177
- code:
178
- | "unknown_question"
179
- | "invalid_value"
180
- | "missing_answer"
181
- | "duplicate_question"
182
- | "malformed";
214
+ code: ValidationIssueCode;
183
215
  message: string;
184
216
  questionId?: string;
185
217
  }