lacspace-fake 0.1.0 → 0.2.0

package/README.md

@@ -11,6 +11,17 @@ every machine), **Nepal-aware** with `--locale ne`, and it emits ready-to-run
 npx lacspace-fake --fields "id:autoincrement,name:fullName,email:email,age:int(18..65)" -n 5
 ```
 
+## New in 0.2.0
+
+- **Relations / linked tables** — `--relations schema.json` generates several entities where one references another's ids (`ref(users.id)`), with guaranteed referential integrity (every foreign key exists).
+- **Template fields** — `full:template({{firstName}} {{lastName}})` interpolates earlier fields and inline generators.
+- **`unique(...)` constraint** — `email:unique(email)` guarantees no duplicate values across rows.
+- **More locales** — added `es` (Spanish) and `fr` (French) alongside `en` and `ne`.
+- **`--ddl`** — for `-f sql`, also emit a `CREATE TABLE` with column types inferred from the data.
+- **~15 new generators** — `ulid`, `hexColor`/`rgb`/`hsl`, `semver`, `mimeType`, `fileExt`/`fileName`/`filePath`, `timezone`, `currencyCode`, `creditCardMasked`/`cardBrand`, `iban`, `bic`.
+
+All additive and backward compatible — existing schemas, flags and output are unchanged.
+
 ## Why it exists
 
 - **Free & keyless.** No API key, no account, no network calls, no telemetry — runs fully offline.
@@ -32,11 +43,21 @@ npx lacspace-fake --fields "id:autoincrement,name:fullName,role:oneOf(admin|user
 # From a JSON schema, out to a CSV file
 npx lacspace-fake --schema users.json -n 50 -f csv -o users.csv
 
-# Nepal locale
+# Nepal / Spanish / French locale
 npx lacspace-fake --fields "name:fullName,phone:phone,district:city" --locale ne -n 10
+npx lacspace-fake --fields "name:fullName,phone:phone" --locale es -n 5
+
+# Template + unique fields
+npx lacspace-fake --fields "id:unique(uuid),first:firstName,handle:template({{first}}-{{int(1..99)}})" -n 5
 
-# Just five emails
-npx lacspace-fake email -n 5 --seed 42
+# SQL with CREATE TABLE DDL
+npx lacspace-fake --fields "id:autoincrement,name:fullName,score:float(0..100)" -f sql --table users --ddl
+
+# Linked tables with foreign keys
+npx lacspace-fake --relations shop.json -f sql --ddl
+
+# Just five ULIDs
+npx lacspace-fake ulid -n 5 --seed 42
 
 # Discover every generator
 npx lacspace-fake list
@@ -109,11 +130,14 @@ key:generator(args)      age:int(18..65)   role:oneOf(admin|user)
 
 - Numeric ranges use `..` — `int(18..65)`, `price(10..999)`, `float(0..1)`
 - Option lists use `|` — `oneOf(admin|user|guest)`
-- Weighted picks use `value:weight` — `weighted(admin:1|user:9)`
+- Weighted picks use `value:weight` — `weighted(admin:1|user:9)` (a weighted enum)
 - Date windows use `..` — `between(2020-01-01..2024-12-31)`
+- **Unique** wraps any generator — `email:unique(email)`, `id:unique(int(1..1000000))` — no two rows repeat a value
+- **Templates** interpolate `{{...}}` — `full:template({{firstName}} {{lastName}})`, `email:template({{username}}@{{domain}})`
 
 Fields evaluate in order, so a later field can derive from an earlier one:
 `firstName:firstName,lastName:lastName,email:email` yields emails built from each row's name.
+Inside a `template(...)`, a `{{token}}` that matches an earlier field reuses its value; otherwise it is evaluated as a generator.
 
 ## Generators
 
@@ -123,13 +147,37 @@ street · city · state · country · countryCode · zip · address · latitude
 latlng · company · catchphrase · jobTitle · department · productName · price · sku ·
 currency · category · color · word · words · sentence · paragraph · lorem · past ·
 future · recent · soon · between · timestamp · date · time · int · float · bool ·
-oneOf · weighted · digit · autoincrement · nanoid · objectId · pan · vat`
+oneOf · weighted · digit · autoincrement · nanoid · objectId · pan · vat ·
+ulid · hexColor · rgb · hsl · semver · mimeType · fileExt · fileName · filePath ·
+timezone · currencyCode · creditCardMasked · cardBrand · iban · bic`
 
 Run `lacspace-fake list` for a live sample of each.
 
-> **Foreign keys / relations:** model an FK column with an `int` range that points at
-> your parent table's id space, e.g. `user_id:int(1..100)`. Deterministic seeds keep the
-> references stable across regenerations.
+## Relations (linked tables with foreign keys)
+
+A relations schema maps each entity to `{ count, fields }`. A field whose spec is
+`ref(<entity>.<field>)` is a **foreign key**, drawn from the already-generated column of
+an earlier entity — so every FK is guaranteed to exist. The whole dataset is drawn from
+one seed, so it's byte-reproducible.
+
+```json
+{
+  "users":  { "count": 10, "fields": { "id": "unique(int(1..99999))", "name": "fullName" } },
+  "orders": { "count": 30, "fields": { "id": "autoincrement", "userId": "ref(users.id)", "total": "price(5..500)" } }
+}
+```
+
+```bash
+$ npx lacspace-fake --relations shop.json -f sql --ddl --seed 42
+CREATE TABLE "users" ( "id" INTEGER NOT NULL, "name" TEXT NOT NULL );
+INSERT INTO "users" ("id", "name") VALUES ... ;
+CREATE TABLE "orders" ( "id" INTEGER NOT NULL, "userId" INTEGER NOT NULL, "total" REAL NOT NULL );
+INSERT INTO "orders" ("id", "userId", "total") VALUES ... ;   -- every userId exists in users
+```
+
+Entities must be declared parent-first (a `ref(...)` can only point at an entity above it).
+`json` output emits one object of arrays; `sql` emits a block per table; `csv`/`ndjson`
+emit one `# <table>` section per entity.
 
 ## CLI reference
 
@@ -140,10 +188,12 @@ Run `lacspace-fake list` for a live sample of each.
 | `-n, --count <n>` | Number of rows/values (default 10) |
 | `-f, --format <fmt>` | `json` (default), `ndjson`, `csv`, `sql` |
 | `-t, --table <name>` | Table name for `-f sql` |
+| `--ddl` | For `-f sql`: also emit `CREATE TABLE` with inferred column types |
 | `--fields <spec>` | Inline schema string |
 | `--schema <file>` | JSON schema file (`-` for stdin) |
+| `--relations <file>` | JSON relations schema → linked entities with foreign keys (`-` for stdin) |
 | `-s, --seed <str>` | Seed for reproducible output (number or any string) |
-| `-l, --locale <loc>` | `en` (default) or `ne` (Nepal) |
+| `-l, --locale <loc>` | `en` (default), `ne` (Nepal), `es` (Spanish) or `fr` (French) |
 | `--pretty` | Pretty-print JSON |
 | `-o, --out <file>` | Write to a file instead of stdout |
 | `-h, --help` / `-v, --version` | Help / version |
@@ -164,15 +214,21 @@ formatRows(rows, { format: "sql", table: "users" });
 
 | Export | Signature |
 |--------|-----------|
-| `parseFields(spec)` | `(input: string) => Field[]` — compile an inline field string |
+| `parseFields(spec)` | `(input: string) => Field[]` — compile an inline field string (`unique(...)`/`template(...)` aware) |
 | `parseJsonSchema(obj)` | `(schema: unknown) => Field[]` — compile a JSON schema object |
-| `generateRows(fields, opts)` | `(Field[], { count?, seed?, locale? }) => Record<string, unknown>[]` |
+| `generateRows(fields, opts)` | `(Field[], { count?, seed?, locale? }) => Record<string, unknown>[]` — enforces `unique` fields |
 | `generateValues(spec, opts)` | `(specStr: string, { count?, seed?, locale? }) => unknown[]` |
-| `formatRows(rows, opts)` | `(rows, { format, pretty?, table? }) => string` |
+| `parseRelations(obj)` | `(schema: unknown) => CompiledEntity[]` — compile a relations schema |
+| `generateDataset(entities, opts)` | `(CompiledEntity[], opts) => Record<string, Row[]>` — linked data with FKs |
+| `generateRelations(obj, opts)` | parse + generate a linked dataset in one call |
+| `formatRows(rows, opts)` | `(rows, { format, pretty?, table?, ddl? }) => string` |
+| `formatDataset(dataset, opts)` | format a `{ entity: rows }` dataset (JSON object / per-table SQL / sections) |
 | `formatValues(values, col, opts)` | scalar-value formatter |
-| `toCsv(rows)` / `toSql(rows, table)` | direct formatters |
+| `toCsv(rows)` / `toSql(rows, table, { ddl? })` | direct formatters |
+| `toCreateTable(rows, table)` / `inferSqlType(values)` | DDL builder + column-type inference |
+| `compileTemplate(body, compile)` | build a template-field resolver |
 | `sqlValue(v)` / `sqlIdent(name)` | SQL escaping primitives |
-| `generators` / `callGen(name, ctx, args)` | the generator registry |
+| `generators` / `callGen(name, ctx, args)` | the generator registry (built-ins + 0.2.0 extras) |
 | `RNG` | the seeded mulberry32 PRNG (`int`, `float`, `bool`, `pick`, `weighted`, `uuid`, …) |
 | `slugify(str)` | accent/punctuation-safe URL slug |
 
@@ -180,9 +236,9 @@ Types (`Field`, `Spec`, `Format`, `FormatOptions`, `GenContext`, `Locale`, …)
 
 ## Limitations
 
-- Data is **plausible, not real** — it's for tests and demos, never production identities.
-- Locales are `en` and `ne` only; `en` is generic English/US-ish, not per-country.
-- Relations are best-effort via `int()` id ranges — there is no cross-table referential engine.
+- Data is **plausible, not real** — it's for tests and demos, never production identities. `creditCardMasked`/`iban`/`bic` are structurally-shaped placeholders, never valid instruments.
+- Locales are `en`, `ne`, `es` and `fr`; `en` is generic English/US-ish, not per-country.
+- Relations resolve foreign keys from the parent's generated column (guaranteed to exist); a `ref(...)` must point at an entity declared earlier in the schema.
 - Determinism holds for a given package version; generator internals may evolve across minor versions.
 - Time-based generators (`past`, `future`, `recent`) are anchored to the current clock, so their absolute instants shift day to day (still deterministic within a run given a seed).