@jround/re-template-tag 0.0.0-stage → 3.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2017 Axel Rauschmayer
+Copyright (c) 2026 Jesus Redondo
+
+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,89 @@
-# Temporary Holding Version
+# @jround/re-template-tag: easily compose regular expressions
 
-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.
+This package provides the template tag `re` for composing regular expressions.
+
+It is a TypeScript fork of [rauschma/re-template-tag](https://github.com/rauschma/re-template-tag),
+published as `@jround/re-template-tag`. The unscoped `re-template-tag` on npm is the original 2.0.1.
+
+## Install
+
+```sh
+npm install @jround/re-template-tag
+```
+
+Requirements:
+
+* Node.js 24 or newer.
+* ES module. Use `import`, or `require()` on Node.js 24, which loads ES modules.
+* Type declarations are included. Do not install `@types/re-template-tag`.
+
+## Basic syntax
+
+Syntax: the following two expressions produce the same regular expression.
+
+```js
+re`/abc/gu`
+/abc/gu
+```
+
+## Composing regular expressions
+
+```js
+import {re} from '@jround/re-template-tag';
+
+const RE_YEAR = /([0-9]{4})/;
+const RE_MONTH = /([0-9]{2})/;
+const RE_DAY = /([0-9]{2})/;
+const RE_DATE = re`/^${RE_YEAR}-${RE_MONTH}-${RE_DAY}$/u`;
+
+RE_DATE.test('2017-01-23'); // true
+```
+
+A `RegExp` substitution inserts its source. A string substitution is matched literally.
+Any other substitution throws `Error`.
+
+## Escaping text
+
+`quoteText` escapes every regular expression metacharacter, including inside parentheses
+or a character class. `re` applies it to every string substitution.
+
+```js
+import {quoteText} from '@jround/re-template-tag';
+
+quoteText('1+1=2'); // '1\\+1\\x3d2'
+```
+
+`- = ! < > :` become hex escapes such as `\x2d`, because the `u` and `v` flags reject a
+backslash before them. The result is a literal match with any flags.
+
+## Checks
+
+```sh
+npm run typecheck
+npm run lint
+npm run build
+npm test
+```
+
+`npm test` builds first, then the unit tests import the package by its own name,
+which resolves through `exports` to `dist/index.js`.
+
+## Releases
+
+Changes are listed in [CHANGELOG.md](./CHANGELOG.md). Pushing a tag `vX.Y.Z` that matches the
+`version` in `package.json` publishes that version to npm with provenance.
+
+## More information
+
+* Take a look at [the unit tests](https://github.com/JSRound/re-template-tag/blob/master/test/index.test.js).
+* Check out [the blog post on re-template-tag](http://2ality.com/2017/07/re-template-tag.html).
+
+## Related work
+
+* http://xregexp.com
+* https://github.com/DmitrySoshnikov/regexp-tree
+* https://github.com/shannonmoeller/regx
+
+## Acknowledgement
+
+The syntax for separating flags from the actual regular expression is based on an idea by [Mathias Bynens](https://twitter.com/mathias/).

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/** A pattern fragment, or text that must be matched literally. */
+type PatternSubstitution = RegExp | string;
+/**
+ * Compose a regular expression.
+ * A `RegExp` substitution inserts its source. A string substitution is escaped.
+ * Start the template with `/` to set flags: `` re`/pattern/flags` ``.
+ */
+export declare function re(template: TemplateStringsArray, ...substitutions: readonly PatternSubstitution[]): RegExp;
+/**
+ * Escape every regex metacharacter, including inside parentheses or a character class.
+ * The result is valid with any flags, including `u` and `v`.
+ */
+export declare function quoteText(text: string): string;
+export {};

package/dist/index.js

@@ -0,0 +1,86 @@
+const FLAGS = /^[dgimsuvy]*$/;
+/**
+ * Compose a regular expression.
+ * A `RegExp` substitution inserts its source. A string substitution is escaped.
+ * Start the template with `/` to set flags: `` re`/pattern/flags` ``.
+ */
+export function re(template, ...substitutions) {
+    const pattern = composePattern(template, substitutions);
+    const { source, flags } = splitPattern(pattern);
+    return new RegExp(source, flags);
+}
+function composePattern(template, substitutions) {
+    let pattern = transformRaw(template.raw[0] ?? '');
+    for (const [index, substitution] of substitutions.entries()) {
+        pattern += substitutionText(substitution);
+        pattern += transformRaw(template.raw[index + 1] ?? '');
+    }
+    return pattern;
+}
+function substitutionText(substitution) {
+    if (isRegExpFragment(substitution)) {
+        return substitution.source;
+    }
+    if (isLiteralText(substitution)) {
+        return quoteText(substitution);
+    }
+    throw new Error(`Illegal substitution: ${String(substitution)}`);
+}
+function isRegExpFragment(substitution) {
+    return substitution instanceof RegExp;
+}
+function isLiteralText(substitution) {
+    return typeof substitution === 'string';
+}
+function splitPattern(pattern) {
+    if (!startsWithDelimiter(pattern)) {
+        return { source: pattern, flags: '' };
+    }
+    const closingSlash = pattern.lastIndexOf('/');
+    if (isMissingClosingSlash(closingSlash)) {
+        throw new Error(missingClosingSlashMessage(pattern));
+    }
+    const flags = pattern.slice(closingSlash + 1);
+    if (!isFlagString(flags)) {
+        throw new Error(`Invalid regular expression flags: ${flags}`);
+    }
+    return { source: pattern.slice(1, closingSlash), flags };
+}
+function startsWithDelimiter(pattern) {
+    return pattern.startsWith('/');
+}
+function isMissingClosingSlash(closingSlash) {
+    return closingSlash === 0;
+}
+function isFlagString(flags) {
+    return FLAGS.test(flags);
+}
+function missingClosingSlashMessage(pattern) {
+    return ('If the `re` string starts with a slash, it must end with a second slash and zero or more flags: ' +
+        pattern);
+}
+function transformRaw(text) {
+    return text.replace(/\\`/g, '`');
+}
+/**
+ * Escape every regex metacharacter, including inside parentheses or a character class.
+ * The result is valid with any flags, including `u` and `v`.
+ */
+export function quoteText(text) {
+    return text.replace(/[\\^$.*+?()[\]{}|=!<>:-]/g, escapeCharacter);
+}
+/** Characters that `u` and `v` mode accept after a backslash. */
+const SYNTAX_CHARACTER = /^[\\^$.*+?()[\]{}|]$/;
+function escapeCharacter(character) {
+    if (isSyntaxCharacter(character)) {
+        return `\\${character}`;
+    }
+    return hexEscape(character);
+}
+function isSyntaxCharacter(character) {
+    return SYNTAX_CHARACTER.test(character);
+}
+/** `-` becomes `\x2d`: a literal in every flag mode, never a range inside a character class. */
+function hexEscape(character) {
+    return `\\x${character.charCodeAt(0).toString(16).padStart(2, '0')}`;
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@jround/re-template-tag",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.0.1",
+  "description": "Template tag that composes regular expressions from RegExp and escaped string fragments.",
+  "keywords": [
+    "regexp",
+    "regular-expression",
+    "template-tag",
+    "tagged-template"
+  ],
+  "homepage": "https://github.com/JSRound/re-template-tag#readme",
+  "bugs": "https://github.com/JSRound/re-template-tag/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "build": "tsc -p tsconfig.build.json",
+    "pretest": "npm run build",
+    "test": "node --test",
+    "check:tarball": "node scripts/check-tarball.mjs",
+    "prepare": "npm run build"
+  },
+  "author": "Axel Rauschmayer",
+  "contributors": [
+    "Jesus Redondo <github@jesusredondo.com>"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JSRound/re-template-tag.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.6.4",
+    "eslint": "^10.12.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.1"
+  }
+}