@regex-designer/js 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 loganmzz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,243 @@
-# Temporary Holding Version
+# Regular Expression Designer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small TypeScript library for composing JavaScript regular expressions in a readable, reusable way.
+
+## API
+
+The library exposes a default factory and a `RegexDesigner` class. Each builder acts like a lazy regex composer: methods return template objects that render their pattern only when stringified (e.g. `toString()`) or invoked to compile to a native `RegExp`.
+
+```ts
+import createDesigner from '@regex-designer/js';
+
+const r$ = createDesigner()
+  .set('number', r$.qty([1, Infinity], /[0-9]/));
+  .set('identifier', r$.qty([1, Infinity], /[a-z0-9-]/));
+
+const template = r$.named(
+  'version',
+  r$.var('number'), /\./, r$.var('number'), /\./, r$.var('number'),
+  r$.opt('-', r$.named('prerelease', r$.var('identifier'))),
+);
+const regex = template('i'); // Compile template by using it as a function
+regex.test('12.3.4-beta-1'); // true
+regex.exec('12.3.4-beta-1')?.groups; // { version: '12.3.4-beta-1', prerelease: 'beta-1' }
+```
+
+### tpl(...patterns)
+
+```ts
+tpl(...patterns: RegexValue[]): RegexTemplate
+```
+
+Concatenates pattern parts as-is, without adding grouping, alternation, or escaping:
+
+```ts
+r$.tpl('A', r$.raw('B.C')); // AB\\.C
+```
+
+### default
+
+```ts
+default function(): RegexDesigner
+```
+
+Examples:
+
+```ts
+import createDesigner from '@regex-designer/js';
+
+const r$ = createDesigner();
+r$.named('user', /[^@]+/, '@', /[a-z]+/); // (?<user>[^@]+@[a-z]+)
+```
+
+### or(...patterns)
+
+```ts
+or(...patterns: RegexValue[]): RegexTemplate
+```
+
+Examples:
+
+```ts
+r$.or('A', 'B');                     // A|B
+r$.or(/foo/, 'bar', r$.raw('baz'));  // foo|bar|baz
+```
+
+### named(name, ...patterns)
+
+```ts
+named(name: string, ...patterns: RegexValue[]): RegexTemplate
+```
+
+Examples:
+
+```ts
+r$.named('value', 'A', 'B');            // (?<value>AB)
+r$.named('word', r$.or('cat', 'dog'));  // (?<word>cat|dog)
+```
+
+### group(options, ...patterns)
+
+```ts
+group(options: GroupOptions, ...patterns: RegexValue[]): RegexTemplate
+type GroupOptions = boolean | { name: string } | { capture: boolean };
+```
+
+Examples:
+
+```ts
+r$.group(false, 'A', 'B');              // (?:AB)
+r$.group({ name: 'part' }, 'A', 'B');   // (?<part>AB)
+r$.group({ capture: false }, 'A', 'B'); // (?:AB)
+```
+
+Options:
+
+- `options` can be a boolean or an object.
+- `true` creates a normal capturing group.
+- `false` creates a non-capturing group.
+- `group({ name: 'x' })` creates a named capturing group.
+- `name` and `capture` are mutually exclusive; passing both throws a `TypeError`.
+
+### opt(...patterns)
+
+```ts
+opt(...patterns: RegexValue[]): RegexTemplate
+```
+
+Examples:
+
+```ts
+r$.opt('C');                          // (?:C)?
+r$.opt(r$.named('value', 'A', 'B'));  // (?:(?<value>AB))?
+```
+
+### qty(quantity, ...patterns)
+
+```ts
+qty(quantity: QuantityOptions, ...patterns: RegexValue[]): RegexTemplate
+type QuantityOptions = number | [min: number, max?: number] | QuantityNamedOptions;
+type QuantityNamedOptions = ({ exact: number } | { min: number; max?: number; }) & { greedy?: boolean };
+```
+
+Examples:
+
+```ts
+r$.qty(3, 'A', 'B');                                  // (?:AB){3}
+r$.qty([1, 3], 'A', 'B');                             // (?:AB){1,3}
+r$.qty({ min: 2, max: 5, greedy: false }, 'A', 'B');  // (?:AB){2,5}?
+r$.qty({ exact: 2 }, 'A', 'B');                       // (?:AB){2}
+```
+
+Options:
+
+- `number` means an exact repetition count.
+- `[min, max?]` means a range, with `max` omitted for open-ended repetition.
+- `{ exact }` is a shorthand for exact repetition.
+- `{ min, max? }` creates a bounded repetition.
+- `max` can be `Infinity` for open-ended repetition.
+- `{ greedy?: boolean }` for lazy quantifiers.
+- Quantifiers are greedy by default.
+
+### raw(...strings)
+
+```ts
+raw(...patterns: string[]): RegexTemplate
+```
+
+Examples:
+
+```ts
+r$.raw('a.b', '*').source;    // a\.b\*
+r$.raw('https://example.com') // https://example\.com
+```
+
+### ref(reference)
+
+```ts
+ref(reference: number | string): RegexTemplate
+```
+
+Examples:
+
+```ts
+// (B)\1
+r$.tpl(
+  r$.group(true, 'B'),
+  r$.ref(1),
+);
+
+// (?<name>B)\k<name>
+r$.tpl(
+  r$.named('name', 'B'),
+  r$.ref('name'),
+);
+```
+
+### ahead(...patterns) / ahead_pos(...patterns) / ahead_neg(...patterns)
+
+```ts
+ahead(positive: boolean, ...patterns: RegexValue[]): RegexTemplate
+ahead_pos(...patterns: RegexValue[]): RegexTemplate
+ahead_neg(...patterns: RegexValue[]): RegexTemplate
+```
+
+Examples:
+
+```ts
+r$.ahead_pos('foo');  // (?=foo)
+r$.ahead_neg('bar');  // (?!bar)
+```
+
+### behind(...patterns) / behind_pos(...patterns) / behind_neg(...patterns)
+
+```ts
+behind(positive: boolean, ...patterns: RegexValue[]): RegexTemplate
+behind_pos(...patterns: RegexValue[]): RegexTemplate
+behind_neg(...patterns: RegexValue[]): RegexTemplate
+```
+
+Examples:
+
+```ts
+r$.behind_pos('foo'); // (?<=foo)
+r$.behind_neg('bar'); // (?<!bar)
+```
+
+### set(name, pattern) / var(name)
+
+```ts
+set(name: string, patterns: ...RegexValue[]): this
+var(name: string): RegexTemplate
+```
+
+Examples:
+
+```ts
+r$.set('word', r$.or('cat', 'dog'));
+r$.var('word'); // cat|dog
+```
+
+Options:
+
+- `set()` stores a reusable pattern..
+- `var()` resolves that pattern lazily when rendering.
+- Variables are scoped to the builder instance, so separate builders can reuse the same names without conflict.
+- Rendering an unset variable throws an error.
+- Circular dependencies between variables also throw an error.
+
+## Development
+
+See [AGENTS.md](AGENTS.md) for design choices and contribution conventions shared
+by human contributors and AI coding assistants.
+
+The project relies on Node.js 24.x:
+
+```sh
+npm ci
+npm run check
+```
+
+The build emits ESM JavaScript, TypeScript declarations, and source maps in
+`dist/`. Tests are written in TypeScript, type-checked, and executed with the
+native Node.js test runner against the built library.

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+/** A lazy regex template that can render pattern text or compile to a native RegExp. */
+export interface RegexTemplate {
+    /** Compile the rendered pattern with the supplied flags. */
+    (flags?: string): RegExp;
+    /** Render the pattern; when compiling, validates embedded Unicode flags. */
+    render(flags?: string, compiling?: boolean): string;
+    /** Render the pattern text without compiling it. */
+    toString(): string;
+}
+/** Check whether a value is a regex template. */
+export declare function isRegexTemplate(value: unknown): value is RegexTemplate;
+/**
+ * A regex source string, native RegExp, or lazy regex template.
+ * Strings are regex syntax, not escaped literals. Embedded RegExp values scope
+ * their i, m, and s flags locally, require u or v when compiling, and do not
+ * carry over d, g, or y.
+ */
+export type RegexValue = string | RegExp | RegexTemplate;
+/** Mutually exclusive settings for a named capturing group or an unnamed group. */
+export type GroupNamedOptions = {
+    name: string;
+    capture?: never;
+} | {
+    name?: never;
+    capture?: boolean;
+};
+/** Configure a group with a capture boolean or named-group options. */
+export type GroupOptions = GroupNamedOptions | boolean;
+/** Repetition bounds; specify either an exact count or a minimum and optional maximum. */
+export type QuantityNamedOptions = ({
+    exact: number;
+    min?: never;
+    max?: never;
+} | {
+    exact?: never;
+    min: number;
+    max?: number;
+}) & {
+    greedy?: boolean;
+};
+/** Repetition count, [minimum, maximum] tuple, or named bounds. */
+export type QuantityOptions = number | [min: number, max?: number] | QuantityNamedOptions;
+/** Compose lazy regex templates and resolve reusable variables in an isolated scope. */
+export declare class RegexDesigner {
+    private readonly variables;
+    private readonly resolvingVariables;
+    /** Concatenate patterns without adding groups or escaping. */
+    tpl(...patterns: RegexValue[]): RegexTemplate;
+    /** Join patterns with alternation without adding groups. */
+    or(...patterns: RegexValue[]): RegexTemplate;
+    /** Create a named capturing group around the concatenated patterns. */
+    named(name: string, ...patterns: RegexValue[]): RegexTemplate;
+    /** Group patterns, optionally capturing them or assigning a capture name. */
+    group(options: GroupOptions, ...patterns: RegexValue[]): RegexTemplate;
+    /** Make the concatenated patterns optional using a non-capturing group. */
+    opt(...patterns: RegexValue[]): RegexTemplate;
+    /** Repeat the concatenated patterns according to the supplied bounds. */
+    qty(quantity: QuantityOptions, ...patterns: RegexValue[]): RegexTemplate;
+    /** Escape literal text for use in a regex pattern. */
+    raw(...patterns: string[]): RegexTemplate;
+    /** Create a positive or negative lookahead assertion. */
+    ahead(positive: boolean, ...patterns: RegexValue[]): RegexTemplate;
+    /** Create a positive lookahead assertion. */
+    ahead_pos(...patterns: RegexValue[]): RegexTemplate;
+    /** Create a negative lookahead assertion. */
+    ahead_neg(...patterns: RegexValue[]): RegexTemplate;
+    /** Create a positive or negative lookbehind assertion. */
+    behind(positive: boolean, ...patterns: RegexValue[]): RegexTemplate;
+    /** Create a positive lookbehind assertion. */
+    behind_pos(...patterns: RegexValue[]): RegexTemplate;
+    /** Create a negative lookbehind assertion. */
+    behind_neg(...patterns: RegexValue[]): RegexTemplate;
+    /** Create a numeric or named backreference. */
+    ref(reference: number | string): RegexTemplate;
+    /** Define or replace a lazy pattern variable on this designer. */
+    set(name: string, ...patterns: RegexValue[]): this;
+    private resolveVariable;
+    /** Reference a variable, resolving it when this template is rendered. */
+    var(name: string): RegexTemplate;
+}
+/** Create a new regex designer with its own variable scope. */
+export default function create(): RegexDesigner;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,172 @@
+/** Check whether a value is a regex template. */
+export function isRegexTemplate(value) {
+    return typeof value === 'function' && 'render' in value && typeof value.render === 'function';
+}
+function patternString(pattern, flags, compiling) {
+    if (pattern instanceof RegExp) {
+        const unicodeFlag = pattern.flags.includes('v') ? 'v' : pattern.flags.includes('u') ? 'u' : undefined;
+        if (compiling && unicodeFlag !== undefined && !flags?.includes(unicodeFlag)) {
+            throw new TypeError(`RegExp flag "${unicodeFlag}" must be passed when compiling the composed pattern`);
+        }
+        const scopedFlags = pattern.flags.replace(/[dgyuv]/g, '');
+        return scopedFlags === '' ? pattern.source : `(?${scopedFlags}:${pattern.source})`;
+    }
+    if (isRegexTemplate(pattern)) {
+        return pattern.render(flags, compiling);
+    }
+    return pattern.toString();
+}
+function template(render) {
+    const regex = (flags) => new RegExp(regex.render(flags, true), flags);
+    regex.render = (flags, compiling = false) => render(flags, compiling);
+    regex.toString = () => regex.render();
+    return regex;
+}
+function tpl(...patterns) {
+    return template((flags, compiling) => patterns.map(pattern => patternString(pattern, flags, compiling)).join(''));
+}
+function or(...patterns) {
+    return template((flags, compiling) => patterns.map(pattern => patternString(pattern, flags, compiling)).join('|'));
+}
+function group(options, ...patterns) {
+    if (typeof options !== 'boolean' && options.name !== undefined && options.capture !== undefined) {
+        throw new TypeError('Group options "name" and "capture" are mutually exclusive');
+    }
+    return template((flags, compiling) => {
+        const name = typeof options === 'boolean' ? undefined : options.name;
+        const capture = typeof options === 'boolean' ? options : options.capture ?? true;
+        const prefix = name !== undefined ? `?<${name}>` : capture ? '' : '?:';
+        return `(${prefix}${patterns.map(pattern => patternString(pattern, flags, compiling)).join('')})`;
+    });
+}
+function named(name, ...patterns) {
+    return group({ name }, ...patterns);
+}
+function opt(...patterns) {
+    return template((flags, compiling) => `${patternString(group(false, ...patterns), flags, compiling)}?`);
+}
+function qty(quantity, ...patterns) {
+    let min;
+    let max;
+    let greedy = true;
+    if (typeof quantity === 'number') {
+        min = quantity;
+        max = quantity;
+    }
+    else if (Array.isArray(quantity)) {
+        [min, max] = quantity;
+    }
+    else if ('exact' in quantity) {
+        min = quantity.exact;
+        max = quantity.exact;
+        greedy = quantity.greedy ?? true;
+    }
+    else {
+        min = quantity.min;
+        max = quantity.max;
+        greedy = quantity.greedy ?? true;
+    }
+    if (!Number.isInteger(min) || min < 0 || (max !== undefined && max !== Infinity && (!Number.isInteger(max) || max < min))) {
+        throw new RangeError('Quantity bounds must be non-negative integers with max >= min');
+    }
+    return template((flags, compiling) => `${patternString(group(false, ...patterns), flags, compiling)}{${min}${max === undefined || max === Infinity ? ',' : max === min ? '' : `,${max}`}}${greedy ? '' : '?'}`);
+}
+function look(prefix, positive, patterns) {
+    return template((flags, compiling) => `(${prefix}${positive ? '=' : '!'}${patterns.map(pattern => patternString(pattern, flags, compiling)).join('')})`);
+}
+function raw(...patterns) {
+    return template(() => patterns.map(p => RegExp.escape(p)).join(''));
+}
+/** Compose lazy regex templates and resolve reusable variables in an isolated scope. */
+export class RegexDesigner {
+    variables = new Map();
+    resolvingVariables = [];
+    /** Concatenate patterns without adding groups or escaping. */
+    tpl(...patterns) {
+        return tpl(...patterns);
+    }
+    /** Join patterns with alternation without adding groups. */
+    or(...patterns) {
+        return or(...patterns);
+    }
+    /** Create a named capturing group around the concatenated patterns. */
+    named(name, ...patterns) {
+        return named(name, ...patterns);
+    }
+    /** Group patterns, optionally capturing them or assigning a capture name. */
+    group(options, ...patterns) {
+        return group(options, ...patterns);
+    }
+    /** Make the concatenated patterns optional using a non-capturing group. */
+    opt(...patterns) {
+        return opt(...patterns);
+    }
+    /** Repeat the concatenated patterns according to the supplied bounds. */
+    qty(quantity, ...patterns) {
+        return qty(quantity, ...patterns);
+    }
+    /** Escape literal text for use in a regex pattern. */
+    raw(...patterns) {
+        return raw(...patterns);
+    }
+    /** Create a positive or negative lookahead assertion. */
+    ahead(positive, ...patterns) {
+        return look('?', positive, patterns);
+    }
+    /** Create a positive lookahead assertion. */
+    ahead_pos(...patterns) {
+        return look('?', true, patterns);
+    }
+    /** Create a negative lookahead assertion. */
+    ahead_neg(...patterns) {
+        return look('?', false, patterns);
+    }
+    /** Create a positive or negative lookbehind assertion. */
+    behind(positive, ...patterns) {
+        return look('?<', positive, patterns);
+    }
+    /** Create a positive lookbehind assertion. */
+    behind_pos(...patterns) {
+        return look('?<', true, patterns);
+    }
+    /** Create a negative lookbehind assertion. */
+    behind_neg(...patterns) {
+        return look('?<', false, patterns);
+    }
+    /** Create a numeric or named backreference. */
+    ref(reference) {
+        return template(() => typeof reference === 'number' ? `\\${reference}` : `\\k<${reference}>`);
+    }
+    /** Define or replace a lazy pattern variable on this designer. */
+    set(name, ...patterns) {
+        this.variables.set(name, tpl(...patterns));
+        return this;
+    }
+    resolveVariable(name, flags, compiling) {
+        const cycleStart = this.resolvingVariables.indexOf(name);
+        if (cycleStart !== -1) {
+            const cycle = [...this.resolvingVariables.slice(cycleStart), name];
+            throw new Error(`Circular variable dependency: ${cycle.join(' -> ')}`);
+        }
+        const pattern = this.variables.get(name);
+        if (pattern === undefined) {
+            throw new Error(`Variable "${name}" is not set`);
+        }
+        this.resolvingVariables.push(name);
+        try {
+            return patternString(pattern, flags, compiling);
+        }
+        finally {
+            this.resolvingVariables.pop();
+        }
+    }
+    /** Reference a variable, resolving it when this template is rendered. */
+    var(name) {
+        return template((flags, compiling) => this.resolveVariable(name, flags, compiling));
+    }
+}
+/** Create a new regex designer with its own variable scope. */
+export default function create() {
+    return new RegexDesigner();
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,iDAAiD;AACjD,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,OAAO,KAAK,KAAK,UAAU,IAAI,QAAQ,IAAI,KAAK,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,UAAU,CAAC;AAChG,CAAC;AA2BD,SAAS,aAAa,CAAC,OAAmB,EAAE,KAAyB,EAAE,SAAkB;IACvF,IAAI,OAAO,YAAY,MAAM,EAAE,CAAC;QAC9B,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QACtG,IAAI,SAAS,IAAI,WAAW,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YAC5E,MAAM,IAAI,SAAS,CAAC,gBAAgB,WAAW,sDAAsD,CAAC,CAAC;QACzG,CAAC;QAED,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAC1D,OAAO,WAAW,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;IACrF,CAAC;IAED,IAAI,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED,SAAS,QAAQ,CAAC,MAAiE;IACjF,MAAM,KAAK,GAAkB,CAAC,KAAc,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;IAC9F,KAAK,CAAC,MAAM,GAAG,CAAC,KAAc,EAAE,SAAS,GAAG,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC/E,KAAK,CAAC,QAAQ,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;IACtC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,GAAG,CAAC,GAAG,QAAsB;IACpC,OAAO,QAAQ,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;AACpH,CAAC;AAED,SAAS,EAAE,CAAC,GAAG,QAAsB;IACnC,OAAO,QAAQ,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACrH,CAAC;AAED,SAAS,KAAK,CAAC,OAAqB,EAAE,GAAG,QAAsB;IAC7D,IAAI,OAAO,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChG,MAAM,IAAI,SAAS,CAAC,2DAA2D,CAAC,CAAC;IACnF,CAAC;IAED,OAAO,QAAQ,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE;QACnC,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;QACrE,MAAM,OAAO,GAAG,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC;QACjF,MAAM,MAAM,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACvE,OAAO,IAAI,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;IACpG,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,KAAK,CAAC,IAAY,EAAE,GAAG,QAAsB;IACpD,OAAO,KAAK,CAAC,EAAE,IAAI,EAAE,EAAE,GAAG,QAAQ,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,GAAG,CAAC,GAAG,QAAsB;IACpC,OAAO,QAAQ,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,QAAQ,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC;AAC1G,CAAC;AAED,SAAS,GAAG,CAAC,QAAyB,EAAE,GAAG,QAAsB;IAC/D,IAAI,GAAW,CAAC;IAChB,IAAI,GAAuB,CAAC;IAC5B,IAAI,MAAM,GAAG,IAAI,CAAC;IAElB,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,GAAG,GAAG,QAAQ,CAAC;QACf,GAAG,GAAG,QAAQ,CAAC;IACjB,CAAC;SAAM,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnC,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,QAAQ,CAAC;IACxB,CAAC;SAAM,IAAI,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC;QACrB,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC;QACrB,MAAM,GAAG,QAAQ,CAAC,MAAM,IAAI,IAAI,CAAC;IACnC,CAAC;SAAM,CAAC;QACN,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC;QACnB,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC;QACnB,MAAM,GAAG,QAAQ,CAAC,MAAM,IAAI,IAAI,CAAC;IACnC,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC;QAC1H,MAAM,IAAI,UAAU,CAAC,+DAA+D,CAAC,CAAC;IACxF,CAAC;IAED,OAAO,QAAQ,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,QAAQ,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,GAAG,GAAG,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;AAClN,CAAC;AAED,SAAS,IAAI,CAAC,MAAc,EAAE,QAAiB,EAAE,QAAsB;IACrE,OAAO,QAAQ,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,IAAI,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;AAC3J,CAAC;AAED,SAAS,GAAG,CAAC,GAAG,QAAkB;IAChC,OAAO,QAAQ,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;AACtE,CAAC;AAED,wFAAwF;AACxF,MAAM,OAAO,aAAa;IACP,SAAS,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC1C,kBAAkB,GAAa,EAAE,CAAC;IAEnD,8DAA8D;IAC9D,GAAG,CAAC,GAAG,QAAsB;QAC3B,OAAO,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;IAC1B,CAAC;IAED,4DAA4D;IAC5D,EAAE,CAAC,GAAG,QAAsB;QAC1B,OAAO,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC;IACzB,CAAC;IAED,uEAAuE;IACvE,KAAK,CAAC,IAAY,EAAE,GAAG,QAAsB;QAC3C,OAAO,KAAK,CAAC,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED,6EAA6E;IAC7E,KAAK,CAAC,OAAqB,EAAE,GAAG,QAAsB;QACpD,OAAO,KAAK,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAC,CAAC;IACrC,CAAC;IAED,2EAA2E;IAC3E,GAAG,CAAC,GAAG,QAAsB;QAC3B,OAAO,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;IAC1B,CAAC;IAED,yEAAyE;IACzE,GAAG,CAAC,QAAyB,EAAE,GAAG,QAAsB;QACtD,OAAO,GAAG,CAAC,QAAQ,EAAE,GAAG,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED,sDAAsD;IACtD,GAAG,CAAC,GAAG,QAAkB;QACvB,OAAO,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;IAC1B,CAAC;IAED,yDAAyD;IACzD,KAAK,CAAC,QAAiB,EAAE,GAAG,QAAsB;QAChD,OAAO,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,6CAA6C;IAC7C,SAAS,CAAC,GAAG,QAAsB;QACjC,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED,6CAA6C;IAC7C,SAAS,CAAC,GAAG,QAAsB;QACjC,OAAO,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED,0DAA0D;IAC1D,MAAM,CAAC,QAAiB,EAAE,GAAG,QAAsB;QACjD,OAAO,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,8CAA8C;IAC9C,UAAU,CAAC,GAAG,QAAsB;QAClC,OAAO,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED,8CAA8C;IAC9C,UAAU,CAAC,GAAG,QAAsB;QAClC,OAAO,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IACrC,CAAC;IAED,+CAA+C;IAC/C,GAAG,CAAC,SAA0B;QAC5B,OAAO,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC,CAAC,CAAC,OAAO,SAAS,GAAG,CAAC,CAAC;IAChG,CAAC;IAED,kEAAkE;IAClE,GAAG,CAAC,IAAY,EAAE,GAAG,QAAsB;QACzC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,eAAe,CAAC,IAAY,EAAE,KAAyB,EAAE,SAAkB;QACjF,MAAM,UAAU,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACzD,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;YACtB,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,CAAC;YACnE,MAAM,IAAI,KAAK,CAAC,iCAAiC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACzE,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,cAAc,CAAC,CAAC;QACnD,CAAC;QAED,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC;YACH,OAAO,aAAa,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;QAClD,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,kBAAkB,CAAC,GAAG,EAAE,CAAC;QAChC,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,GAAG,CAAC,IAAY;QACd,OAAO,QAAQ,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;IACtF,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,CAAC,OAAO,UAAU,MAAM;IAC5B,OAAO,IAAI,aAAa,EAAE,CAAC;AAC7B,CAAC"}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@regex-designer/js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A small TypeScript library for composing JavaScript regular expressions in a readable, reusable way.",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "regex",
+    "regexp",
+    "pattern",
+    "builder"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "npm run build && tsc -p tsconfig.test.json",
+    "lint": "eslint .",
+    "test": "npm run typecheck && node --test test/*.test.ts",
+    "check": "npm run lint && npm run test"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/node": "24.19.2",
+    "eslint": "10.12.0",
+    "globals": "17.13.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.71.1"
+  }
+}