Faker.js, byte for byte, in a Go binary.
go-fakerjs runs Faker.js inside a Go program, so Go code can generate the same fake data that Faker.js generates from the same seed, value for value. Faker.js and the QuickJS-NG interpreter are compiled to WebAssembly and then translated into Go source, so the package builds with CGO_ENABLED=0, needs no Wasm runtime, and imports nothing outside the standard library. Of 2,240 test cases across all 262 Faker.js methods, 2,235 match Faker.js byte for byte; the other 5 need Intl, which the interpreter doesn't have.
I built it to get Faker.js output in Go, exact to the byte and reproducible from a seed, without cgo. A Go reimplementation of Faker can't match its output value for value, and each bridge in use today has a cost: v8go needs cgo and a prebuilt V8 library for every platform, wazero with QuickJS adds a third-party module and evaluates the Faker.js bundle every time an engine starts, and calling out to Node needs Node installed wherever the Go program runs. go-fakerjs replaces them with one Go module that runs Faker.js itself.
Requires Go 1.27.1 or later. Create a module and add go-fakerjs to it:
mkdir fakerdemo && cd fakerdemo
go mod init fakerdemo
go get github.com/iamramtin/go-fakerjs@latestSave this as main.go:
package main
import (
"fmt"
"log"
"time"
"github.com/iamramtin/go-fakerjs"
)
func main() {
// The same seed and reference date give the same values on every run.
e := fakerjs.NewEngine(42, fakerjs.WithRefDate(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)))
defer e.Close()
// show calls one Faker.js method. arg is nil for no argument, or any value encoding/json accepts.
show := func(method string, arg any) {
v, err := e.Generate(method, arg)
if err != nil {
fmt.Printf("%-22s error: %v\n", method, err)
return
}
fmt.Printf("%-22s %s\n", method, v)
}
show("person.fullName", nil) // text
show("number.int", map[string]any{"max": 100}) // a number
show("datatype.boolean", nil) // a boolean
show("date.recent", nil) // a Date
show("helpers.arrayElements", []string{"red", "green", "blue"}) // an array
show("airline.airline", nil) // an object
show("person.nickname", nil) // not a Faker.js method
// GenerateN returns several values from one call into the engine.
codes, err := e.GenerateN("string.alpha", map[string]any{"length": 8}, 3)
if err != nil {
log.Fatal(err)
}
fmt.Println(codes)
}Run it:
go run .person.fullName Nikita Crist
number.int 5
datatype.boolean false
date.recent Wed Dec 31 2025 14:25:35 GMT+0000 (Coordinated Universal Time)
helpers.arrayElements blue,green,red
airline.airline [object Object]
person.nickname error: unknown faker method "person.nickname"
[ljjpBwpF hptxOkAE cFidXYQp]
These are the values Faker.js prints on Node 22 with faker.seed(42) and the same reference date, under TZ=UTC, and the program prints them on every run. The first build compiles the generated Go that contains Faker.js, which took 9 s and peaked at 2.1 GB of memory on an Apple M5 with an empty build cache; later builds come from Go's build cache.
- Text. Every result is a Go
string, converted the way JavaScript'sString()converts it. Numbers and booleans become their text, aDatebecomes itsDate#toStringtext, an array is joined with commas, and an object becomes[object Object]. Seven methods return objects:airline.airline,airline.airplane,airline.airport,finance.currency,location.language,science.chemicalElement, andscience.unit. - Arguments.
nilcalls the method with no argument. Any other value is encoded withencoding/jsonand passed as the method's only argument, so a Go map, a slice, or a struct whose JSON field names match the Faker.js options all work. - Batches.
GenerateN(method, arg, n)returns the samenvalues asncalls toGenerate, in one call into the engine. - Methods. A method is named
module.method, as in the Faker.js API reference; every one of the 262 is listed ingolden/api.json.
Generate and GenerateN return a *fakerjs.Error with one of six classes, except that GenerateN with a negative count returns a plain error. fakerjs.IsClass(err, class) tests the class, and errors.Is matches the sentinel errors (ErrUnknownMethod, ErrDeadline, ErrOutOfMemory, ErrResultTooLarge, ErrArgTooLarge, ErrPoisoned, and ErrClosed). Each message below is real output:
| Class | Call | err.Error() |
|---|---|---|
ClassInvalidMethod |
Generate("person", nil) |
invalid faker method format: "person" (expected format: module.method) |
ClassUnknownMethod |
Generate("person.nickname", nil) |
unknown faker method "person.nickname" |
ClassJSException |
Generate("internet.jwt", nil) |
failed to execute faker.internet.jwt: ReferenceError: TextEncoder is not defined |
ClassInvalidArgument |
Generate("string.alpha", make(chan int)) |
failed to marshal faker argument: json: unsupported type: chan int |
ClassResource |
Generate("string.nanoid", map[string]any{"length": 5}) with WithTimeout(100 * time.Millisecond) |
faker call exceeded its deadline |
ClassEngine |
any call after Close |
engine is closed |
string.nanoid with length: 5 never returns in Faker.js itself, which makes it a convenient deadline test. Each call is bounded by WithTimeout (default 30 s), and its JSON argument by WithMaxArgBytes (default 4 MiB). An engine stays usable after a resource-limit error, but one that hit a memory limit keeps the memory it grew until it is closed (limits).
- Test fixtures.
Engine.Generatewith a fixed seed gives the same values on every run, and the same values on linux/amd64, linux/arm64, darwin/arm64, and windows/amd64, which CI compares. - Seeded, reproducible data.
NewEngine(seed, WithRefDate(t))reproduces the Faker.js sequence for that seed, date methods included. - Seeding databases.
Engine.GenerateNreturns a column of values in one call into the engine. - Load tests.
NewPool(size, seed)runs engines in parallel, each seeded withDeriveSeed(seed, i). Throughput is in performance. - Demos.
NewEngine(0)leaves Faker.js on a random seed, so each new engine gives new values.
Every module and method that Faker.js's en instance exposes is callable: 27 modules and 262 methods, enumerated from Faker.js itself into golden/api.json. The methods are tested with 448 argument variants, each run with 5 seeds and 200 calls per seed. The reference is Faker.js on Node 22.23.3 (V8 12.4) under TZ=UTC, with Node's web-platform globals removed so that Faker.js sees the same bare environment as the engine (Linux VM, conformance results).
| Module | Methods | Cases | Exact | Differences from Faker.js |
|---|---|---|---|---|
airline |
7 | 55 | 55 | airline, airplane, and airport return [object Object] |
animal |
16 | 80 | 80 | |
book |
6 | 30 | 30 | |
color |
11 | 105 | 105 | |
commerce |
9 | 65 | 65 | |
company |
9 | 45 | 45 | |
database |
5 | 25 | 25 | |
datatype |
1 | 15 | 15 | |
date |
11 | 135 | 135 | Date text always names UTC; on Node it names the host's time zone |
finance |
20 | 150 | 145 | amount with autoFormat: true gives $20.55 for $20.550, because there's no Intl (5 cases); currency returns [object Object] |
food |
9 | 45 | 45 | |
git |
5 | 40 | 40 | |
hacker |
6 | 30 | 30 | |
helpers |
18 | 195 | 195 | One argument per call, so the second parameter of arrayElements, mustache, and uniqueArray can't be given; no function arguments, so multiple and maybe can't take a callback |
image |
7 | 65 | 65 | dataUri throws ReferenceError: TextEncoder is not defined for type: 'svg-base64', and with no argument whenever Faker picks that type; stock Node returns a base64 URI |
internet |
21 | 175 | 175 | jwt throws ReferenceError: TextEncoder is not defined; stock Node returns a token |
location |
20 | 160 | 160 | language returns [object Object] |
lorem |
9 | 120 | 120 | |
music |
4 | 20 | 20 | |
number |
7 | 115 | 115 | |
person |
15 | 125 | 125 | |
phone |
2 | 25 | 25 | |
science |
2 | 10 | 10 | chemicalElement and unit return [object Object] |
string |
12 | 165 | 165 | |
system |
12 | 85 | 85 | |
vehicle |
9 | 45 | 45 | |
word |
9 | 115 | 115 | |
| Total | 262 | 2,240 | 2,235 |
The image.dataUri and internet.jwt cases count as exact because the oracle lacks the same globals; they differ from Faker.js on a stock Node process, which provides them.
Locales. en only, from @faker-js/faker/locale/en, one of the 76 locales in the pinned Faker.js package. There is no option to select another.
| go-fakerjs | Faker.js | Oracle |
|---|---|---|
| v0.1.0 | 10.6.0 (en locale) | Node 22.23.3 (V8 12.4), TZ=UTC, web-platform globals removed |
tools.versions is the single source of the Faker.js version, and make check-versions fails if any other statement of it disagrees.
- Seeds. A non-zero
int64seed is passed tofaker.seed(n)after conversion tofloat64with round-to-nearest-even, which is what V8 does withfaker.seed(<int64 literal>). Seeds above 2^53 that round to the samefloat64give the same sequence, as they do in Faker.js. - Seed 0.
faker.seed()is called with no argument, after 32 bytes fromcrypto/randare mixed intoMath.random, so two seed-0 engines give different sequences. - Reference date. Without
WithRefDate,date.recent,date.past,date.future, and the other relative date methods count from the wall clock and change from day to day under a fixed seed. - One sequence per engine. Each engine owns its sequence, and calls on one engine are serialised. Values are reproducible when one logical stream uses each engine.
Closeis final, so a sequence never restarts silently. - Pools. Engine
iofNewPool(size, seed)is seeded withDeriveSeed(seed, i). A poisoned engine is replaced with a fresh one whose sequence starts again, so a pool is reproducible only while no engine is poisoned. - Order. Three 5,000-call sequences that interleave the 22 workload methods with 40 other method and argument pairs match Faker.js exactly, which shows that the engine consumes the PRNG in Faker's order.
The engine differs from Faker.js where QuickJS-NG differs from V8 and Node:
Intl. QuickJS-NG has none, sofinance.amountwithautoFormatdrops trailing zeros. This is the only catalogued divergence, ingolden/known_divergences.yaml; the tests fail on any divergence that isn't listed there.- Web-platform globals. The engine has none of the globals Node adds, such as
TextEncoder, sointernet.jwtand base64image.dataUrithrow. The oracle removes the same globals before it runs Faker.js (golden/gen.mjs), so these cases match the oracle and differ from a stock Node process. - Time zone. The engine always prints
Datetext in UTC and appends(Coordinated Universal Time), so its output is the same under any hostTZ. V8 prints the host's zone, so the two agree only underTZ=UTC. - Latent differences. Of 73 probes run in both engines, 22 differ. Two reach golden data (the
Datetext, which the engine corrects, andtoLocaleStringwith options). The others areArray#sortwith an inconsistent comparator, the locale-formattedDatemethods, the last digits of one trigonometry result, and error message text, where the error classes still match (probes).
Determinism covers each rule in detail.
- Faker.js itself. go-fakerjs runs the published Faker.js bundle and doesn't reimplement it, so equality with Faker.js is tested rather than approximated, and a new Faker.js release is adopted by rebuilding the snapshot, with
make faker-upgrade, instead of porting code. The cost is throughput: QuickJS-NG interprets the JavaScript, where V8 compiles it. - Initialised at build time. Wizer evaluates the Faker.js bundle once while the snapshot is built and saves the resulting memory, so
NewEnginecosts 0.31 ms on an Apple M5, against 23.4 ms for wazero with QuickJS, which evaluates the bundle at start-up, and 4.75 ms for v8go. - Private engines. Each engine runs its own copy of the translated module, about 4.6 MB resident (Linux VM, development build). Calls on one engine are serialised by a mutex, so parallel work needs more engines, which
Poolprovides. - An allowlist of methods. The module lists Faker.js's 262 methods when the snapshot is built and rejects any other name before JavaScript runs, so
constructor,__proto__, andfakerare refused. Arguments are parsed as JSON and never evaluated as code. - Bounded calls. A deadline interrupts a call from inside the module, and a call that exceeds the memory limits fails with an error. A trap or panic poisons the engine, and later calls return
ErrPoisonedinstead of running on unknown state. - Committed generated code.
internal/wasm/snapshot_en.go(6,395,677 bytes) andsnapshot_en.dat(3,465,429 bytes) are in the repository. The snapshot adds 10.2 MB to a stripped binary, and a cold build takes 8.9 s and peaks at about 1.9 GB of RSS (Linux VM, sizes).
go-fakerjs deliberately does not:
- Evaluate caller code. Only allowlisted
module.methodnames run, with JSON arguments. - Give the module a host surface. QuickJS-NG's
stdandosmodules aren't compiled in, so the module has no filesystem, process, network, or timer access. Its only imports are clocks and the stdio calls libc needs (module imports). - Restart a closed engine. Every call after
Closefails withErrClosed, instead of starting a fresh engine whose sequence would begin again from the seed. - Compress the embedded data. Go module zips are already deflated, so gzip would save almost nothing on download and would add a decompression step to the first engine of every process.
- Adopt a major Faker.js release automatically.
make faker-upgraderefuses major versions, which are upgraded by hand.
It also doesn't select a locale other than en, return typed Go values, take more than one argument or a function argument per call, or provide Intl.
How it works describes the build pipeline and a call from Go into the module.
Apple M5, darwin/arm64, medians of 10 runs, 20-column rows with one call per value. The v8go column builds a script per call; performance also has v8go with precompiled scripts.
| go-fakerjs | v8go | wazero with QuickJS | |
|---|---|---|---|
| Engine start-up, first value included | 0.31 ms | 4.75 ms | 23.4 ms |
| Rows/s, 1 engine | 2,100 | 25,339 | 677 |
| Rows/s, 10 engines | 9,652 | 111,128 | 727 |
Per call, go-fakerjs is 1.3× (number.int) to 55× (lorem.sentence) slower than v8go. Performance has the figures per method and their sources.
How to use Faker.js in Go (golang)? Add go-fakerjs with go get github.com/iamramtin/go-fakerjs@latest, create an engine with fakerjs.NewEngine(seed), and call any Faker.js method by name, as in e.Generate("person.fullName", nil). The quick start is a complete program with its output.
Is go-fakerjs a Go port of Faker.js? No. It runs the published Faker.js bundle itself, in the QuickJS-NG interpreter, compiled to WebAssembly and translated into Go source. Nothing is reimplemented, so the values are Faker.js's own, and a new Faker.js release is adopted by rebuilding the snapshot rather than by porting code.
Does go-fakerjs give the same values as Faker.js for the same seed? Yes, on the tested surface: 2,235 of 2,240 test cases across all 262 methods match Faker.js byte for byte under TZ=UTC. The other 5 are finance.amount with autoFormat, which needs Intl. internet.jwt and base64 image.dataUri throw, because they need TextEncoder, which Node provides and the interpreter doesn't (determinism and compatibility).
Does it need cgo, Node, or a Wasm runtime? No. It builds with CGO_ENABLED=0 and imports only the standard library. Cross-compiled test binaries for linux/amd64, linux/arm64, and windows/amd64 link no dynamic libraries, and CI checks that the engine's output over the whole golden set is identical on linux/amd64, linux/arm64, darwin/arm64, and windows/amd64 (portability).
How fast is it? On an Apple M5, an engine starts in 0.31 ms, against 4.75 ms for v8go, and produces about 2,100 20-column rows per second, against 25,339 for v8go. Per call it is 1.3× to 55× slower than v8go, because QuickJS-NG interprets the JavaScript that V8 compiles (performance).
How does it compare with gofakeit? gofakeit is written in Go with its own generators and data, so its values are its own. go-fakerjs runs Faker.js, so its values are Faker.js's, which matters when Go and JavaScript code must produce the same fixtures from one seed.
- How it works: the build pipeline, a call from Go into the module, and how a Faker.js release is adopted.
- Determinism: seeds, reference dates, pools, and every difference from Faker.js.
- Performance: start-up, per-call, and parallel figures against v8go and wazero.
- Findings: method, results, analysis, threats to validity, and replication.
- Results: the raw output behind every published figure, by date and machine.
- Contributing: toolchain, regeneration, tests, and Faker.js upgrades.
- Discussions: questions, ideas, and feedback. Bugs go in issues.
- Security: threat model and how to report a vulnerability.
- Changelog: release notes.
- C harness and Wasm build: what the module contains and how it is built.
- Third-party notices: bundled components, tools, and their licences.
Claude models were used for variation testing and measurements. Findings records which models and what each did.
Faker.js (MIT), QuickJS-NG (MIT; QuickJS by Fabrice Bellard and Charlie Gordon), wasm2go, Wizer, Binaryen, wasi-sdk, and esbuild. Versions and licences are listed in full.
Released under the MIT licence. The generated snapshot also contains code under the licences listed in third-party notices.