@clementine-solutions/jane-io 1.0.0 → 1.0.1

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 (205) hide show
  1. package/README.md +132 -1
  2. package/dist/core/analysis/diff.d.ts +35 -0
  3. package/dist/core/analysis/explain.d.ts +35 -0
  4. package/dist/core/analysis/index.d.ts +14 -0
  5. package/dist/core/analysis/replay.d.ts +34 -0
  6. package/dist/core/analysis/telemetry.d.ts +28 -0
  7. package/dist/core/boundary-rules/at-most-one.d.ts +17 -0
  8. package/dist/core/boundary-rules/conditionally-required.d.ts +18 -0
  9. package/dist/core/boundary-rules/date-range.d.ts +17 -0
  10. package/dist/core/boundary-rules/index.d.ts +18 -0
  11. package/dist/core/boundary-rules/mutually-exclusive.d.ts +16 -0
  12. package/dist/core/boundary-rules/no-unknown-fields.d.ts +17 -0
  13. package/dist/core/boundary-rules/require-all.d.ts +16 -0
  14. package/dist/core/boundary-rules/require-one.d.ts +17 -0
  15. package/dist/core/common/events.d.ts +37 -0
  16. package/dist/core/common/fluent.d.ts +151 -0
  17. package/dist/core/common/index.d.ts +16 -0
  18. package/dist/core/common/policy.d.ts +170 -0
  19. package/dist/core/common/utilities.d.ts +59 -0
  20. package/dist/core/common/wildcard.d.ts +27 -0
  21. package/dist/core/field-path/construct.d.ts +77 -0
  22. package/dist/core/field-path/format.d.ts +41 -0
  23. package/dist/core/field-path/index.d.ts +14 -0
  24. package/dist/core/field-path/utilities.d.ts +85 -0
  25. package/dist/core/field-path/walk.d.ts +36 -0
  26. package/dist/core/fluent-registry.d.ts +138 -0
  27. package/dist/core/normalizers/array/compact-sparse-array.d.ts +22 -0
  28. package/dist/core/normalizers/array/flatten-one-level.d.ts +17 -0
  29. package/dist/core/normalizers/array/remove-empty-string-items.d.ts +6 -0
  30. package/dist/core/normalizers/array/remove-null-items.d.ts +16 -0
  31. package/dist/core/normalizers/array/remove-undefined-items.d.ts +16 -0
  32. package/dist/core/normalizers/date/invalid-date-to-undefined.d.ts +17 -0
  33. package/dist/core/normalizers/index.d.ts +28 -0
  34. package/dist/core/normalizers/normalizer-register.d.ts +17 -0
  35. package/dist/core/normalizers/number/infinity-to-undefined.d.ts +18 -0
  36. package/dist/core/normalizers/number/nan-to-undefined.d.ts +17 -0
  37. package/dist/core/normalizers/number/normalize-negative-zero.d.ts +16 -0
  38. package/dist/core/normalizers/object/remove-empty-array-keys.d.ts +17 -0
  39. package/dist/core/normalizers/object/remove-empty-object-keys.d.ts +16 -0
  40. package/dist/core/normalizers/object/remove-empty-string-keys.d.ts +16 -0
  41. package/dist/core/normalizers/object/remove-null-keys.d.ts +16 -0
  42. package/dist/core/normalizers/object/remove-undefined-keys.d.ts +16 -0
  43. package/dist/core/normalizers/string/collapse-whitespace.d.ts +17 -0
  44. package/dist/core/normalizers/string/empty-to-undefined.d.ts +16 -0
  45. package/dist/core/normalizers/string/trim.d.ts +16 -0
  46. package/dist/core/parsers/index.d.ts +22 -0
  47. package/dist/core/parsers/parse-array-string.d.ts +16 -0
  48. package/dist/core/parsers/parse-bigint-string.d.ts +16 -0
  49. package/dist/core/parsers/parse-binary-string.d.ts +16 -0
  50. package/dist/core/parsers/parse-boolean-string.d.ts +16 -0
  51. package/dist/core/parsers/parse-date-string.d.ts +16 -0
  52. package/dist/core/parsers/parse-duration-string.d.ts +16 -0
  53. package/dist/core/parsers/parse-hex-string.d.ts +16 -0
  54. package/dist/core/parsers/parse-integer-string.d.ts +16 -0
  55. package/dist/core/parsers/parse-json-string.d.ts +17 -0
  56. package/dist/core/parsers/parse-numeric-string.d.ts +16 -0
  57. package/dist/core/parsers/parse-object-string.d.ts +16 -0
  58. package/dist/core/parsers/parse-octal-string.d.ts +16 -0
  59. package/dist/core/parsers/parse-scientific-notation-string.d.ts +16 -0
  60. package/dist/core/parsers/parse-url-string.d.ts +16 -0
  61. package/dist/core/pipeline/boundary.d.ts +36 -0
  62. package/dist/core/pipeline/contain.d.ts +122 -0
  63. package/dist/core/pipeline/index.d.ts +16 -0
  64. package/dist/core/pipeline/normalize.d.ts +34 -0
  65. package/dist/core/pipeline/parse.d.ts +40 -0
  66. package/dist/core/pipeline/pipeline.d.ts +23 -0
  67. package/dist/core/pipeline/scan.d.ts +46 -0
  68. package/dist/core/pipeline/validate.d.ts +40 -0
  69. package/dist/core/scanners/any/scan-for-sentinels.d.ts +19 -0
  70. package/dist/core/scanners/array/array-is-deep.d.ts +19 -0
  71. package/dist/core/scanners/array/array-is-heterogenous.d.ts +18 -0
  72. package/dist/core/scanners/array/array-is-large.d.ts +19 -0
  73. package/dist/core/scanners/bigint/bigint-is-large.d.ts +20 -0
  74. package/dist/core/scanners/bigint/bigint-not-safe.d.ts +20 -0
  75. package/dist/core/scanners/date/date-is-before-epoch.d.ts +19 -0
  76. package/dist/core/scanners/date/date-is-far-future.d.ts +19 -0
  77. package/dist/core/scanners/date/date-is-invalid.d.ts +19 -0
  78. package/dist/core/scanners/index.d.ts +31 -0
  79. package/dist/core/scanners/number/number-is-infinite.d.ts +19 -0
  80. package/dist/core/scanners/number/number-is-nan.d.ts +19 -0
  81. package/dist/core/scanners/number/number-is-too-large.d.ts +20 -0
  82. package/dist/core/scanners/number/number-is-unsafe-integer.d.ts +19 -0
  83. package/dist/core/scanners/object/object-has-circular-references.d.ts +20 -0
  84. package/dist/core/scanners/object/object-has-many-keys.d.ts +19 -0
  85. package/dist/core/scanners/object/object-is-deep.d.ts +20 -0
  86. package/dist/core/scanners/scanner-registry.d.ts +19 -0
  87. package/dist/core/scanners/string/string-has-unsafe-unicode.d.ts +19 -0
  88. package/dist/core/scanners/string/string-has-whitespace-edges.d.ts +19 -0
  89. package/dist/core/scanners/string/string-is-long.d.ts +19 -0
  90. package/dist/core/scanners/unknown/unknown-not-scannable.d.ts +21 -0
  91. package/dist/core/shapes/analysis.d.ts +239 -0
  92. package/dist/core/shapes/boundary.d.ts +126 -0
  93. package/dist/core/shapes/events.d.ts +83 -0
  94. package/dist/core/shapes/field-path.d.ts +51 -0
  95. package/dist/core/shapes/index.d.ts +21 -0
  96. package/dist/core/shapes/normalize.d.ts +59 -0
  97. package/dist/core/shapes/parse.d.ts +75 -0
  98. package/dist/core/shapes/pipeline.d.ts +149 -0
  99. package/dist/core/shapes/policy.d.ts +158 -0
  100. package/dist/core/shapes/public.d.ts +92 -0
  101. package/dist/core/shapes/scan.d.ts +126 -0
  102. package/dist/core/shapes/validate.d.ts +65 -0
  103. package/dist/core/validators/array/array-max-items.d.ts +25 -0
  104. package/dist/core/validators/array/array-min-items.d.ts +25 -0
  105. package/dist/core/validators/array/array.d.ts +22 -0
  106. package/dist/core/validators/array/excludes.d.ts +25 -0
  107. package/dist/core/validators/array/has-unique-items.d.ts +24 -0
  108. package/dist/core/validators/array/includes.d.ts +24 -0
  109. package/dist/core/validators/array/items-equal.d.ts +25 -0
  110. package/dist/core/validators/array/no-empty-string-items.d.ts +24 -0
  111. package/dist/core/validators/array/no-null-items.d.ts +24 -0
  112. package/dist/core/validators/array/no-undefined-items.d.ts +24 -0
  113. package/dist/core/validators/array/non-empty-array.d.ts +24 -0
  114. package/dist/core/validators/array/not-sparse.d.ts +25 -0
  115. package/dist/core/validators/bigint/bigint-equals.d.ts +24 -0
  116. package/dist/core/validators/bigint/bigint-max.d.ts +25 -0
  117. package/dist/core/validators/bigint/bigint-min.d.ts +25 -0
  118. package/dist/core/validators/bigint/bigint-negative.d.ts +23 -0
  119. package/dist/core/validators/bigint/bigint-non-negative.d.ts +24 -0
  120. package/dist/core/validators/bigint/bigint-non-positive.d.ts +24 -0
  121. package/dist/core/validators/bigint/bigint-positive.d.ts +24 -0
  122. package/dist/core/validators/bigint/bigint-safe.d.ts +25 -0
  123. package/dist/core/validators/bigint/bigint.d.ts +20 -0
  124. package/dist/core/validators/boolean/boolean.d.ts +21 -0
  125. package/dist/core/validators/boolean/is-false.d.ts +22 -0
  126. package/dist/core/validators/boolean/is-true.d.ts +22 -0
  127. package/dist/core/validators/common/is-country-code.d.ts +17 -0
  128. package/dist/core/validators/common/is-currency-code.d.ts +17 -0
  129. package/dist/core/validators/common/is-email-strict.d.ts +17 -0
  130. package/dist/core/validators/common/is-email.d.ts +17 -0
  131. package/dist/core/validators/common/is-ip.d.ts +17 -0
  132. package/dist/core/validators/common/is-phone-strict.d.ts +17 -0
  133. package/dist/core/validators/common/is-phone.d.ts +17 -0
  134. package/dist/core/validators/common/is-port.d.ts +17 -0
  135. package/dist/core/validators/common/is-postal-code.d.ts +17 -0
  136. package/dist/core/validators/common/is-url.d.ts +17 -0
  137. package/dist/core/validators/common/is-uuid.d.ts +17 -0
  138. package/dist/core/validators/date/before-epoch.d.ts +28 -0
  139. package/dist/core/validators/date/date-now-required.d.ts +22 -0
  140. package/dist/core/validators/date/is-date.d.ts +21 -0
  141. package/dist/core/validators/date/is-far-future.d.ts +23 -0
  142. package/dist/core/validators/date/is-future.d.ts +24 -0
  143. package/dist/core/validators/date/is-past.d.ts +24 -0
  144. package/dist/core/validators/date/not-after.d.ts +25 -0
  145. package/dist/core/validators/date/not-before.d.ts +25 -0
  146. package/dist/core/validators/date/same-day.d.ts +25 -0
  147. package/dist/core/validators/date/same-month.d.ts +25 -0
  148. package/dist/core/validators/date/same-year.d.ts +24 -0
  149. package/dist/core/validators/date/too-early.d.ts +25 -0
  150. package/dist/core/validators/date/too-late.d.ts +25 -0
  151. package/dist/core/validators/date/weekday.d.ts +32 -0
  152. package/dist/core/validators/date/weekend.d.ts +27 -0
  153. package/dist/core/validators/index.d.ts +112 -0
  154. package/dist/core/validators/nullish/is-null-or-undefined.d.ts +22 -0
  155. package/dist/core/validators/nullish/is-null.d.ts +21 -0
  156. package/dist/core/validators/nullish/is-undefined.d.ts +21 -0
  157. package/dist/core/validators/number/finite.d.ts +22 -0
  158. package/dist/core/validators/number/integer.d.ts +22 -0
  159. package/dist/core/validators/number/less-than.d.ts +21 -0
  160. package/dist/core/validators/number/max.d.ts +21 -0
  161. package/dist/core/validators/number/min.d.ts +21 -0
  162. package/dist/core/validators/number/more-than.d.ts +21 -0
  163. package/dist/core/validators/number/negative.d.ts +20 -0
  164. package/dist/core/validators/number/non-negative.d.ts +19 -0
  165. package/dist/core/validators/number/non-positive.d.ts +19 -0
  166. package/dist/core/validators/number/number.d.ts +19 -0
  167. package/dist/core/validators/number/positive.d.ts +20 -0
  168. package/dist/core/validators/number/safe-integer.d.ts +19 -0
  169. package/dist/core/validators/object/deep-equals.d.ts +24 -0
  170. package/dist/core/validators/object/has-key.d.ts +23 -0
  171. package/dist/core/validators/object/has-value.d.ts +27 -0
  172. package/dist/core/validators/object/keys-equal.d.ts +26 -0
  173. package/dist/core/validators/object/max-keys.d.ts +24 -0
  174. package/dist/core/validators/object/min-keys.d.ts +24 -0
  175. package/dist/core/validators/object/missing-key.d.ts +23 -0
  176. package/dist/core/validators/object/no-empty-array-values.d.ts +23 -0
  177. package/dist/core/validators/object/no-empty-object-values.d.ts +23 -0
  178. package/dist/core/validators/object/no-null-values.d.ts +23 -0
  179. package/dist/core/validators/object/no-undefined-values.d.ts +23 -0
  180. package/dist/core/validators/object/non-empty-object.d.ts +21 -0
  181. package/dist/core/validators/object/only-keys.d.ts +23 -0
  182. package/dist/core/validators/object/plain-object.d.ts +22 -0
  183. package/dist/core/validators/string/alpha-num.d.ts +23 -0
  184. package/dist/core/validators/string/alpha.d.ts +24 -0
  185. package/dist/core/validators/string/chars-equal.d.ts +23 -0
  186. package/dist/core/validators/string/ends-with.d.ts +23 -0
  187. package/dist/core/validators/string/is-ascii.d.ts +24 -0
  188. package/dist/core/validators/string/is-printable.d.ts +25 -0
  189. package/dist/core/validators/string/matches.d.ts +23 -0
  190. package/dist/core/validators/string/max-length.d.ts +24 -0
  191. package/dist/core/validators/string/min-length.d.ts +24 -0
  192. package/dist/core/validators/string/no-lead-space.d.ts +23 -0
  193. package/dist/core/validators/string/no-repeat-space.d.ts +25 -0
  194. package/dist/core/validators/string/no-space.d.ts +24 -0
  195. package/dist/core/validators/string/no-trail-space.d.ts +23 -0
  196. package/dist/core/validators/string/non-empty.d.ts +22 -0
  197. package/dist/core/validators/string/not-one-of.d.ts +24 -0
  198. package/dist/core/validators/string/num-string.d.ts +23 -0
  199. package/dist/core/validators/string/one-of.d.ts +23 -0
  200. package/dist/core/validators/string/starts-with.d.ts +23 -0
  201. package/dist/core/validators/string/string.d.ts +21 -0
  202. package/dist/core/validators/string/trimmed.d.ts +24 -0
  203. package/dist/index.d.ts +83 -0
  204. package/dist/test.d.ts +1 -0
  205. package/package.json +2 -2
@@ -0,0 +1,51 @@
1
+ /**
2
+ * ----------------------------------------------------------------------------
3
+ * Shapes | Field Path
4
+ * ----------------------------------------------------------------------------
5
+ * @package @clementine-solutions/jane
6
+ * @description Structural paths that locate positions inside JSON‑like data.
7
+ * @see https://jane-io.com
8
+ * ----------------------------------------------------------------------------
9
+ */
10
+ /**
11
+ * A structured, lossless representation of a location inside a value.
12
+ *
13
+ * A FieldPath is an ordered list of segments, each describing a single step
14
+ * into an object or array. This avoids string parsing, keeps traversal
15
+ * deterministic, and provides a stable reference for validation, scanning,
16
+ * formatting, and boundary evaluation.
17
+ */
18
+ export interface FieldPath {
19
+ segments: FieldPathSegment[];
20
+ toString(): string;
21
+ inputName?: string;
22
+ }
23
+ /**
24
+ * A single step in a FieldPath.
25
+ *
26
+ * Segments are either object keys or array indexes. They never infer meaning
27
+ * and never encode both at once, ensuring paths remain literal and unambiguous
28
+ * across all pipeline stages.
29
+ */
30
+ export type FieldPathSegment = SegmentIndex | SegmentKey;
31
+ /**
32
+ * A segment that refers to an array index.
33
+ *
34
+ * Represents a concrete numeric position inside a list. Index segments keep
35
+ * array traversal stable and predictable for scanning, diff, and explain.
36
+ */
37
+ export interface SegmentIndex {
38
+ kind: 'index';
39
+ index: number;
40
+ }
41
+ /**
42
+ * A segment that refers to an object key.
43
+ *
44
+ * Stores the key exactly as encountered. No normalization or inference is
45
+ * applied, preserving the original structure for formatting, parsing, and
46
+ * boundary evaluation.
47
+ */
48
+ export interface SegmentKey {
49
+ kind: 'key';
50
+ key: string;
51
+ }
@@ -0,0 +1,21 @@
1
+ /**
2
+ * ----------------------------------------------------------------------------
3
+ * Shapes | Barrel File
4
+ * ----------------------------------------------------------------------------
5
+ * @package @clementine-solutions/jane
6
+ * @description Central export surface for all shape families in this
7
+ * module.
8
+ * @see https://jane-io.com
9
+ * ----------------------------------------------------------------------------
10
+ */
11
+ export type { DiffEntry, DiffFunction, DiffResult, ExplainFunction, ExplainResult, ExplainStep, ReplayFunction, ReplayResult, ReplayStep, TelemetryContext, TelemetryDiffRecord, TelemetryNormalizeRecord, TelemetryDecideRecord, TelemetryExplainRecord, TelemetryParseRecord, TelemetryReplayRecord, TelemetryRecord, TelemetryRecordBase, TelemetryResult, TelemetryScanRecord, TelemetrySink, TelemetryStage, TelemetryValidateRecord, } from './analysis';
12
+ export type { BoundaryContext, BoundaryDecideConfig, BoundaryDecision, BoundaryInput, BoundaryMetadata, BoundaryResult, BoundaryRule, BoundaryRuleResult, } from './boundary';
13
+ export type { EventCode, EventKind, EventRule, JaneEvent } from './events';
14
+ export type { FieldPath, FieldPathSegment, SegmentIndex, SegmentKey } from './field-path';
15
+ export type { NormalizationMode, NormalizationResult, NormalizationRule, NormalizationStageContext, NormalizationStageOutput, } from './normalize';
16
+ export type { ParserFactory, ParserFactoryRule, ParseResult, ParseRule, ParseStageContext, ParseStageOutput, ParserFluentRule, ParserName, } from './parse';
17
+ export type { FieldMetadata, PipelineBuilder, PipelineBuilderBase, PipelineInput, PipelineMetadata, PipelinePhase, PipelineResult, } from './pipeline';
18
+ export type { Policy, PolicyAnalysisConfig, PolicyContext, PolicyDecideConfig, PolicyDecision, PolicyDecisionCode, PolicyExceptionConfig, PolicyInput, PolicyOverrides, PolicyResult, } from './policy';
19
+ export type { JaneBoundaryResult, JaneResult, PublicPipeline } from './public';
20
+ export type { ContainmentContext, ContainmentOptions, InternalJsonArray, InternalJsonObject, InternalJsonValue, JsonValue, ScanRule, ScanRuleSet, ScanRunner, ScanStageContext, ScanStageOutput, StructuralType, } from './scan';
21
+ export type { ValidatorFactory, ValidatorFactoryRule, ValidatorFluentRule, ValidatorName, ValidationRule, ValidationStageContext, ValidationStageOutput, } from './validate';
@@ -0,0 +1,59 @@
1
+ /**
2
+ * ----------------------------------------------------------------------------
3
+ * Shapes | Normalize
4
+ * ----------------------------------------------------------------------------
5
+ * @package @clementine-solutions/jane
6
+ * @description Shapes that define mode‑aware value transformations during
7
+ * normalization.
8
+ * @see https://jane-io.com
9
+ * ----------------------------------------------------------------------------
10
+ */
11
+ import type { FieldPath, JaneEvent } from '.';
12
+ /**
13
+ * Controls how aggressively values may be transformed during normalization.
14
+ *
15
+ * `strict` applies no changes, `moderate` allows only lossless adjustments,
16
+ * and `lax` enables full, potentially lossy normalization.
17
+ */
18
+ export type NormalizationMode = 'strict' | 'moderate' | 'lax';
19
+ /**
20
+ * Describes a proposed value transformation during normalization.
21
+ *
22
+ * Each result specifies the next value, whether the change is lossless or
23
+ * lossy, and any events emitted by the rule at the given path.
24
+ */
25
+ export interface NormalizationResult<T = unknown> {
26
+ readonly path?: FieldPath;
27
+ readonly nextValue: T;
28
+ readonly lossy: 'lossless' | 'lossy';
29
+ readonly events?: JaneEvent[];
30
+ }
31
+ /**
32
+ * A normalization rule that inspects a value and proposes transformations.
33
+ *
34
+ * Rules return zero or more NormalizationResult entries, allowing the
35
+ * pipeline to merge, filter, or apply them based on the active mode.
36
+ */
37
+ export type NormalizationRule<T = unknown> = (value: T, mode: NormalizationMode, path: FieldPath) => readonly NormalizationResult<T>[];
38
+ /**
39
+ * Input to a normalization stage execution.
40
+ *
41
+ * Provides the safe value from scan, the active rules, the current path,
42
+ * and the normalization mode controlling which transformations are allowed.
43
+ */
44
+ export interface NormalizationStageContext {
45
+ readonly safe: unknown;
46
+ readonly path?: FieldPath;
47
+ readonly rules: readonly NormalizationRule[];
48
+ readonly mode: NormalizationMode;
49
+ }
50
+ /**
51
+ * Output produced by the normalization stage.
52
+ *
53
+ * Contains all emitted normalization events and the final normalized value
54
+ * after applying mode‑appropriate transformations.
55
+ */
56
+ export interface NormalizationStageOutput {
57
+ readonly events: readonly JaneEvent[];
58
+ readonly normalized: unknown;
59
+ }
@@ -0,0 +1,75 @@
1
+ /**
2
+ * ----------------------------------------------------------------------------
3
+ * Shapes | Parse
4
+ * ----------------------------------------------------------------------------
5
+ * @package @clementine-solutions/jane
6
+ * @description Shapes that define how raw strings are converted into typed
7
+ * values.
8
+ * @see https://jane-io.com
9
+ * ----------------------------------------------------------------------------
10
+ */
11
+ import type { FieldPath, JaneEvent, PipelineBuilder } from '.';
12
+ import type { janeRegistry } from '../fluent-registry';
13
+ /**
14
+ * A factory that produces a parse rule.
15
+ *
16
+ * Used by registry‑backed fluent APIs to create parameterized parsing
17
+ * behavior from user‑supplied arguments.
18
+ */
19
+ export type ParserFactory = (...args: unknown[]) => ParseRule;
20
+ /**
21
+ * A fluent parser entry for a named parser in the registry.
22
+ *
23
+ * If the registry entry is a factory, exposes its parameters and returns
24
+ * a PipelineBuilder. Otherwise, returns a PipelineBuilder directly.
25
+ */
26
+ export type ParserFactoryRule<Name extends ParserName> = (typeof janeRegistry.parsers)[Name] extends ParserFactory ? (...args: Parameters<(typeof janeRegistry.parsers)[Name]>) => PipelineBuilder : PipelineBuilder;
27
+ /**
28
+ * The fluent rule type for any parser registered in Jane.
29
+ *
30
+ * Represents either a zero‑argument parser or a parameterized factory,
31
+ * depending on the registry entry.
32
+ */
33
+ export type ParserFluentRule = (typeof janeRegistry.parsers)[ParserName];
34
+ /**
35
+ * The set of parser names registered in Jane.
36
+ *
37
+ * Used to index parser factories and fluent rules in the registry.
38
+ */
39
+ export type ParserName = keyof typeof janeRegistry.parsers;
40
+ /**
41
+ * Describes the outcome of a single parse rule.
42
+ *
43
+ * Provides the next value, its path, and any events emitted while parsing.
44
+ */
45
+ export interface ParseResult<T = unknown> {
46
+ readonly path?: FieldPath;
47
+ readonly nextValue: T;
48
+ readonly events?: JaneEvent[];
49
+ }
50
+ /**
51
+ * A parsing rule that inspects a value and proposes transformations.
52
+ *
53
+ * Returns zero or more ParseResult entries, allowing the parse stage to
54
+ * apply or merge them as needed.
55
+ */
56
+ export type ParseRule<T = unknown> = (value: T, path: FieldPath) => readonly ParseResult<T>[];
57
+ /**
58
+ * Input to a parse stage execution.
59
+ *
60
+ * Provides the raw value, its current path, and the active parse rules.
61
+ */
62
+ export interface ParseStageContext {
63
+ readonly value: unknown;
64
+ readonly path?: FieldPath;
65
+ readonly rules: readonly ParseRule[];
66
+ }
67
+ /**
68
+ * Output produced by the parse stage.
69
+ *
70
+ * Contains all emitted parse events and the final parsed value.
71
+ */
72
+ export interface ParseStageOutput {
73
+ readonly events: readonly JaneEvent[];
74
+ readonly parsed: unknown;
75
+ }
@@ -0,0 +1,149 @@
1
+ /**
2
+ * ----------------------------------------------------------------------------
3
+ * Shapes | Pipeline
4
+ * ----------------------------------------------------------------------------
5
+ * @package @clementine-solutions/jane
6
+ * @description Shapes that define the structural contracts between
7
+ * pipeline stages.
8
+ * @see https://jane-io.com
9
+ * ----------------------------------------------------------------------------
10
+ */
11
+ import type { DiffResult, ExplainResult, FieldPath, JaneEvent, ParseRule, Policy, PolicyDecision, PolicyOverrides, ReplayResult, ScanRule, StructuralType, TelemetrySink, ValidationRule, ValidatorName, ParserName, PolicyInput } from '.';
12
+ /**
13
+ * Captures per‑field lifecycle information across the pipeline.
14
+ *
15
+ * Records the raw, safe, and final values, structural types, path, timing
16
+ * data, and optional input name for analysis and reporting.
17
+ */
18
+ export interface FieldMetadata {
19
+ raw: unknown;
20
+ safe?: unknown;
21
+ final?: unknown;
22
+ path?: FieldPath;
23
+ rawType: StructuralType;
24
+ finalType?: StructuralType;
25
+ startedAt: string;
26
+ finishedAt: string;
27
+ durationMs: number;
28
+ inputName?: string;
29
+ }
30
+ /**
31
+ * A fluent builder that assembles a complete pipeline.
32
+ *
33
+ * Extends the base builder with parser and validator fluent entries,
34
+ * enabling expressive, chainable configuration of all pipeline stages.
35
+ */
36
+ export type PipelineBuilder = PipelineBuilderBase & {
37
+ [K in ValidatorName]: (...args: unknown[]) => PipelineBuilder;
38
+ } & {
39
+ [K in ParserName]: (...args: unknown[]) => PipelineBuilder;
40
+ };
41
+ /**
42
+ * Core fluent interface for constructing a pipeline.
43
+ *
44
+ * Provides access to the raw value, path, accumulated rules, policy
45
+ * overrides, and all configuration methods for naming, messaging,
46
+ * mode selection, analysis features, and policy behavior.
47
+ */
48
+ export interface PipelineBuilderBase {
49
+ readonly raw: unknown;
50
+ readonly path: FieldPath;
51
+ readonly scanRules: readonly ScanRule[];
52
+ readonly parseRules: readonly ParseRule[];
53
+ readonly validationRules: readonly ValidationRule[];
54
+ readonly policy?: Policy;
55
+ readonly overrides: PolicyOverrides;
56
+ run<T>(): Promise<PipelineResult<T>>;
57
+ scan(): PipelineBuilder;
58
+ parse(name: ParserName, ...args: unknown[]): PipelineBuilder;
59
+ parse(rule: ParseRule): PipelineBuilder;
60
+ validate(name: ValidatorName, ...args: unknown[]): PipelineBuilder;
61
+ validate(rule: ValidationRule): PipelineBuilder;
62
+ named(name: string): PipelineBuilder;
63
+ userMessage(message: string): PipelineBuilder;
64
+ strict(): PipelineBuilder;
65
+ moderate(): PipelineBuilder;
66
+ lax(): PipelineBuilder;
67
+ withDiff(): PipelineBuilder;
68
+ withExplain(): PipelineBuilder;
69
+ withReplay(): PipelineBuilder;
70
+ withTelemetry(sink: TelemetrySink): PipelineBuilder;
71
+ withPolicy(policy: PolicyInput): PipelineBuilder;
72
+ allowBigint(): PipelineBuilder;
73
+ }
74
+ /**
75
+ * Internal representation of a fully configured pipeline.
76
+ *
77
+ * Contains the raw value, path, resolved policy, selected rules for each
78
+ * stage, and optional user‑facing metadata such as input name, message
79
+ * overrides, and telemetry sink.
80
+ */
81
+ export interface PipelineInput {
82
+ raw: unknown;
83
+ path: FieldPath;
84
+ policy: Policy;
85
+ scanRules: ScanRule[];
86
+ parseRules: ParseRule[];
87
+ validationRules: ValidationRule[];
88
+ inputName?: string;
89
+ userMessageOverride?: string;
90
+ telemetrySink?: TelemetrySink;
91
+ }
92
+ /**
93
+ * Execution‑level metadata for a pipeline run.
94
+ *
95
+ * Records timing, identifiers, naming, and enabled analysis features,
96
+ * providing a complete audit trail for the run.
97
+ */
98
+ export interface PipelineMetadata {
99
+ runId: string;
100
+ startedAt: string;
101
+ finishedAt: string;
102
+ durationMs: number;
103
+ inputName?: string;
104
+ pipelineName?: string;
105
+ boundaryName?: string;
106
+ analysis?: {
107
+ diff?: boolean;
108
+ explain?: boolean;
109
+ replay?: boolean;
110
+ telemetry?: boolean;
111
+ };
112
+ }
113
+ /**
114
+ * Enumerates the phases of the pipeline lifecycle.
115
+ *
116
+ * Used to tag events and organize analysis across scan, parse,
117
+ * normalize, validate, and decide.
118
+ */
119
+ export type PipelinePhase = 'scan' | 'normalize' | 'validate' | 'parse' | 'decide';
120
+ /**
121
+ * The complete outcome of a pipeline run.
122
+ *
123
+ * Includes the policy decision, intermediate and final values, structural
124
+ * types, all emitted events (both aggregated and per‑phase), optional
125
+ * analysis artifacts, and execution metadata.
126
+ */
127
+ export interface PipelineResult<T> {
128
+ decision: PolicyDecision;
129
+ policy: Policy;
130
+ raw: unknown;
131
+ safe?: unknown;
132
+ normalized?: unknown;
133
+ final?: T;
134
+ path: FieldPath;
135
+ rawType: StructuralType;
136
+ safeType: StructuralType;
137
+ normalizedType: StructuralType;
138
+ finalType?: StructuralType;
139
+ events: readonly JaneEvent[];
140
+ issues: readonly JaneEvent[];
141
+ scanEvents: readonly JaneEvent[];
142
+ normalizeEvents: readonly JaneEvent[];
143
+ parseEvents: readonly JaneEvent[];
144
+ validateEvents: readonly JaneEvent[];
145
+ diff?: DiffResult;
146
+ explain?: ExplainResult;
147
+ replay?: ReplayResult;
148
+ metadata: PipelineMetadata;
149
+ }
@@ -0,0 +1,158 @@
1
+ /**
2
+ * ----------------------------------------------------------------------------
3
+ * Shapes | Policy
4
+ * ----------------------------------------------------------------------------
5
+ * @package @clementine-solutions/jane
6
+ * @description Configuration shapes that control how boundaries interpret
7
+ * and act on events.
8
+ * @see https://jane-io.com
9
+ * ----------------------------------------------------------------------------
10
+ */
11
+ import type { DiffResult, EventCode, ExplainResult, FieldPath, JaneEvent, NormalizationMode, PipelineResult, ReplayResult, StructuralType, TelemetrySink } from '.';
12
+ import type { BoundaryDecideConfig } from './boundary';
13
+ import type { EventKind, EventPattern } from './events';
14
+ /**
15
+ * A configuration object that controls how a boundary interprets events.
16
+ *
17
+ * Policy selects the normalization mode, enables analysis features, applies
18
+ * decision rules, and defines exceptions. It is the stable contract that
19
+ * guides acceptance, rejection, review, and severity transforms across the
20
+ * pipeline.
21
+ */
22
+ export interface Policy {
23
+ boundaryName?: string;
24
+ pipelineName?: string;
25
+ mode: NormalizationMode;
26
+ boundary?: BoundaryDecideConfig;
27
+ decide?: PolicyDecideConfig;
28
+ analysis?: PolicyAnalysisConfig;
29
+ scan?: boolean;
30
+ exception?: PolicyExceptionConfig;
31
+ severity?: Readonly<Partial<Record<EventCode, EventKind>>>;
32
+ reject?: readonly string[];
33
+ review?: readonly string[];
34
+ warn?: readonly string[];
35
+ }
36
+ /**
37
+ * Optional analysis features that a policy may enable.
38
+ *
39
+ * These flags activate diff, explain, replay, and telemetry support during
40
+ * evaluation without affecting core normalization or decision behavior.
41
+ */
42
+ export interface PolicyAnalysisConfig {
43
+ readonly diff?: boolean;
44
+ readonly explain?: boolean;
45
+ readonly replay?: boolean;
46
+ readonly telemetry?: boolean;
47
+ }
48
+ /**
49
+ * A complete snapshot of boundary evaluation state.
50
+ *
51
+ * Captures the raw, safe, normalized, and final values; their structural
52
+ * types; all emitted events; and any optional analysis results. This context
53
+ * is passed to policy logic to support deterministic decisions and
54
+ * contributor‑visible explanations.
55
+ */
56
+ export interface PolicyContext<T> {
57
+ readonly policy: Policy;
58
+ readonly raw: unknown;
59
+ readonly safe?: unknown;
60
+ readonly normalized?: unknown;
61
+ readonly final?: T;
62
+ readonly path: FieldPath;
63
+ readonly rawType: StructuralType;
64
+ readonly safeType: StructuralType;
65
+ readonly normalizedType: StructuralType;
66
+ readonly finalType?: StructuralType;
67
+ readonly events: readonly JaneEvent[];
68
+ readonly issues: readonly JaneEvent[];
69
+ readonly scanEvents: readonly JaneEvent[];
70
+ readonly normalizeEvents: readonly JaneEvent[];
71
+ readonly parseEvents: readonly JaneEvent[];
72
+ readonly validateEvents: readonly JaneEvent[];
73
+ readonly diff?: DiffResult;
74
+ readonly explain?: ExplainResult;
75
+ readonly replay?: ReplayResult;
76
+ }
77
+ /**
78
+ * Decision rules that transform or classify events.
79
+ *
80
+ * Override and escalate adjust severities, while review, reject, and warn
81
+ * define pattern‑based classifications used during final policy evaluation.
82
+ */
83
+ export interface PolicyDecideConfig {
84
+ readonly override?: Readonly<Partial<Record<EventPattern, number>>>;
85
+ readonly escalate?: Readonly<Partial<Record<EventPattern, number>>>;
86
+ readonly review?: readonly EventCode[] | string[];
87
+ readonly reject?: readonly string[];
88
+ readonly warn?: readonly string[];
89
+ }
90
+ /**
91
+ * The final outcome produced by policy evaluation.
92
+ *
93
+ * Encodes whether the pipeline accepts, reviews, or rejects the value,
94
+ * along with flags indicating whether review or reject events were present.
95
+ */
96
+ export interface PolicyDecision {
97
+ readonly code: PolicyDecisionCode;
98
+ readonly reason?: string;
99
+ readonly hasRejectEvents: boolean;
100
+ readonly hasReviewEvents: boolean;
101
+ }
102
+ /**
103
+ * The three possible outcomes of policy evaluation.
104
+ */
105
+ export type PolicyDecisionCode = 'accept' | 'review' | 'reject';
106
+ /**
107
+ * Opt‑in allowances for otherwise disallowed structural types.
108
+ *
109
+ * These exceptions let a boundary accept bigint, Map, or Set values
110
+ * without emitting structural errors during normalization or validation.
111
+ */
112
+ export interface PolicyExceptionConfig {
113
+ readonly bigint?: boolean;
114
+ readonly map?: boolean;
115
+ readonly set?: boolean;
116
+ }
117
+ /**
118
+ * A flexible input shape for constructing a Policy.
119
+ *
120
+ * Accepts partial configuration for all policy features, allowing callers
121
+ * to specify only the fields they need while relying on normalization to
122
+ * produce a complete Policy object.
123
+ */
124
+ export type PolicyInput = Partial<Omit<Policy, 'mode'>> & {
125
+ mode?: NormalizationMode;
126
+ analysis?: PolicyAnalysisConfig;
127
+ scan?: boolean;
128
+ exception?: PolicyExceptionConfig;
129
+ boundaryName?: string;
130
+ pipelineName?: string;
131
+ boundary?: Partial<BoundaryDecideConfig>;
132
+ decide?: Partial<PolicyDecideConfig>;
133
+ severity?: Readonly<Partial<Record<EventCode, EventKind>>>;
134
+ reject?: readonly string[];
135
+ review?: readonly string[];
136
+ warn?: readonly string[];
137
+ };
138
+ /**
139
+ * The full pipeline result produced under a given policy.
140
+ *
141
+ * Alias of PipelineResult to keep the public Policy surface cohesive.
142
+ */
143
+ export type PolicyResult<T> = PipelineResult<T>;
144
+ /**
145
+ * Runtime overrides applied during boundary evaluation.
146
+ *
147
+ * Allows callers to adjust mode, analysis features, exceptions, and
148
+ * telemetry behavior without modifying the underlying Policy.
149
+ */
150
+ export interface PolicyOverrides {
151
+ inputName?: string;
152
+ userMessageOverride?: string;
153
+ readonly mode?: NormalizationMode;
154
+ readonly analysis?: PolicyAnalysisConfig;
155
+ readonly scan?: boolean;
156
+ readonly exception?: PolicyExceptionConfig;
157
+ readonly telemetrySink?: TelemetrySink;
158
+ }
@@ -0,0 +1,92 @@
1
+ /**
2
+ * ----------------------------------------------------------------------------
3
+ * Shapes | Public
4
+ * ----------------------------------------------------------------------------
5
+ * @package @clementine-solutions/jane
6
+ * @description Stable result and input shapes exposed by the public API.
7
+ * @see https://jane-io.com
8
+ * ----------------------------------------------------------------------------
9
+ */
10
+ import type { DiffResult, EventKind, ExplainResult, FieldPath, JaneEvent, ParserName, ParseRule, Policy, PolicyInput, ReplayResult, StructuralType, TelemetrySink, ValidationRule, ValidatorName } from '../shapes';
11
+ import type { BoundaryReducer, BoundaryRule } from './boundary';
12
+ import type { FieldMetadata } from './pipeline';
13
+ export interface JaneBoundaryResult<TFields extends Record<string, unknown>> {
14
+ ok: boolean;
15
+ issues?: readonly JaneEvent[];
16
+ events?: readonly JaneEvent[];
17
+ values?: TFields;
18
+ fields: Record<string, JaneResult<unknown>>;
19
+ metadata: {
20
+ runId?: string;
21
+ startedAt?: string;
22
+ finishedAt?: string;
23
+ durationMs?: number;
24
+ fields: Record<string, FieldMetadata>;
25
+ };
26
+ }
27
+ export interface JaneResult<T> {
28
+ readonly ok: boolean;
29
+ readonly issues?: readonly JaneEvent[];
30
+ readonly events?: readonly JaneEvent[];
31
+ readonly value?: T;
32
+ readonly path?: FieldPath;
33
+ readonly diff?: DiffResult;
34
+ readonly explain?: ExplainResult;
35
+ readonly replay?: ReplayResult;
36
+ readonly metadata: {
37
+ readonly raw: unknown;
38
+ readonly rawType: StructuralType;
39
+ readonly safe?: unknown;
40
+ readonly safeType?: StructuralType;
41
+ readonly normalized?: unknown;
42
+ readonly normalizedType?: StructuralType;
43
+ readonly final?: unknown;
44
+ readonly finalType?: StructuralType;
45
+ readonly startedAt: string;
46
+ readonly finishedAt: string;
47
+ readonly durationMs: number;
48
+ readonly inputName?: string;
49
+ };
50
+ }
51
+ export type PublicPipeline = {
52
+ run(): Promise<JaneResult<unknown>>;
53
+ scan(): PublicPipeline;
54
+ named(name: string): PublicPipeline;
55
+ userMessage(userMessage: string): PublicPipeline;
56
+ strict(): PublicPipeline;
57
+ moderate(): PublicPipeline;
58
+ lax(): PublicPipeline;
59
+ withDiff(): PublicPipeline;
60
+ withExplain(): PublicPipeline;
61
+ withReplay(): PublicPipeline;
62
+ withTelemetry(sink: TelemetrySink): PublicPipeline;
63
+ withPolicy(policy: PolicyInput): Policy;
64
+ allowBigint(): PublicPipeline;
65
+ allowMap(): PublicPipeline;
66
+ allowSet(): PublicPipeline;
67
+ parse(name: ParserName, ...args: unknown[]): PublicPipeline;
68
+ parse(rule: ParseRule): PublicPipeline;
69
+ validate(name: ValidatorName, ...args: unknown[]): PublicPipeline;
70
+ validate(rule: ValidationRule): PublicPipeline;
71
+ severity(map: Record<string, EventKind>): PublicPipeline;
72
+ reject(...patterns: string[]): PublicPipeline;
73
+ review(...patterns: string[]): PublicPipeline;
74
+ warn(...patterns: string[]): PublicPipeline;
75
+ boundaryAccept(mode: 'strict' | 'all' | 'any' | 'partial'): PublicPipeline;
76
+ boundaryIncludeRejected(): PublicPipeline;
77
+ boundaryIncludeUndefined(): PublicPipeline;
78
+ boundaryTransform(fn: (values: Record<string, unknown>) => Record<string, unknown>): PublicPipeline;
79
+ boundaryIgnore(...patterns: string[]): PublicPipeline;
80
+ boundaryHideEvents(...patterns: string[]): PublicPipeline;
81
+ boundaryHideIssues(...patterns: string[]): PublicPipeline;
82
+ boundaryReducer(fn: BoundaryReducer): PublicPipeline;
83
+ boundaryRule(rule: BoundaryRule): PublicPipeline;
84
+ boundaryRules(...rules: BoundaryRule[]): PublicPipeline;
85
+ boundaryHideFields(): PublicPipeline;
86
+ boundaryHideTimestamps(): PublicPipeline;
87
+ boundaryHideRunId(): PublicPipeline;
88
+ } & {
89
+ [K in ValidatorName]: (...args: unknown[]) => PublicPipeline;
90
+ } & {
91
+ [K in ParserName]: (...args: unknown[]) => PublicPipeline;
92
+ };