fejkdata/CHANGELOG.md

Changelog

Format: Keep a Changelog. A release's Breaking section comes first and names each rejected spelling with its replacement, and each removed path, column or flag.

[Unreleased]

The first release: a Go library and a CLI that render locale-aware fake data from JSON templates, and the data they ship with. The README documents each part. Install the CLI with go install github.com/larvit/fejkdata/cmd/fejkdata@v0.1.0, or the library with go get github.com/larvit/fejkdata@v0.1.0. Before 1.0.0 a minor may break, and any release may change what a seed draws, so pin one exact version (Versioning).

Added

• The CLI, fejkdata, renders exactly the template on its stdin and adds nothing: echo '{/sv_SE.person} hihi' | fejkdata prints e.g. Sara Eriksson hihi. --seed makes a run reproducible for one version and data, -n repeats it, --list prints every path, and --data-path layers a directory of your own data over the shipped set, or alone with --no-shipped-data. --format json|ndjson|csv|sql writes a record's columns, one record per row. It exits 0 on success, 1 on a runtime error such as data that fails to load, and 2 on misuse.
• The library, github.com/larvit/fejkdata, for Go 1.22 or later on a 64-bit target. New loads the modules WithDataFS names and the folders WithDataPath names, and fails, naming WithDataFS, where neither is given; WithSeed makes its draws reproducible for one version and data. Fake renders a path, FakeTemplate and NewTemplate a template, FakeRecord, FakeRecordTemplate and NewRecordTemplate a record, whose columns JSON, CSVHeader, CSVLine and SQLInsert write as the CLI does, and FakeStruct fills a struct's fake:"…" tagged fields. List gives every path Fake renders, and IsTemplate tells an inline template from a path. Data that fails to load gives an error matching ErrLoad, and a record with no fields one matching ErrNoColumns.
• Package github.com/larvit/fejkdata/cli is the fejkdata command: cli.Main(modules...) runs it over the modules given, so cli.Main(append(data.Modules(), mydata)...) builds a CLI carrying your own data. That CLI names itself by the file it runs from, and its --version prints its own module's version before fejkdata's.
• The template language (Data format). A node is a string, a choice, a template, a table, a number or a boolean. A format string's {…} tokens read sibling fields, references from the data root, the file's folder or the folder above ({/sv_SE.person.last}, {.x}, {..x}), builtins and names. Every {…} draws afresh, and a name is the one way to keep a pick: {/sv_SE.person as p}{p.first} {p.last} is one person. The builtins draw check digits (luhn, mod11, ean), samples (digits, int, float, uuid, ulid, iban, date, time and more), a counter (seq), arithmetic (calc) and transforms (lowercase, uppercase, ascii). New refuses data that breaks the grammar, could mean two things or cannot render a valid value.
• Records (Records): a template seen as columns. A column is a string unless it declares a datatype, integer, number or boolean, and a null item draws it as null.
• Tables (Table): a category naming a rows TSV beside it, with the options key, name, weight and parent. A path selects a row by key or name, misc.territory[SE], descends to a linked table, geo.SE.locality[Lund].street, and steps up to the parent row, {/misc.timezone[Europe/Oslo]..territory.name}.
• Data sources (Data): a directory is a namespace, and each JSON file in it a category. A .fejkdata.json manifest at a source's root may carry a namespace, the dot path the source mounts under, and an index, with which each category loads on the first call reaching it.
• The shipped data, in Go packages that each export FS and Modules(): github.com/larvit/fejkdata/data/en_US (package enus), …/sv_SE (svse), …/misc, …/geo/SE (geose) and …/geo/US (geous). data.Modules(), from github.com/larvit/fejkdata/data, lists every one, and the CLI carries them all. DATA-LICENSES.md names each source.
  • sv_SE and en_US: an address, a person and more per locale. sex, first-name and last-name are tables weighted by bearers, from SCB, the SSA and the Census Bureau. A person's first name and sex agree, and so does an en_US person's title; person.prefix is null where a person has no title. sv_SE.personnummer and sv_SE.samordningsnummer draw Skatteverket's test series. en_US.ssn and en_US.itin draw the ranges the SSA and the IRS assign, with the columns area, group and serial, and en_US.phone draws an exchange NANPA may assign.
  • misc: IANA's registries of HTTP methods, protocols, ports and root-zone TLDs, the HTTP status codes, ISO 3166-1 territories, ISO 4217 currencies with their CLDR symbols, ISO 639 languages, the syslog severities, mime-db's media types, tzdb's zones weighted by the people living in each, user agents and cars, all as tables; and coordinates, credit card numbers, RFC 3339 instants, emoji, MAC addresses, ObjectIds and UUIDs.
  • geo.SE and geo.US: five linked tables per country, region, municipality, locality, postal-code and street, weighted by population and address counts and built from SCB, GeoNames, Trafikverket NVDB, the US Census Bureau and Wikidata, and an address record drawing a street and postal code inside one locality, which sv_SE.address and en_US.address print. Every Swedish postort the import can place ships with all its streets. Of the US incorporated places that hold most of some postal code's land, every state capital but Honolulu, every place of 100,000 or more and a population-weighted tenth of them ship, each with a quarter of its streets, at least ten.