@ptolemy2002/rgx 5.6.0 → 6.0.0

package/README.md

@@ -79,21 +79,23 @@ type RGXGroupTokenArgs = {
     capturing?: boolean;
 };
 
-type RGXPartEventType = "pre-capture" | "post-capture";
+type RGXPartControl = "skip" | "stop" | "silent" | void;
+
+type RGXCapture<T = unknown> = {
+    raw: string;
+    value: T;
+};
+
 type RGXPartOptions<R, T=string> = {
     transform: (captured: string) => T;
-    onEvent: ((part: RGXPart<R, T>, eventType: RGXPartEventType, walker: RGXWalker<R>) => void) | null;
+    validate: (captured: RGXCapture<T>, part: RGXPart<R, T>, walker: RGXWalker<R>) => boolean | string;
+    beforeCapture: ((part: RGXPart<R, T>, walker: RGXWalker<R>) => RGXPartControl) | null;
+    afterCapture: ((capture: RGXCapture<T>, part: RGXPart<R, T>, walker: RGXWalker<R>) => void) | null;
 };
 
 type RGXWalkerOptions<R> = {
     startingSourcePosition?: number;
-    reducedCurrent?: R;
-};
-
-type RGXWalkerFlags = {
-    stopped: boolean;
-    skipped: boolean;
-    nonCapture: boolean;
+    reduced?: R;
 };
 ```
 
@@ -325,6 +327,21 @@ constructor(message: string, got: number, { min, max, inclusiveLeft, inclusiveRi
 - `failedAtMax() => boolean`: Returns `true` if the `got` value is above the maximum bound (respecting `inclusiveRight`), otherwise `false`. Returns `false` if `max` is `null`.
 - `failedAtAny() => boolean`: Returns `true` if the value failed at either the minimum or maximum bound.
 
+### RGXPartValidationFailedError extends RGXError
+A specific error class for RGX part validation failures. This error is thrown when a captured value fails validation in a custom part's `validate` function. The error code is set to `PART_VALIDATION_FAILED` on instantiation.
+
+#### Constructor
+```typescript
+constructor(message: string, gotRaw: string, gotTransformed: unknown)
+```
+- `message` (`string`): The error message.
+- `gotRaw` (`string`): The raw captured string value that failed validation.
+- `gotTransformed` (`unknown`): The transformed value that was produced by the part's `transform` function, which also failed validation.
+
+#### Properties
+- `gotRaw` (`string`): The raw captured string value that failed validation.
+- `gotTransformed` (`unknown`): The transformed value that was produced by the part's `transform` function, which also failed validation.
+
 ### RGXTokenCollection
 A class representing a collection of RGX tokens. This class manages collections of RGX tokens like an array, but with additional metadata about the collection mode (union or concat). Since `toRgx()` returns a `RegExp`, instances of this class satisfy the `RGXConvertibleToken` interface and can be used directly as tokens in `rgx`, `rgxa`, and other token-accepting functions.
 
@@ -579,7 +596,7 @@ constructor(pattern: string | RegExp, flags?: string)
 - `[Symbol.species]` (`RegExpConstructor`): Returns `ExtRegExp`, ensuring that derived `RegExp` methods (like those returning new regex instances) produce `ExtRegExp` instances rather than plain `RegExp`.
 
 ### RGXPart\<R, T=string\>
-A class that wraps an `RGXToken` and captures the matched string when used within an `RGXWalker`. It implements `RGXConvertibleToken`, delegating `rgxIsGroup` and `rgxIsRepeatable` to the wrapped token. After a walker captures a match for this part, the `capturedString` and `capturedValue` properties are populated, with the latter produced by the `transform` function.
+A class that wraps an `RGXToken` with optional callbacks for use within an `RGXWalker`. It implements `RGXConvertibleToken`, delegating `rgxIsGroup` and `rgxIsRepeatable` to the wrapped token. Unlike plain tokens, Parts can control walker behavior via `beforeCapture` (returning an `RGXPartControl` value) and react to captures via `afterCapture`. Parts are purely definitions and do not store capture state — all captures are stored on the walker as `RGXCapture` objects.
 
 A function `rgxPart` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
 
@@ -594,24 +611,25 @@ constructor(token: RGXToken, options?: Partial<RGXPartOptions<R, T>>)
 - `token` (`RGXToken`): The token to wrap.
 - `options` (`Partial<RGXPartOptions<R, T>>`, optional): Configuration options. Defaults to `{}`.
   - `transform` (`(captured: string) => T`, optional): A function that transforms the captured string into the desired type `T`. Defaults to an identity function that casts the string to `T`.
-  - `onEvent` (`((part: RGXPart<R, T>, eventType: RGXPartEventType, walker: RGXWalker<R>) => void) | null`, optional): A callback invoked when an event is triggered on this part during walking. Defaults to `null`.
+  - `beforeCapture` (`((part: RGXPart<R, T>, walker: RGXWalker<R>) => RGXPartControl) | null`, optional): A callback invoked before capturing this part during walking. Returns an `RGXPartControl` value to control walker behavior: `"skip"` to skip this token without capturing, `"silent"` to capture but not record in `captures`, `"stop"` to halt immediately without capturing or advancing, or `void`/`undefined` to proceed normally. Defaults to `null`.
+  - `afterCapture` (`((capture: RGXCapture<T>, part: RGXPart<R, T>, walker: RGXWalker<R>) => void) | null`, optional): A callback invoked after capturing this part during walking. Receives the typed `RGXCapture<T>` result. Can call `walker.stop()` to halt walking after this capture. Defaults to `null`.
+  - `validate` (`((capture: RGXCapture<T>, walker: RGXWalker<R>) => boolean | string) | null`, optional): A callback invoked during validation after capturing and transforming, but before `afterCapture`. Returns `true` if validation passes, `false` to fail with a generic error, or a string to fail with that string as the error message. Defaults to `null`.
 
 #### Properties
 - `token` (`RGXToken`): The wrapped token.
-- `capturedString` (`string | null`): The raw string captured by the walker for this part, or `null` if not yet captured.
-- `capturedValue` (`T | null`): The transformed value produced by applying `transform` to `capturedString`, or `null` if not yet captured.
-- `transform` (`(captured: string) => T`): The transform function used to convert captured strings to values of type `T`.
-- `onEvent` (`((part: RGXPart<R, T>, eventType: RGXPartEventType, walker: RGXWalker<R>) => void) | null`): The event callback, or `null`.
+- `transform` (`(captured: string) => T`, readonly): The transform function used to convert captured strings to values of type `T`.
+- `beforeCapture` (`((part: RGXPart<R, T>, walker: RGXWalker<R>) => RGXPartControl) | null`, readonly): The before-capture callback, or `null`.
+- `afterCapture` (`((capture: RGXCapture<T>, part: RGXPart<R, T>, walker: RGXWalker<R>) => void) | null`, readonly): The after-capture callback, or `null`.
 - `rgxIsGroup` (`boolean`): Delegates to the wrapped token's group status via `isRGXGroupedToken`.
 - `rgxIsRepeatable` (`boolean`): If the wrapped token is an `RGXConvertibleToken`, delegates to its `rgxIsRepeatable` property (defaulting to `true` if not present). Otherwise, returns `true`.
 
 #### Methods
-- `triggerEvent(eventType: RGXPartEventType, walker: RGXWalker<R>) => void`: Triggers an event on this part. For `"post-capture"` events, sets `capturedString` to the walker's last captured string and `capturedValue` to the result of `transform`. Then calls the `onEvent` callback if present.
 - `toRgx() => RGXToken`: Returns the wrapped token.
-- `clone(depth: CloneDepth = "max") => RGXPart`: Creates a clone of this part. When `depth` is `0`, returns `this`; otherwise, returns a new `RGXPart` with a cloned token and the same `transform` and `onEvent` references.
+- `clone(depth: CloneDepth = "max") => RGXPart`: Creates a clone of this part. When `depth` is `0`, returns `this`; otherwise, returns a new `RGXPart` with a cloned token and the same `transform`, `beforeCapture`, and `afterCapture` references.
+- `validate(capture: RGXCapture<T>, walker: RGXWalker<R>) => void`: A method that calls the inner passed validation logic for this part, if any. If it returns `false`, a generic `RGXPartValidationFailedError` is thrown. If it returns a string, an `RGXPartValidationFailedError` is thrown with that string as the message. If it returns `true`, validation passed. This is called internally by the walker after capturing and transforming a part, before invoking `afterCapture`.
 
 ### RGXWalker\<R\>
-A class that walks through a sequence of RGX tokens, matching each token against a source string at the current position. It implements `RGXConvertibleToken`, delegating to its internal `RGXTokenCollection`. The walker maintains a source position and a token position, advancing through both as tokens are matched. When an `RGXPart` is encountered, its event callbacks are triggered around the capture. The generic type `R` represents a user-defined "reduced" value that can accumulate state during walking (e.g., via `RGXPart` event callbacks).
+A class that walks through a sequence of RGX tokens, matching each token against a source string at the current position. It implements `RGXConvertibleToken`, delegating to its internal `RGXTokenCollection`. The walker maintains a source position and a token position, advancing through both as tokens are matched. When an `RGXPart` is encountered, its `beforeCapture` callback can control behavior via return values (`RGXPartControl`), and its `afterCapture` callback is invoked with the typed capture result. All captures are stored as structured `RGXCapture` objects on the walker. The generic type `R` represents a user-defined "reduced" value that can accumulate state during walking (e.g., via `RGXPart` callbacks).
 
 A function `rgxWalker` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
 
@@ -627,37 +645,33 @@ constructor(source: string, tokens: RGXTokenCollectionInput, options?: RGXWalker
 - `tokens` (`RGXTokenCollectionInput`): The tokens to match sequentially. Internally stored as an `RGXTokenCollection` in 'concat' mode.
 - `options` (`RGXWalkerOptions<R>`, optional): Configuration options. Defaults to `{}`.
   - `startingSourcePosition` (`number`, optional): The starting index in the source string. Defaults to `0`.
-  - `reducedCurrent` (`R`, optional): The initial value for the `reducedCurrent` accumulator. Defaults to `null`.
+  - `reduced` (`R`, optional): The initial value for the `reduced` accumulator. Defaults to `null`.
 
 #### Properties
 - `source` (`string`): The source string being walked (readonly).
-- `sourcePosition` (`number`): The current index in the source string. Setting this validates that the value is >= 0 and < `source.length`, throwing `RGXOutOfBoundsError` if not.
+- `sourcePosition` (`number`): The current index in the source string. Range is `[0, source.length]` inclusive, where `source.length` represents "fully consumed". Setting this validates that the value is >= 0 and <= `source.length`, throwing `RGXOutOfBoundsError` if not.
 - `tokens` (`RGXTokenCollection`): The internal collection of tokens in 'concat' mode (readonly).
 - `tokenPosition` (`number`): The current index in the token collection. Setting this validates that the value is >= 0 and <= `tokens.length`, throwing `RGXOutOfBoundsError` if not.
-- `reducedCurrent` (`R`): A user-defined accumulator value, typically updated by `RGXPart` event callbacks during walking.
-- `capturedStrings` (`string[]`): An array of all strings captured during walking (excluding those captured with the `nonCapture` flag set).
-- `flags` (`RGXWalkerFlags`): The current walker flags: `stopped` halts `stepToToken`/`stepToPart`/`walk`, `skipped` causes `step` to skip the current token without capturing, and `nonCapture` prevents the captured string from being added to `capturedStrings`.
+- `reduced` (`R`): A user-defined accumulator value, typically updated by `RGXPart` callbacks during walking.
+- `captures` (`RGXCapture[]`): An array of structured capture results recorded during walking. Each entry has a `raw` string and a `value` (the transform result for Parts, or the raw string for plain tokens).
+- `stopped` (`boolean`, readonly): Whether the walker has been stopped, either by a Part's `beforeCapture` returning `"stop"` or by calling `stop()` in an `afterCapture` callback.
 
 #### Methods
-- `resetFlags() => void`: Resets all flags (`stopped`, `skipped`, `nonCapture`) to `false`.
-- `stop() => void`: Sets the `stopped` flag to `true`, causing any active `stepToToken`, `stepToPart`, or `walk` loop to halt after the current iteration.
-- `skip() => void`: Sets the `skipped` flag to `true`, causing the current `step` call to skip capturing the current token.
-- `preventCapture() => void`: Sets the `nonCapture` flag to `true`, causing the current `step` call to capture the token but not add the matched string to `capturedStrings`.
+- `stop() => void`: Sets `stopped` to `true`, causing any active `stepToToken`, `stepToPart`, or `walk` loop to halt after the current iteration. Typically called from an `afterCapture` callback to stop walking after the current capture.
 - `atTokenEnd() => boolean`: Returns `true` if the token position is at or past the end of the token collection.
-- `hasNextToken(predicate?: (token: RGXToken) => boolean) => boolean`: Returns `true` if there is a next token and it satisfies the optional predicate (defaults to `() => true`).
-- `atSourceEnd() => boolean`: Returns `true` if the source position is at the last character of the source string.
-- `hasNextSource(predicate?: (rest: string) => boolean) => boolean`: Returns `true` if the source position is not at the end and the remaining source satisfies the optional predicate (defaults to `() => true`).
-- `hasCapturedStrings(minCount?: number) => boolean`: Returns `true` if `capturedStrings` has at least `minCount` entries (defaults to `1`).
-- `getLastCapturedString() => string | null`: Returns the last entry in `capturedStrings`, or `null` if empty.
-- `nextToken() => RGXToken | null`: Returns the token at the current token position, or `null` if at the end.
-- `remainingSource() => string | null`: Returns the remaining source string from the current position onward, or `null` if at the end.
-- `capture(token: RGXToken) => string`: Resolves the token to a regex, asserts that it matches at the current source position (throwing `RGXRegexNotMatchedAtPositionError` if not), captures the matched string (unless `nonCapture` is set), and advances the source position by the match length. Returns the matched string.
-- `step(flagReset?: boolean) => string | null`: Steps through the next token in the collection. If `flagReset` is `true` (the default), resets flags first. If the token is an `RGXPart`, triggers `"pre-capture"` before capturing and `"post-capture"` after (when not skipped or non-capturing). Advances the token position and returns the captured string, or `null` if there are no more tokens or the step was skipped.
-- `stepToToken(predicate: (token: RGXToken) => boolean) => void`: Steps through tokens until the predicate returns `true` for the next token or the walker is stopped. The matching token is not consumed.
-- `stepToPart(predicate?: (part: RGXPart<R>) => boolean) => void`: Steps through tokens until the next `RGXPart` satisfying the predicate is reached. If already at a part, steps once first to move past it. The matching part is not consumed.
-- `walk() => void`: Steps through all remaining tokens until the end of the token collection.
+- `hasNextToken(predicate?: (token: RGXToken) => boolean) => boolean`: Returns `true` if there is a current token and it satisfies the optional predicate (defaults to `() => true`).
+- `atSourceEnd() => boolean`: Returns `true` if the source has been fully consumed (`sourcePosition >= source.length`).
+- `hasNextSource(predicate?: (rest: string) => boolean) => boolean`: Returns `true` if the source is not fully consumed and the remaining source satisfies the optional predicate (defaults to `() => true`).
+- `lastCapture() => RGXCapture | null`: Returns the last entry in `captures`, or `null` if empty.
+- `currentToken() => RGXToken | null`: Returns the token at the current token position, or `null` if at the end.
+- `remainingSource() => string | null`: Returns the remaining source string from the current position onward, or `null` if the source is fully consumed.
+- `capture(token: RGXToken) => string`: Resolves the token to a regex, asserts that it matches at the current source position (throwing `RGXRegexNotMatchedAtPositionError` if not), and advances the source position by the match length. Returns the matched string.
+- `step() => RGXCapture | null`: Steps through the next token in the collection. If the token is an `RGXPart`, calls `beforeCapture` first — if it returns `"stop"`, sets `stopped` and returns `null` without advancing; if `"skip"`, advances the token position and returns `null` without capturing; if `"silent"`, captures but does not add to `captures`. After capturing, validates. After validating, calls `afterCapture` if present. Returns the `RGXCapture` result, or `null` if there are no more tokens, the step was skipped, or the walker was stopped.
+- `stepToToken(predicate: (token: RGXToken) => boolean) => void`: Steps through tokens until the predicate returns `true` for the current token or the walker is stopped. The matching token is not consumed.
+- `stepToPart(predicate?: (part: RGXPart<R>) => boolean) => void`: Steps through tokens until the next `RGXPart` satisfying the predicate is reached. If already at a Part, steps once first to move past it. The matching Part is not consumed.
+- `walk() => void`: Steps through all remaining tokens until the end of the token collection or the walker is stopped.
 - `toRgx() => RGXToken`: Returns the internal `RGXTokenCollection`, allowing the walker to be used as a convertible token.
-- `clone(depth: CloneDepth = "max") => RGXWalker`: Creates a clone of the walker. When `depth` is `0`, returns `this`; otherwise, creates a new `RGXWalker` with cloned tokens, source position, reduced value, captured strings, and flags.
+- `clone(depth: CloneDepth = "max") => RGXWalker`: Creates a clone of the walker. When `depth` is `0`, returns `this`; otherwise, creates a new `RGXWalker` with cloned tokens, source position, reduced value, captures, and stopped state.
 
 ## Functions
 The following functions are exported by the library:

package/dist/errors/base.d.ts

@@ -1,4 +1,4 @@
-export type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'NOT_SUPPORTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS' | 'INVALID_FLAG_TRANSFORMER_KEY' | 'FLAG_TRANSFORMER_CONFLICT' | 'CONSTANT_CONFLICT' | 'INVALID_CONSTANT_KEY' | 'INSERTION_REJECTED' | 'REGEX_NOT_MATCHED_AT_POSITION';
+export type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'NOT_SUPPORTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS' | 'INVALID_FLAG_TRANSFORMER_KEY' | 'FLAG_TRANSFORMER_CONFLICT' | 'CONSTANT_CONFLICT' | 'INVALID_CONSTANT_KEY' | 'INSERTION_REJECTED' | 'REGEX_NOT_MATCHED_AT_POSITION' | 'PART_VALIDATION_FAILED';
 export declare class RGXError extends Error {
     _message: string;
     code: RGXErrorCode;

package/dist/errors/index.d.ts

@@ -13,3 +13,4 @@ export * from './insertionRejected';
 export * from './constantConflict';
 export * from './invalidConstantKey';
 export * from './regexNotMatchedAtPosition';
+export * from './partValidationFailed';

package/dist/errors/index.js

@@ -29,3 +29,4 @@ __exportStar(require("./insertionRejected"), exports);
 __exportStar(require("./constantConflict"), exports);
 __exportStar(require("./invalidConstantKey"), exports);
 __exportStar(require("./regexNotMatchedAtPosition"), exports);
+__exportStar(require("./partValidationFailed"), exports);

package/dist/errors/partValidationFailed.d.ts

@@ -0,0 +1,7 @@
+import { RGXError } from "./base";
+export declare class RGXPartValidationFailedError extends RGXError {
+    gotRaw: string;
+    gotTransformed: unknown;
+    constructor(message: string, gotRaw: string, gotTransformed: unknown);
+    calcMessage(message: string): string;
+}

package/dist/errors/partValidationFailed.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXPartValidationFailedError = void 0;
+const base_1 = require("./base");
+class RGXPartValidationFailedError extends base_1.RGXError {
+    constructor(message, gotRaw, gotTransformed) {
+        super(message, 'PART_VALIDATION_FAILED');
+        this.name = 'RGXPartValidationFailedError';
+        this.gotRaw = gotRaw;
+        this.gotTransformed = gotTransformed;
+    }
+    calcMessage(message) {
+        return `${message}; Got: ${this.gotRaw} (transformed: ${JSON.stringify(this.gotTransformed)})`;
+    }
+}
+exports.RGXPartValidationFailedError = RGXPartValidationFailedError;

package/dist/utils/regexMatchAtPosition.js

@@ -22,8 +22,9 @@ function doesRegexMatchAtPosition(regex, str, position) {
     return regexMatchAtPosition(regex, str, position) !== null;
 }
 function assertRegexMatchesAtPosition(regex, str, position, contextSize = 10) {
-    if (!doesRegexMatchAtPosition(regex, str, position)) {
+    const result = regexMatchAtPosition(regex, str, position);
+    if (result === null) {
         throw new errors_1.RGXRegexNotMatchedAtPositionError("Regex not matched at index", regex, str, position, contextSize);
     }
-    return regexMatchAtPosition(regex, str, position);
+    return result;
 }

package/dist/walker/base.d.ts

@@ -1,45 +1,37 @@
 import { CloneDepth } from "@ptolemy2002/immutability-utils";
 import { RGXTokenCollection, RGXTokenCollectionInput } from "../collection";
 import { RGXConvertibleToken, RGXToken } from "../types";
-import { RGXPart } from "./part";
+import { RGXPart, RGXCapture } from "./part";
 export type RGXWalkerOptions<R> = {
     startingSourcePosition?: number;
-    reducedCurrent?: R;
-};
-export type RGXWalkerFlags = {
-    stopped: boolean;
-    skipped: boolean;
-    nonCapture: boolean;
+    reduced?: R;
 };
 export declare class RGXWalker<R> implements RGXConvertibleToken {
     readonly source: string;
     _sourcePosition: number;
     readonly tokens: RGXTokenCollection;
     _tokenPosition: number;
-    reducedCurrent: R;
-    capturedStrings: string[];
-    flags: RGXWalkerFlags;
+    reduced: R;
+    captures: RGXCapture[];
+    private _stopped;
     static check: (value: unknown) => value is RGXWalker<unknown>;
     static assert: (value: unknown) => asserts value is RGXWalker<unknown>;
     get sourcePosition(): number;
     set sourcePosition(value: number);
     get tokenPosition(): number;
     set tokenPosition(value: number);
+    get stopped(): boolean;
     constructor(source: string, tokens: RGXTokenCollectionInput, options?: RGXWalkerOptions<R>);
-    resetFlags(): void;
     stop(): void;
-    skip(): void;
-    preventCapture(): void;
     atTokenEnd(): boolean;
     hasNextToken(predicate?: (token: RGXToken) => boolean): boolean;
     atSourceEnd(): boolean;
     hasNextSource(predicate?: (rest: string) => boolean): boolean;
-    hasCapturedStrings(minCount?: number): boolean;
-    getLastCapturedString(): string | null | undefined;
-    nextToken(): RGXToken;
+    lastCapture(): RGXCapture | null;
+    currentToken(): RGXToken;
     remainingSource(): string | null;
     capture(token: RGXToken): string;
-    step(flagReset?: boolean): string | null;
+    step(): RGXCapture | null;
     stepToToken(predicate: (token: RGXToken) => boolean): void;
     stepToPart(predicate?: (part: RGXPart<R>) => boolean): void;
     walk(): void;

package/dist/walker/base.js

@@ -13,7 +13,7 @@ class RGXWalker {
         return this._sourcePosition;
     }
     set sourcePosition(value) {
-        (0, errors_1.assertInRange)(value, { min: 0, max: this.source.length, inclusiveRight: false }, "sourcePosition is outside the bounds of the source string");
+        (0, errors_1.assertInRange)(value, { min: 0, max: this.source.length }, "sourcePosition is outside the bounds of the source string");
         this._sourcePosition = value;
     }
     get tokenPosition() {
@@ -23,114 +23,119 @@ class RGXWalker {
         (0, errors_1.assertInRange)(value, { min: 0, max: this.tokens.length }, "tokenPosition is outside the bounds of the token collection");
         this._tokenPosition = value;
     }
+    get stopped() {
+        return this._stopped;
+    }
     constructor(source, tokens, options = {}) {
-        this.capturedStrings = [];
-        this.flags = {
-            stopped: false,
-            skipped: false,
-            nonCapture: false
-        };
+        this.captures = [];
+        this._stopped = false;
         this.source = source;
         this.sourcePosition = options.startingSourcePosition ?? 0;
         this.tokens = new collection_1.RGXTokenCollection(tokens, "concat");
         this.tokenPosition = 0;
-        this.reducedCurrent = options.reducedCurrent ?? null;
-    }
-    resetFlags() {
-        this.flags.stopped = false;
-        this.flags.skipped = false;
-        this.flags.nonCapture = false;
+        this.reduced = options.reduced ?? null;
     }
     stop() {
-        this.flags.stopped = true;
-    }
-    skip() {
-        this.flags.skipped = true;
-    }
-    preventCapture() {
-        this.flags.nonCapture = true;
+        this._stopped = true;
     }
     atTokenEnd() {
         return this.tokenPosition >= this.tokens.length;
     }
     hasNextToken(predicate = () => true) {
-        return !this.atTokenEnd() && predicate(this.nextToken());
+        return !this.atTokenEnd() && predicate(this.currentToken());
     }
     atSourceEnd() {
-        return this.sourcePosition >= this.source.length - 1;
+        return this.sourcePosition >= this.source.length;
     }
     hasNextSource(predicate = () => true) {
         return !this.atSourceEnd() && predicate(this.remainingSource());
     }
-    hasCapturedStrings(minCount = 1) {
-        return this.capturedStrings.length >= minCount;
-    }
-    getLastCapturedString() {
-        if (!this.hasCapturedStrings())
+    lastCapture() {
+        if (this.captures.length === 0)
             return null;
-        return this.capturedStrings[this.capturedStrings.length - 1];
+        return this.captures[this.captures.length - 1];
     }
-    nextToken() {
-        if (this.tokenPosition >= this.tokens.length)
+    currentToken() {
+        if (this.atTokenEnd())
             return null;
         return this.tokens.at(this.tokenPosition);
     }
     remainingSource() {
-        if (this.sourcePosition >= this.source.length - 1)
+        if (this.atSourceEnd())
             return null;
         return this.source.slice(this.sourcePosition);
     }
     capture(token) {
         const regex = (0, index_1.rgxa)([token]);
         const match = (0, index_1.assertRegexMatchesAtPosition)(regex, this.source, this.sourcePosition);
-        if (!this.flags.nonCapture)
-            this.capturedStrings.push(match);
-        if (this.sourcePosition < this.source.length - match.length)
-            this.sourcePosition += match.length;
-        else
-            this.sourcePosition = this.source.length - 1; // Move to the end of the source if the match goes beyond it
+        this.sourcePosition += match.length;
         return match;
     }
-    step(flagReset = true) {
-        if (flagReset)
-            this.resetFlags();
-        if (!this.hasNextToken())
+    step() {
+        if (this.atTokenEnd())
             return null;
-        const token = this.nextToken();
-        if (token instanceof part_1.RGXPart)
-            token.triggerEvent("pre-capture", this);
-        let captured = null;
-        if (!this.flags.skipped) {
-            captured = this.capture(token);
-            if (token instanceof part_1.RGXPart && !this.flags.nonCapture)
-                token.triggerEvent("post-capture", this);
+        const token = this.currentToken();
+        const isPart = token instanceof part_1.RGXPart;
+        let silent = false;
+        // Ask Part what to do — control flow via return values, not flags.
+        if (isPart) {
+            const control = token.beforeCapture?.(token, this);
+            if (control === "stop") {
+                this._stopped = true;
+                return null;
+            }
+            if (control === "skip") {
+                this.tokenPosition++;
+                return null;
+            }
+            if (control === "silent") {
+                silent = true;
+            }
+        }
+        // Capture the match
+        const raw = this.capture(token);
+        const value = isPart ? token.transform(raw) : raw;
+        const captureResult = { raw, value };
+        // Validate the part. If validation fails, it will throw an error, so nothing below will run.
+        if (isPart) {
+            token.validate(captureResult, this);
+        }
+        // Skip adding the capture if in silent mode.
+        if (!silent) {
+            this.captures.push(captureResult);
+        }
+        // Notify Part after capture
+        if (isPart) {
+            token.afterCapture?.(captureResult, token, this);
         }
         this.tokenPosition++;
-        return captured;
+        return captureResult;
     }
     stepToToken(predicate) {
         while (this.hasNextToken()) {
-            this.resetFlags();
-            if (predicate(this.nextToken()))
+            this._stopped = false;
+            if (predicate(this.currentToken()))
                 break;
-            this.step(false);
-            if (this.flags.stopped)
+            this.step();
+            if (this._stopped)
                 break;
         }
     }
     stepToPart(predicate = () => true) {
-        // If we're currently at a part, step once so that we can get to the next one.
-        if (this.nextToken() instanceof part_1.RGXPart)
+        // If currently at a Part, step past it first so repeated
+        // calls advance to the next Part rather than getting stuck.
+        if (this.currentToken() instanceof part_1.RGXPart) {
+            this._stopped = false;
             this.step();
-        if (this.flags.stopped)
-            return;
+            if (this._stopped)
+                return;
+        }
         this.stepToToken(token => token instanceof part_1.RGXPart && predicate(token));
     }
     walk() {
         return this.stepToToken(() => false);
     }
-    // When used as a convertible token, just treat the walker as
-    // a collection.
+    // When used as a convertible token, treat the walker as its collection.
     toRgx() {
         return this.tokens;
     }
@@ -140,11 +145,11 @@ class RGXWalker {
             return this;
         const clone = new RGXWalker(this.source, this.tokens.clone((0, immutability_utils_1.depthDecrement)(1)), {
             startingSourcePosition: this.sourcePosition,
-            reducedCurrent: (0, immutability_utils_1.extClone)(this.reducedCurrent, (0, immutability_utils_1.depthDecrement)(1))
+            reduced: (0, immutability_utils_1.extClone)(this.reduced, (0, immutability_utils_1.depthDecrement)(1))
         });
         clone._tokenPosition = this.tokenPosition;
-        clone.capturedStrings = (0, immutability_utils_1.extClone)(this.capturedStrings, (0, immutability_utils_1.depthDecrement)(1));
-        clone.flags = (0, immutability_utils_1.extClone)(this.flags, (0, immutability_utils_1.depthDecrement)(1));
+        clone.captures = (0, immutability_utils_1.extClone)(this.captures, (0, immutability_utils_1.depthDecrement)(1));
+        clone._stopped = this._stopped;
         return clone;
     }
 }

package/dist/walker/part.d.ts

@@ -1,21 +1,27 @@
 import { RGXConvertibleToken, RGXToken } from "../types";
 import type { RGXWalker } from "./base";
 import { CloneDepth } from "@ptolemy2002/immutability-utils";
-export type RGXPartEventType = "pre-capture" | "post-capture";
+export type RGXPartControl = "skip" | "stop" | "silent" | void;
+export type RGXCapture<T = unknown> = {
+    raw: string;
+    value: T;
+};
 export type RGXPartOptions<R, T = string> = {
     transform: (captured: string) => T;
-    onEvent: ((part: RGXPart<R, T>, eventType: RGXPartEventType, walker: RGXWalker<R>) => void) | null;
+    validate: (captured: RGXCapture<T>, part: RGXPart<R, T>, walker: RGXWalker<R>) => boolean | string;
+    beforeCapture: ((part: RGXPart<R, T>, walker: RGXWalker<R>) => RGXPartControl) | null;
+    afterCapture: ((capture: RGXCapture<T>, part: RGXPart<R, T>, walker: RGXWalker<R>) => void) | null;
 };
 export declare class RGXPart<R, T = string> implements RGXConvertibleToken {
     token: RGXToken;
-    capturedString: string | null;
-    capturedValue: T | null;
     readonly transform: RGXPartOptions<R, T>["transform"];
-    readonly onEvent: RGXPartOptions<R, T>["onEvent"];
+    private readonly _validate;
+    readonly beforeCapture: RGXPartOptions<R, T>["beforeCapture"];
+    readonly afterCapture: RGXPartOptions<R, T>["afterCapture"];
     static check: (value: unknown) => value is RGXPart<unknown, unknown>;
     static assert: (value: unknown) => asserts value is RGXPart<unknown, unknown>;
     constructor(token: RGXToken, options?: Partial<RGXPartOptions<R, T>>);
-    triggerEvent(eventType: RGXPartEventType, walker: RGXWalker<R>): void;
+    validate(capture: RGXCapture<T>, walker: RGXWalker<R>): void;
     get rgxIsGroup(): boolean;
     get rgxIsRepeatable(): boolean;
     toRgx(): RGXToken;

package/dist/walker/part.js

@@ -6,23 +6,23 @@ const typeGuards_1 = require("../typeGuards");
 const internal_1 = require("../internal");
 const clone_1 = require("../clone");
 const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
+const errors_1 = require("../errors");
+// A Part is purely a definition: a token + optional callbacks.
+// It does NOT store capture state — that lives on the walker.
 class RGXPart {
     constructor(token, options = {}) {
-        this.capturedString = null;
-        this.capturedValue = null;
         this.token = token;
         this.transform = options.transform ?? ((captured) => captured);
-        this.onEvent = options.onEvent ?? null;
+        this._validate = options.validate ?? (() => true);
+        this.beforeCapture = options.beforeCapture ?? null;
+        this.afterCapture = options.afterCapture ?? null;
     }
-    triggerEvent(eventType, walker) {
-        switch (eventType) {
-            case "post-capture": {
-                this.capturedString = walker.getLastCapturedString();
-                this.capturedValue = this.transform(this.capturedString);
-                break;
-            }
-        }
-        this.onEvent?.(this, eventType, walker);
+    validate(capture, walker) {
+        const result = this._validate(capture, this, walker);
+        if (result === true)
+            return;
+        const message = typeof result === "string" ? result : "Part Validation Failed";
+        throw new errors_1.RGXPartValidationFailedError(message, capture.raw, capture.value);
     }
     // Properties used for conversion to an RGXToken
     get rgxIsGroup() {
@@ -41,7 +41,11 @@ class RGXPart {
     clone(depth = "max") {
         if (depth === 0)
             return this;
-        return new RGXPart((0, clone_1.cloneRGXToken)(this.token, (0, immutability_utils_1.depthDecrement)(depth, 1)), { transform: this.transform, onEvent: this.onEvent });
+        return new RGXPart((0, clone_1.cloneRGXToken)(this.token, (0, immutability_utils_1.depthDecrement)(depth, 1)), {
+            transform: this.transform,
+            beforeCapture: this.beforeCapture,
+            afterCapture: this.afterCapture,
+        });
     }
 }
 exports.RGXPart = RGXPart;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ptolemy2002/rgx",
-    "version": "5.6.0",
+    "version": "6.0.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",