wildling

TypeScript library and CLI for pattern-based string generation. Runtime has zero npm dependencies (Node.js only); TypeScript is a build-time devDependency.

Docs: Website · Sandbox · Syntax · Source

Registry: npm

Example

http://${'dev,stage,prod'}\-${'api,web'}#{0-2}.example.${'com,net,org'}/@.html

(The \- is a literal hyphen; bare - would mean “one letter or digit”. @ is one lowercase letter.)

That builds URL-shaped candidates: scheme http://, then environment × service × optional digits × TLD, then a one-letter path page. Three environments, two services, zero–two digits ('', 0–9, 00–99), three TLDs, and a–z → 51948 strings — the kind of list you generate for fuzzing links or probing staging hosts, not type out.

A few of them:

• http://dev-api.example.com/a.html / http://stage-web.example.com/z.html
• http://dev-api0.example.net/a.html / http://prod-web9.example.org/m.html
• http://dev-api00.example.com/a.html / http://prod-web99.example.org/z.html

Named dictionaries (%{'hosts'}) work the same way when the word lists live in files.

Try it in the sandbox, or see pattern syntax for length ranges, dictionaries, and escapes.

Install

Registry:

npm install wildling

Git (monorepo subdirectory): current npm does not reliably resolve the #tag:subdir / github:…#tag:subdir forms for this repo. Prefer a tagged clone, then install from the javascript/ tree (run npm ci --include=dev && npm run build there first if dist/ is missing):

git clone --branch v2.0.7 --depth 1 https://github.com/dotmonk/wildling.git
cd wildling/javascript
npm ci --include=dev
npm run build
cd /path/to/your-app
npm install /path/to/wildling/javascript

prepare builds dist/ when missing on install (Node 18+, network for TypeScript on first install).

From this repository:

cd javascript
npm ci --include=dev
npm run build

The CLI is ./bin/wildling (or npx wildling after install). The library entry is dist/index.js.

Library

const createWildling = require("wildling").default;
// or: import createWildling from "wildling";

const wildling = createWildling({
  patterns: ["abrakadabra", "Year 19##"],
  dictionaries: {
    colors: ["red", "blue"],
  },
});

wildling.count(); // 101
wildling.get(0); // "abrakadabra"

let value;
while ((value = wildling.next()) !== false) {
  console.log(value);
}

wildling.reset();

Options

| Field | Type | Description | |-------|------|-------------| | patterns | string[] | One or more patterns to expand | | dictionaries | { [name: string]: string[] } | Named word lists for %{'name'} |

API

| Method | Description | |--------|-------------| | next() | Next combination, or false when exhausted | | get(index) | Combination at index, or false if out of range | | count() | Total combinations across all patterns | | index() | Current position (after next calls) | | reset() | Reset iteration to the start | | generators() | Per-pattern generators |

CLI

wildling [options] [pattern ...]

| Option | Description | |--------|-------------| | --select # | Print only combination # (repeatable) | | --range #-# | Print combinations from # to # inclusive (repeatable) | | --check | Print generation info instead of results | | --dictionary <name>:<path> | Load a dictionary file as <name> (repeatable) | | --template <path> | Load options from a JSON template | | --help, -h | Help (shared text from docs/help.txt) | | --version, -v | Version |

--check and help text follow the cross-language contracts in docs/cli.md.

Examples:

./bin/wildling "Year 19##"
./bin/wildling --dictionary planets:../dictionaries/planets.txt "%{'planets'}"
./bin/wildling --select 0 --range 8-9 "##"
./bin/wildling --template ./config.json

Template JSON

{
  "patterns": ["Year 19##", "%{'colors'}"],
  "dictionaries": {
    "colors": "path/to/colors.txt",
    "inline": ["red", "blue"]
  },
  "select": [0, 2],
  "range": ["5-7"],
  "check": false
}

Dictionary values may be a file path or an inline string array. Template fields merge with CLI flags in argument order.

Patterns

Simple wildcards

| Token | Alphabet | |-------|----------| | # | 0-9 | | @ | a-z | | * | a-z and 0-9 | | & | a-zA-Z | | ! | A-Z | | ? | A-Z and 0-9 | | - | a-zA-Z0-9 |

Optional length: #{2}, @{1-2}, *{1-2} (start–end inclusive).

Special wildcards

${'blue,red,green',1-2}   words / punctuation from a list
%{'colors'}               dictionary named "colors"
%{'colors',1-2}           dictionary with length range

Escape a wildcard with a backslash: \## → #0 … #9.

Build

npm run build
# or from repo root: ./build.sh  (Docker)

Project tests live in ../tests/ and are run with ../test.sh.