wildling

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.