@clementine-solutions/jane-io 1.0.0 → 1.0.2

package/dist/core/shapes/index.js

@@ -0,0 +1,11 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Barrel File
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Central export surface for all shape families in this
+ *                  module.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export {};

package/dist/core/shapes/normalize.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Normalize
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shapes that define mode‑aware value transformations during
+ *                  normalization.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { FieldPath, JaneEvent } from '.';
+/**
+ * Controls how aggressively values may be transformed during normalization.
+ *
+ * `strict` applies no changes, `moderate` allows only lossless adjustments,
+ * and `lax` enables full, potentially lossy normalization.
+ */
+export type NormalizationMode = 'strict' | 'moderate' | 'lax';
+/**
+ * Describes a proposed value transformation during normalization.
+ *
+ * Each result specifies the next value, whether the change is lossless or
+ * lossy, and any events emitted by the rule at the given path.
+ */
+export interface NormalizationResult<T = unknown> {
+    readonly path?: FieldPath;
+    readonly nextValue: T;
+    readonly lossy: 'lossless' | 'lossy';
+    readonly events?: JaneEvent[];
+}
+/**
+ * A normalization rule that inspects a value and proposes transformations.
+ *
+ * Rules return zero or more NormalizationResult entries, allowing the
+ * pipeline to merge, filter, or apply them based on the active mode.
+ */
+export type NormalizationRule<T = unknown> = (value: T, mode: NormalizationMode, path: FieldPath) => readonly NormalizationResult<T>[];
+/**
+ * Input to a normalization stage execution.
+ *
+ * Provides the safe value from scan, the active rules, the current path,
+ * and the normalization mode controlling which transformations are allowed.
+ */
+export interface NormalizationStageContext {
+    readonly safe: unknown;
+    readonly path?: FieldPath;
+    readonly rules: readonly NormalizationRule[];
+    readonly mode: NormalizationMode;
+}
+/**
+ * Output produced by the normalization stage.
+ *
+ * Contains all emitted normalization events and the final normalized value
+ * after applying mode‑appropriate transformations.
+ */
+export interface NormalizationStageOutput {
+    readonly events: readonly JaneEvent[];
+    readonly normalized: unknown;
+}

package/dist/core/shapes/normalize.js

@@ -0,0 +1,11 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Normalize
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shapes that define mode‑aware value transformations during
+ *                  normalization.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export {};

package/dist/core/shapes/parse.d.ts

@@ -0,0 +1,75 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Parse
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shapes that define how raw strings are converted into typed
+ *                  values.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { FieldPath, JaneEvent, PipelineBuilder } from '.';
+import type { janeRegistry } from '../fluent-registry';
+/**
+ * A factory that produces a parse rule.
+ *
+ * Used by registry‑backed fluent APIs to create parameterized parsing
+ * behavior from user‑supplied arguments.
+ */
+export type ParserFactory = (...args: unknown[]) => ParseRule;
+/**
+ * A fluent parser entry for a named parser in the registry.
+ *
+ * If the registry entry is a factory, exposes its parameters and returns
+ * a PipelineBuilder. Otherwise, returns a PipelineBuilder directly.
+ */
+export type ParserFactoryRule<Name extends ParserName> = (typeof janeRegistry.parsers)[Name] extends ParserFactory ? (...args: Parameters<(typeof janeRegistry.parsers)[Name]>) => PipelineBuilder : PipelineBuilder;
+/**
+ * The fluent rule type for any parser registered in Jane.
+ *
+ * Represents either a zero‑argument parser or a parameterized factory,
+ * depending on the registry entry.
+ */
+export type ParserFluentRule = (typeof janeRegistry.parsers)[ParserName];
+/**
+ * The set of parser names registered in Jane.
+ *
+ * Used to index parser factories and fluent rules in the registry.
+ */
+export type ParserName = keyof typeof janeRegistry.parsers;
+/**
+ * Describes the outcome of a single parse rule.
+ *
+ * Provides the next value, its path, and any events emitted while parsing.
+ */
+export interface ParseResult<T = unknown> {
+    readonly path?: FieldPath;
+    readonly nextValue: T;
+    readonly events?: JaneEvent[];
+}
+/**
+ * A parsing rule that inspects a value and proposes transformations.
+ *
+ * Returns zero or more ParseResult entries, allowing the parse stage to
+ * apply or merge them as needed.
+ */
+export type ParseRule<T = unknown> = (value: T, path: FieldPath) => readonly ParseResult<T>[];
+/**
+ * Input to a parse stage execution.
+ *
+ * Provides the raw value, its current path, and the active parse rules.
+ */
+export interface ParseStageContext {
+    readonly value: unknown;
+    readonly path?: FieldPath;
+    readonly rules: readonly ParseRule[];
+}
+/**
+ * Output produced by the parse stage.
+ *
+ * Contains all emitted parse events and the final parsed value.
+ */
+export interface ParseStageOutput {
+    readonly events: readonly JaneEvent[];
+    readonly parsed: unknown;
+}

package/dist/core/shapes/parse.js

@@ -0,0 +1,11 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Parse
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shapes that define how raw strings are converted into typed
+ *                  values.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export {};

package/dist/core/shapes/pipeline.d.ts

@@ -0,0 +1,149 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Pipeline
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shapes that define the structural contracts between
+ *                  pipeline stages.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { DiffResult, ExplainResult, FieldPath, JaneEvent, ParseRule, Policy, PolicyDecision, PolicyOverrides, ReplayResult, ScanRule, StructuralType, TelemetrySink, ValidationRule, ValidatorName, ParserName, PolicyInput } from '.';
+/**
+ * Captures per‑field lifecycle information across the pipeline.
+ *
+ * Records the raw, safe, and final values, structural types, path, timing
+ * data, and optional input name for analysis and reporting.
+ */
+export interface FieldMetadata {
+    raw: unknown;
+    safe?: unknown;
+    final?: unknown;
+    path?: FieldPath;
+    rawType: StructuralType;
+    finalType?: StructuralType;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    inputName?: string;
+}
+/**
+ * A fluent builder that assembles a complete pipeline.
+ *
+ * Extends the base builder with parser and validator fluent entries,
+ * enabling expressive, chainable configuration of all pipeline stages.
+ */
+export type PipelineBuilder = PipelineBuilderBase & {
+    [K in ValidatorName]: (...args: unknown[]) => PipelineBuilder;
+} & {
+    [K in ParserName]: (...args: unknown[]) => PipelineBuilder;
+};
+/**
+ * Core fluent interface for constructing a pipeline.
+ *
+ * Provides access to the raw value, path, accumulated rules, policy
+ * overrides, and all configuration methods for naming, messaging,
+ * mode selection, analysis features, and policy behavior.
+ */
+export interface PipelineBuilderBase {
+    readonly raw: unknown;
+    readonly path: FieldPath;
+    readonly scanRules: readonly ScanRule[];
+    readonly parseRules: readonly ParseRule[];
+    readonly validationRules: readonly ValidationRule[];
+    readonly policy?: Policy;
+    readonly overrides: PolicyOverrides;
+    run<T>(): Promise<PipelineResult<T>>;
+    scan(): PipelineBuilder;
+    parse(name: ParserName, ...args: unknown[]): PipelineBuilder;
+    parse(rule: ParseRule): PipelineBuilder;
+    validate(name: ValidatorName, ...args: unknown[]): PipelineBuilder;
+    validate(rule: ValidationRule): PipelineBuilder;
+    named(name: string): PipelineBuilder;
+    userMessage(message: string): PipelineBuilder;
+    strict(): PipelineBuilder;
+    moderate(): PipelineBuilder;
+    lax(): PipelineBuilder;
+    withDiff(): PipelineBuilder;
+    withExplain(): PipelineBuilder;
+    withReplay(): PipelineBuilder;
+    withTelemetry(sink: TelemetrySink): PipelineBuilder;
+    withPolicy(policy: PolicyInput): PipelineBuilder;
+    allowBigint(): PipelineBuilder;
+}
+/**
+ * Internal representation of a fully configured pipeline.
+ *
+ * Contains the raw value, path, resolved policy, selected rules for each
+ * stage, and optional user‑facing metadata such as input name, message
+ * overrides, and telemetry sink.
+ */
+export interface PipelineInput {
+    raw: unknown;
+    path: FieldPath;
+    policy: Policy;
+    scanRules: ScanRule[];
+    parseRules: ParseRule[];
+    validationRules: ValidationRule[];
+    inputName?: string;
+    userMessageOverride?: string;
+    telemetrySink?: TelemetrySink;
+}
+/**
+ * Execution‑level metadata for a pipeline run.
+ *
+ * Records timing, identifiers, naming, and enabled analysis features,
+ * providing a complete audit trail for the run.
+ */
+export interface PipelineMetadata {
+    runId: string;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    inputName?: string;
+    pipelineName?: string;
+    boundaryName?: string;
+    analysis?: {
+        diff?: boolean;
+        explain?: boolean;
+        replay?: boolean;
+        telemetry?: boolean;
+    };
+}
+/**
+ * Enumerates the phases of the pipeline lifecycle.
+ *
+ * Used to tag events and organize analysis across scan, parse,
+ * normalize, validate, and decide.
+ */
+export type PipelinePhase = 'scan' | 'normalize' | 'validate' | 'parse' | 'decide';
+/**
+ * The complete outcome of a pipeline run.
+ *
+ * Includes the policy decision, intermediate and final values, structural
+ * types, all emitted events (both aggregated and per‑phase), optional
+ * analysis artifacts, and execution metadata.
+ */
+export interface PipelineResult<T> {
+    decision: PolicyDecision;
+    policy: Policy;
+    raw: unknown;
+    safe?: unknown;
+    normalized?: unknown;
+    final?: T;
+    path: FieldPath;
+    rawType: StructuralType;
+    safeType: StructuralType;
+    normalizedType: StructuralType;
+    finalType?: StructuralType;
+    events: readonly JaneEvent[];
+    issues: readonly JaneEvent[];
+    scanEvents: readonly JaneEvent[];
+    normalizeEvents: readonly JaneEvent[];
+    parseEvents: readonly JaneEvent[];
+    validateEvents: readonly JaneEvent[];
+    diff?: DiffResult;
+    explain?: ExplainResult;
+    replay?: ReplayResult;
+    metadata: PipelineMetadata;
+}

package/dist/core/shapes/pipeline.js

@@ -0,0 +1,11 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Pipeline
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shapes that define the structural contracts between
+ *                  pipeline stages.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export {};

package/dist/core/shapes/policy.d.ts

@@ -0,0 +1,158 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Policy
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Configuration shapes that control how boundaries interpret
+ *                  and act on events.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { DiffResult, EventCode, ExplainResult, FieldPath, JaneEvent, NormalizationMode, PipelineResult, ReplayResult, StructuralType, TelemetrySink } from '.';
+import type { BoundaryDecideConfig } from './boundary';
+import type { EventKind, EventPattern } from './events';
+/**
+ * A configuration object that controls how a boundary interprets events.
+ *
+ * Policy selects the normalization mode, enables analysis features, applies
+ * decision rules, and defines exceptions. It is the stable contract that
+ * guides acceptance, rejection, review, and severity transforms across the
+ * pipeline.
+ */
+export interface Policy {
+    boundaryName?: string;
+    pipelineName?: string;
+    mode: NormalizationMode;
+    boundary?: BoundaryDecideConfig;
+    decide?: PolicyDecideConfig;
+    analysis?: PolicyAnalysisConfig;
+    scan?: boolean;
+    exception?: PolicyExceptionConfig;
+    severity?: Readonly<Partial<Record<EventCode, EventKind>>>;
+    reject?: readonly string[];
+    review?: readonly string[];
+    warn?: readonly string[];
+}
+/**
+ * Optional analysis features that a policy may enable.
+ *
+ * These flags activate diff, explain, replay, and telemetry support during
+ * evaluation without affecting core normalization or decision behavior.
+ */
+export interface PolicyAnalysisConfig {
+    readonly diff?: boolean;
+    readonly explain?: boolean;
+    readonly replay?: boolean;
+    readonly telemetry?: boolean;
+}
+/**
+ * A complete snapshot of boundary evaluation state.
+ *
+ * Captures the raw, safe, normalized, and final values; their structural
+ * types; all emitted events; and any optional analysis results. This context
+ * is passed to policy logic to support deterministic decisions and
+ * contributor‑visible explanations.
+ */
+export interface PolicyContext<T> {
+    readonly policy: Policy;
+    readonly raw: unknown;
+    readonly safe?: unknown;
+    readonly normalized?: unknown;
+    readonly final?: T;
+    readonly path: FieldPath;
+    readonly rawType: StructuralType;
+    readonly safeType: StructuralType;
+    readonly normalizedType: StructuralType;
+    readonly finalType?: StructuralType;
+    readonly events: readonly JaneEvent[];
+    readonly issues: readonly JaneEvent[];
+    readonly scanEvents: readonly JaneEvent[];
+    readonly normalizeEvents: readonly JaneEvent[];
+    readonly parseEvents: readonly JaneEvent[];
+    readonly validateEvents: readonly JaneEvent[];
+    readonly diff?: DiffResult;
+    readonly explain?: ExplainResult;
+    readonly replay?: ReplayResult;
+}
+/**
+ * Decision rules that transform or classify events.
+ *
+ * Override and escalate adjust severities, while review, reject, and warn
+ * define pattern‑based classifications used during final policy evaluation.
+ */
+export interface PolicyDecideConfig {
+    readonly override?: Readonly<Partial<Record<EventPattern, number>>>;
+    readonly escalate?: Readonly<Partial<Record<EventPattern, number>>>;
+    readonly review?: readonly EventCode[] | string[];
+    readonly reject?: readonly string[];
+    readonly warn?: readonly string[];
+}
+/**
+ * The final outcome produced by policy evaluation.
+ *
+ * Encodes whether the pipeline accepts, reviews, or rejects the value,
+ * along with flags indicating whether review or reject events were present.
+ */
+export interface PolicyDecision {
+    readonly code: PolicyDecisionCode;
+    readonly reason?: string;
+    readonly hasRejectEvents: boolean;
+    readonly hasReviewEvents: boolean;
+}
+/**
+ * The three possible outcomes of policy evaluation.
+ */
+export type PolicyDecisionCode = 'accept' | 'review' | 'reject';
+/**
+ * Opt‑in allowances for otherwise disallowed structural types.
+ *
+ * These exceptions let a boundary accept bigint, Map, or Set values
+ * without emitting structural errors during normalization or validation.
+ */
+export interface PolicyExceptionConfig {
+    readonly bigint?: boolean;
+    readonly map?: boolean;
+    readonly set?: boolean;
+}
+/**
+ * A flexible input shape for constructing a Policy.
+ *
+ * Accepts partial configuration for all policy features, allowing callers
+ * to specify only the fields they need while relying on normalization to
+ * produce a complete Policy object.
+ */
+export type PolicyInput = Partial<Omit<Policy, 'mode'>> & {
+    mode?: NormalizationMode;
+    analysis?: PolicyAnalysisConfig;
+    scan?: boolean;
+    exception?: PolicyExceptionConfig;
+    boundaryName?: string;
+    pipelineName?: string;
+    boundary?: Partial<BoundaryDecideConfig>;
+    decide?: Partial<PolicyDecideConfig>;
+    severity?: Readonly<Partial<Record<EventCode, EventKind>>>;
+    reject?: readonly string[];
+    review?: readonly string[];
+    warn?: readonly string[];
+};
+/**
+ * The full pipeline result produced under a given policy.
+ *
+ * Alias of PipelineResult to keep the public Policy surface cohesive.
+ */
+export type PolicyResult<T> = PipelineResult<T>;
+/**
+ * Runtime overrides applied during boundary evaluation.
+ *
+ * Allows callers to adjust mode, analysis features, exceptions, and
+ * telemetry behavior without modifying the underlying Policy.
+ */
+export interface PolicyOverrides {
+    inputName?: string;
+    userMessageOverride?: string;
+    readonly mode?: NormalizationMode;
+    readonly analysis?: PolicyAnalysisConfig;
+    readonly scan?: boolean;
+    readonly exception?: PolicyExceptionConfig;
+    readonly telemetrySink?: TelemetrySink;
+}

package/dist/core/shapes/policy.js

@@ -0,0 +1,11 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Policy
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Configuration shapes that control how boundaries interpret
+ *                  and act on events.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export {};

package/dist/core/shapes/public.d.ts

@@ -0,0 +1,92 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Public
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Stable result and input shapes exposed by the public API.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { DiffResult, EventKind, ExplainResult, FieldPath, JaneEvent, ParserName, ParseRule, Policy, PolicyInput, ReplayResult, StructuralType, TelemetrySink, ValidationRule, ValidatorName } from '../shapes';
+import type { BoundaryReducer, BoundaryRule } from './boundary';
+import type { FieldMetadata } from './pipeline';
+export interface JaneBoundaryResult<TFields extends Record<string, unknown>> {
+    ok: boolean;
+    issues?: readonly JaneEvent[];
+    events?: readonly JaneEvent[];
+    values?: TFields;
+    fields: Record<string, JaneResult<unknown>>;
+    metadata: {
+        runId?: string;
+        startedAt?: string;
+        finishedAt?: string;
+        durationMs?: number;
+        fields: Record<string, FieldMetadata>;
+    };
+}
+export interface JaneResult<T> {
+    readonly ok: boolean;
+    readonly issues?: readonly JaneEvent[];
+    readonly events?: readonly JaneEvent[];
+    readonly value?: T;
+    readonly path?: FieldPath;
+    readonly diff?: DiffResult;
+    readonly explain?: ExplainResult;
+    readonly replay?: ReplayResult;
+    readonly metadata: {
+        readonly raw: unknown;
+        readonly rawType: StructuralType;
+        readonly safe?: unknown;
+        readonly safeType?: StructuralType;
+        readonly normalized?: unknown;
+        readonly normalizedType?: StructuralType;
+        readonly final?: unknown;
+        readonly finalType?: StructuralType;
+        readonly startedAt: string;
+        readonly finishedAt: string;
+        readonly durationMs: number;
+        readonly inputName?: string;
+    };
+}
+export type PublicPipeline = {
+    run(): Promise<JaneResult<unknown>>;
+    scan(): PublicPipeline;
+    named(name: string): PublicPipeline;
+    userMessage(userMessage: string): PublicPipeline;
+    strict(): PublicPipeline;
+    moderate(): PublicPipeline;
+    lax(): PublicPipeline;
+    withDiff(): PublicPipeline;
+    withExplain(): PublicPipeline;
+    withReplay(): PublicPipeline;
+    withTelemetry(sink: TelemetrySink): PublicPipeline;
+    withPolicy(policy: PolicyInput): Policy;
+    allowBigint(): PublicPipeline;
+    allowMap(): PublicPipeline;
+    allowSet(): PublicPipeline;
+    parse(name: ParserName, ...args: unknown[]): PublicPipeline;
+    parse(rule: ParseRule): PublicPipeline;
+    validate(name: ValidatorName, ...args: unknown[]): PublicPipeline;
+    validate(rule: ValidationRule): PublicPipeline;
+    severity(map: Record<string, EventKind>): PublicPipeline;
+    reject(...patterns: string[]): PublicPipeline;
+    review(...patterns: string[]): PublicPipeline;
+    warn(...patterns: string[]): PublicPipeline;
+    boundaryAccept(mode: 'strict' | 'all' | 'any' | 'partial'): PublicPipeline;
+    boundaryIncludeRejected(): PublicPipeline;
+    boundaryIncludeUndefined(): PublicPipeline;
+    boundaryTransform(fn: (values: Record<string, unknown>) => Record<string, unknown>): PublicPipeline;
+    boundaryIgnore(...patterns: string[]): PublicPipeline;
+    boundaryHideEvents(...patterns: string[]): PublicPipeline;
+    boundaryHideIssues(...patterns: string[]): PublicPipeline;
+    boundaryReducer(fn: BoundaryReducer): PublicPipeline;
+    boundaryRule(rule: BoundaryRule): PublicPipeline;
+    boundaryRules(...rules: BoundaryRule[]): PublicPipeline;
+    boundaryHideFields(): PublicPipeline;
+    boundaryHideTimestamps(): PublicPipeline;
+    boundaryHideRunId(): PublicPipeline;
+} & {
+    [K in ValidatorName]: (...args: unknown[]) => PublicPipeline;
+} & {
+    [K in ParserName]: (...args: unknown[]) => PublicPipeline;
+};

package/dist/core/shapes/public.js

@@ -0,0 +1,10 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Public
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Stable result and input shapes exposed by the public API.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export {};