@ptolemy2002/rgx 1.0.0

package/README.md

@@ -0,0 +1,187 @@
+# RGX
+A library for easy construction and validation of regular expressions in TypeScript. You can use `rgx` to concatenate various types of tokens into a valid regular expression string, with type safety and validation.
+
+## Type Reference
+```typescript
+import { Branded } from "@ptolemy2002/ts-brand-utils";
+
+type RGXNoOpToken = null | undefined;
+type RGXNativeToken = string | number | boolean | RGXNoOpToken;
+type RGXConvertibleToken = { toRgx: () => RGXNativeToken | RGXNativeToken[] };
+type RGXToken = RGXNativeToken | RGXConvertibleToken | RGXToken[];
+
+const validRegexSymbol = Symbol('ValidRegex');
+type ValidRegexBrandSymbol = typeof validRegexSymbol;
+type ValidRegexString = Branded<string, [ValidRegexBrandSymbol]>;
+
+type RGXTokenType = 'no-op' | 'native' | 'convertible' | RGXTokenType[];
+type RGXTokenFromType<T extends RGXTokenType> =
+    // ... see source for full definition
+;
+```
+
+## Functions
+The following functions are exported by the library:
+
+### isRGXNoOpToken
+```typescript
+function isRGXNoOpToken(value: unknown): value is RGXNoOpToken
+```
+
+Checks if the given value is a no-op token (`null` or `undefined`).
+
+#### Parameters
+  - `value` (`unknown`): The value to check.
+
+#### Returns
+- `boolean`: `true` if the value is a no-op token, otherwise `false`.
+
+### isRGXNativeToken
+```typescript
+function isRGXNativeToken(value: unknown): value is RGXNativeToken
+```
+
+Checks if the given value is a native token (string, number, boolean, or no-op).
+
+#### Parameters
+  - `value` (`unknown`): The value to check.
+
+#### Returns
+- `boolean`: `true` if the value is a native token, otherwise `false`.
+
+### isRGXConvertibleToken
+```typescript
+function isRGXConvertibleToken(value: unknown): value is RGXConvertibleToken
+```
+
+Checks if the given value is a convertible token (an object with a `toRgx` method). Validates that `toRgx` is callable and returns a valid RGX native token or array of native tokens.
+
+#### Parameters
+  - `value` (`unknown`): The value to check.
+
+#### Returns
+- `boolean`: `true` if the value is a convertible token, otherwise `false`.
+
+### rgxTokenType
+```typescript
+function rgxTokenType(value: RGXToken): RGXTokenType
+```
+
+Determines the type of a given RGX token (`no-op`, `native`, `convertible`, or an array of the former).
+
+If you narrow the result of this function to something more specific, you can then convert these string or array literals into their corresponding token types using the `RGXTokenFromType` utility type or `rgxTokenFromType` function.
+
+```typescript
+const token: RGXToken = ...;
+const type = rgxTokenType(token);
+
+if (type === 'native') {
+    const narrowedToken1 = token as RGXTokenFromType<typeof type>; // narrowedToken is RGXNativeToken
+    const narrowedToken2 = rgxTokenFromType(type, token); // same as above
+}
+```
+
+#### Parameters
+  - `value` (`RGXToken`): The RGX token to check.
+
+#### Returns
+- `RGXTokenType`: The type of the RGX token.
+
+### rgxTokenFromType
+```typescript
+function rgxTokenFromType<T extends RGXTokenType>(type: T, value: RGXToken): RGXTokenFromType<T>
+```
+
+Does nothing at runtime, but performs a type assertion to the correct subset of `RGXToken` based on the provided `RGXTokenType`.
+
+#### Parameters
+  - `type` (`T`): The RGX token type to assert to.
+  - `value` (`RGXToken`): The RGX token to assert.
+
+#### Returns
+- `RGXTokenFromType<T>`: The input value, but with its type asserted to the corresponding token type based on the provided `RGXTokenType`.
+
+### isValidRegex
+```typescript
+function isValidRegex(value: string): value is ValidRegexString
+```
+
+Checks if the given string is a valid regular expression by attempting to create a new `RegExp` object with it. If it succeeds, the string is branded as a `ValidRegexString`.
+
+#### Parameters
+  - `value` (`string`): The string to check.
+
+#### Returns
+- `boolean`: `true` if the string is a valid regular expression, otherwise `false`.
+
+### escapeRegex
+```typescript
+function escapeRegex(value: string): ValidRegexString
+```
+
+Escapes special regex characters in the given string and brands the result as a `ValidRegexString`.
+
+#### Parameters
+  - `value` (`string`): The string to escape.
+
+#### Returns
+- `ValidRegexString`: The escaped string, branded as a valid regex string.
+
+### resolveRGXToken
+```typescript
+function resolveRGXToken(token: RGXToken): string
+```
+
+Resolves an RGX token to a string. No-op tokens resolve to an empty string, native tokens are converted to strings and escaped, convertible tokens are converted using their `toRgx` method and then resolved recursively, and arrays of tokens are resolved as unions of their resolved elements (placed in a non-capturing group).
+
+#### Parameters
+  - `token` (`RGXToken`): The RGX token to resolve.
+
+#### Returns
+- `string`: The resolved string representation of the RGX token.
+
+### rgx
+```typescript
+function rgx(strings: TemplateStringsArray, ...tokens: RGXToken[]): RegExp
+```
+
+A template tag function that constructs a `RegExp` object from the provided template literal. The template literal can contain RGX tokens, which will be resolved and concatenated with the literal parts to form the final regex pattern.
+
+Example usages:
+```typescript
+const beginning = /^/;
+const end = /$/;
+const word = /\w+/;
+const pattern = rgx`${beginning}testing ${word}${end}`; // /^testing \w+$/ - matches the string "testing " followed by a word, anchored to the start and end of the string
+
+const optionalDigit = /\d?/;
+const pattern2 = rgx`${beginning}optional digit: ${optionalDigit}${end}`; // /^optional digit: \d?$/ - matches the string "optional digit: " followed by an optional digit, anchored to the start and end of the string
+
+const pattern3 = rgx`${beginning}value: ${[word, optionalDigit]}${end}`; // /^value: (?:\w+|\d?)$/ - matches the string "value: " followed by either a word or an optional digit, anchored to the start and end of the string
+```
+
+#### Parameters
+  - `strings` (`TemplateStringsArray`): The literal parts of the template string.
+  - `tokens` (`RGXToken[]`): The RGX tokens to be resolved and concatenated with the literal parts.
+
+#### Returns
+- `RegExp`: The resulting regular expression object constructed from the template literal.
+
+## Peer Dependencies
+- `@ptolemy2002/ts-brand-utils` ^1.0.0
+- `@ptolemy2002/ts-utils` ^3.4.0
+- `is-callable` ^1.2.7
+
+## Commands
+The following commands exist in the project:
+
+- `npm run uninstall` - Uninstalls all dependencies for the library
+- `npm run reinstall` - Uninstalls and then Reinstalls all dependencies for the library
+- `npm run build` - Builds the library
+- `npm run release` - Publishes the library to npm without changing the version
+- `npm run release-patch` - Publishes the library to npm with a patch version bump
+- `npm run release-minor` - Publishes the library to npm with a minor version bump
+- `npm run release-major` - Publishes the library to npm with a major version bump
+- `npm run test` - Runs the tests for the library
+- `npm run test:watch` - Runs the tests for the library in watch mode
+- `npm run test:coverage` - Runs the tests for the library and generates a coverage report

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { Branded } from "@ptolemy2002/ts-brand-utils";
+export type RGXNoOpToken = null | undefined;
+export type RGXNativeToken = string | number | boolean | RGXNoOpToken;
+export type RGXConvertibleToken = {
+    toRgx: () => RGXNativeToken | RGXNativeToken[];
+};
+export type RGXToken = RGXNativeToken | RGXConvertibleToken | RGXToken[];
+export type RGXTokenType = 'no-op' | 'native' | 'convertible' | RGXTokenType[];
+export type RGXTokenFromType<T extends RGXTokenType> = T extends 'no-op' ? RGXNoOpToken : T extends 'native' ? RGXNativeToken : T extends 'convertible' ? RGXConvertibleToken : T extends RGXTokenType[] ? {
+    [K in keyof T]: T[K] extends RGXTokenType ? RGXTokenFromType<T[K]> : never;
+} : never;
+export declare const validRegexSymbol: unique symbol;
+export type ValidRegexBrandSymbol = typeof validRegexSymbol;
+export type ValidRegexString = Branded<string, [ValidRegexBrandSymbol]>;
+export declare function isRGXNoOpToken(value: unknown): value is RGXNoOpToken;
+export declare function isRGXNativeToken(value: unknown): value is RGXNativeToken;
+export declare function isRGXConvertibleToken(value: unknown): value is RGXConvertibleToken;
+export declare function rgxTokenType(value: RGXToken): RGXTokenType;
+export declare function rgxTokenFromType<T extends RGXTokenType>(type: T, value: RGXToken): RGXTokenFromType<T>;
+export declare function isValidRegex(value: string): value is ValidRegexString;
+export declare function escapeRegex(value: string): ValidRegexString;
+export declare function resolveRGXToken(token: RGXToken): string;
+export default function rgx(strings: TemplateStringsArray, ...tokens: RGXToken[]): RegExp;

package/dist/index.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validRegexSymbol = void 0;
+exports.isRGXNoOpToken = isRGXNoOpToken;
+exports.isRGXNativeToken = isRGXNativeToken;
+exports.isRGXConvertibleToken = isRGXConvertibleToken;
+exports.rgxTokenType = rgxTokenType;
+exports.rgxTokenFromType = rgxTokenFromType;
+exports.isValidRegex = isValidRegex;
+exports.escapeRegex = escapeRegex;
+exports.resolveRGXToken = resolveRGXToken;
+exports.default = rgx;
+const is_callable_1 = __importDefault(require("is-callable"));
+exports.validRegexSymbol = Symbol('ValidRegex');
+function isRGXNoOpToken(value) {
+    return value === null || value === undefined;
+}
+function isRGXNativeToken(value) {
+    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || isRGXNoOpToken(value);
+}
+function isRGXConvertibleToken(value) {
+    if (typeof value === 'object' && value !== null && 'toRgx' in value) {
+        if ((0, is_callable_1.default)(value.toRgx)) {
+            const returnValue = value.toRgx();
+            if (Array.isArray(returnValue)) {
+                return returnValue.every(isRGXNativeToken);
+            }
+            return isRGXNativeToken(returnValue);
+        }
+        return false;
+    }
+    return false;
+}
+function rgxTokenType(value) {
+    if (isRGXNoOpToken(value))
+        return 'no-op';
+    if (isRGXNativeToken(value))
+        return 'native';
+    if (isRGXConvertibleToken(value))
+        return 'convertible';
+    if (Array.isArray(value))
+        return value.map(rgxTokenType);
+    // Ignoring this line since it should be impossible to reach if the types are correct, but we need it to satisfy the return type
+    /* istanbul ignore next */
+    throw new TypeError(`Invalid RGX token: ${value}`);
+}
+function rgxTokenFromType(type, value) {
+    // Ignoring this line because the function is entirely a TypeScript utility that doesn't need to be tested at runtime.
+    /* istanbul ignore next */
+    return value;
+}
+function isValidRegex(value) {
+    try {
+        new RegExp(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function escapeRegex(value) {
+    return value.replaceAll(/[\-\^\$.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function resolveRGXToken(token) {
+    if (isRGXNoOpToken(token))
+        return '';
+    if (isRGXNativeToken(token))
+        return escapeRegex(String(token));
+    if (isRGXConvertibleToken(token)) {
+        return resolveRGXToken(token.toRgx());
+    }
+    // Interpret arrays as unions
+    if (Array.isArray(token)) {
+        if (token.length === 0)
+            return '';
+        if (token.length > 1) {
+            return '(?:' + token.map(resolveRGXToken).join('|') + ')';
+        }
+        return resolveRGXToken(token[0]);
+    }
+    // Ignoring this line since it should be impossible to reach if the types are correct, but we need it to satisfy the return type
+    /* istanbul ignore next */
+    throw new TypeError(`Invalid RGX token: ${token}`);
+}
+function rgx(strings, ...tokens) {
+    let pattern = '';
+    const resolvedTokens = tokens.map(resolveRGXToken);
+    for (let i = 0; i < strings.length; i++) {
+        pattern += strings[i];
+        if (i < resolvedTokens.length) {
+            pattern += resolvedTokens[i];
+        }
+    }
+    return new RegExp(pattern);
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "@ptolemy2002/rgx",
+    "version": "1.0.0",
+    "private": false,
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "/dist"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Ptolemy2002/rgx",
+        "directory": "lib"
+    },
+    "scripts": {
+        "prepare": "npx ts-patch install -s",
+        "build": "bash ./scripts/build.sh",
+        "_build": "tsc --project ./tsconfig.build.json",
+        "typecheck": "tsc --noEmit",
+        "test": "jest",
+        "test:watch": "jest --watch",
+        "test:coverage": "jest --coverage",
+        "postinstall": "npx typesync",
+        "uninstall": "bash ./scripts/uninstall.sh",
+        "reinstall": "bash ./scripts/reinstall.sh",
+        "release": "bash ./scripts/release.sh",
+        "release-patch": "bash ./scripts/release.sh patch",
+        "release-minor": "bash ./scripts/release.sh minor",
+        "release-major": "bash ./scripts/release.sh major"
+    },
+    "devDependencies": {
+        "@ptolemy2002/ts-brand-utils": "^1.0.0",
+        "@ptolemy2002/ts-utils": "^3.4.0",
+        "@types/is-callable": "^1.1.2",
+        "@types/jest": "^29.5.0",
+        "is-callable": "^1.2.7",
+        "jest": "^29.5.0",
+        "ts-jest": "^29.1.0",
+        "ts-patch": "^3.3.0",
+        "tsconfig-paths": "^4.2.0",
+        "typescript-transform-paths": "^3.5.3"
+    },
+    "peerDependencies": {
+        "@ptolemy2002/ts-brand-utils": "^1.0.0",
+        "@ptolemy2002/ts-utils": "^3.4.0",
+        "is-callable": "^1.2.7"
+    }
+}