# Changelog

Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). 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](README.md) documents each part.

### Added

- The CLI, `fejkdata`, renders exactly the template on its stdin and adds nothing:
  `echo '{/sv_SE.person} hihi' | fejkdata` prints `Sara Eriksson hihi`. `--seed` makes a
  run reproducible, `-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. `New` loads the
  modules `WithDataFS` names and the folders `WithDataPath` names, and fails, naming
  `WithDataFS`, where neither is given; `WithSeed` makes its draws reproducible. `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. 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](README.md#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 or the file's folder
  (`{/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](README.md#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](README.md#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](README.md#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`](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 the rest ship, each with a quarter of its streets,
    at least ten.