@venn-lang/data 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# @venn-lang/data
+
+> The `data` namespace: 96 deterministic faker verbs, plus picking, shuffling and parsing.
+
+Test data that changes between runs makes a failure impossible to reproduce. Every value this
+package draws comes from one seeded PRNG (mulberry32, seed 1) held at module level, so the same
+flow replays the same person, the same card number, the same CPF. The plugin declares no
+capability and rides no port: `data` is pure computation, no network and no clock.
+
+## Install
+
+The package is part of the stdlib the `venn` CLI loads, so nothing to install. Reach it from a
+flow with a `use` line:
+
+```ruby
+use "venn/data"
+```
+
+## Usage
+
+```ruby
+module demo.signup
+
+use "venn/assert"
+use "venn/data"
+
+flow "A generated Brazilian signup" {
+  const name = data.faker.name
+  const email = data.faker.email
+  const cpf = data.faker.br.cpf
+  const card = data.faker.creditCard
+
+  step "the generated person is plausible" {
+    expect name contains " "
+    expect email contains "@"
+    expect cpf contains "-"
+    expect card contains " "
+  }
+
+  step "and the rest of the namespace is there too" {
+    const plan = data.oneOf "free" "pro"
+    const roll = data.range 1 10
+    const rows = data.csv "name,plan\nada,pro\nlinus,free"
+
+    expect roll >= 1
+    expect rows.len == 2
+  }
+}
+```
+
+## Verbs
+
+Five verbs sit directly on the namespace:
+
+| Verb | Gives back | Notes |
+| --- | --- | --- |
+| `data.oneOf a b c…` | `dynamic` | One of the positional arguments. |
+| `data.range min max` | `number` | An integer in the inclusive range. |
+| `data.shuffle values` | `list<dynamic>` | A permutation. The input array is left alone. |
+| `data.csv text` | `list<data.Row>` | Parses inline CSV; the first line names the columns. |
+| `data.json text` | `dynamic` | `JSON.parse`, with the shape left to the caller. |
+
+The other 96 are `data.faker.*`, grouped by what a form asks for:
+
+| Family | Verbs |
+| --- | --- |
+| Person | `firstName` `lastName` `name` `fullName` `prefix` `suffix` `gender` `jobTitle` `age` `birthDate` `phone` |
+| Internet | `email` `username` `password` `domain` `url` `ipv4` `ipv6` `mac` `port` `userAgent` `slug` `httpMethod` `httpStatus` `mimeType` |
+| Address | `street` `streetAddress` `address` `buildingNumber` `city` `country` `countryCode` `zip` `latitude` `longitude` `timezone` |
+| Company | `company` `department` `catchPhrase` `buzzword` |
+| Commerce | `product` `productName` `sku` `barcode` `category` `material` `color` `hexColor` `price` |
+| Finance | `creditCard` `cardType` `cvv` `expiryDate` `iban` `bic` `accountNumber` `currencyCode` `currencySymbol` `currencyName` `amount` |
+| Date and time | `date` `dateTime` `pastDate` `futureDate` `time` `timestamp` `weekday` `month` `year` |
+| Text | `word` `words` `sentence` `sentences` `paragraph` `paragraphs` `title` |
+| Identifiers | `uuid` `nanoid` `objectId` `hex` `token` `alphanumeric` `digits` `int` `float` `boolean` |
+| Brazil | `br.cpf` `br.cnpj` `br.cep` `br.phone` `br.plate` `br.street` `br.address` `br.city` `br.state` `br.stateCode` |
+
+Ten of them read positional bounds; the rest take nothing.
+
+```ruby
+const pin      = data.faker.digits 4        # four decimal digits
+const quantity = data.faker.int 1 6         # inclusive on both ends
+const blurb    = data.faker.words 5
+const born     = data.faker.year 1980 2005
+```
+
+The full list of verbs that read arguments: `nanoid(length)`, `hex(length)`,
+`alphanumeric(length)`, `digits(length)`, `int(min, max)`, `float(min, max)`, `words(count)`,
+`sentences(count)`, `paragraphs(count)`, `year(from, to)`. All arguments are optional and every
+one has a default.
+
+### Check digits are real
+
+A value a form rejects before it reaches the server is useless in a test, so the generators that
+carry a checksum compute it: `creditCard` passes Luhn, `barcode` passes the EAN-13 check, `iban`
+passes mod-97, and `br.cpf` and `br.cnpj` carry the digits a Brazilian form validates.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `dataPlugin` (also the default export) | The `PluginDefinition` for the `data` namespace. |
+| `dataActions` | The `ActionDefinition[]` behind it, faker verbs included. |
+| `allFakerSpecs`, `FakerSpec` | The catalogue as data: `name`, `doc`, a `TypeSpec` result, optional `args`, and `make(rng, args)`. |
+| `rng`, `resetRng()` | The shared PRNG and the reset that rewinds it to the seed. |
+| `mulberry32(seed)`, `Rng` | The generator itself, for an independent stream. |
+| `shuffleWith(items, rng)` | Fisher-Yates against a given PRNG. Returns a new array. |
+| `parseCsv(content)`, `CsvRow` | The splitter behind `data.csv`. |
+| `uuid`, `email`, `firstName`, `lastName`, `fullName` | Single generators, each taking an `Rng`. |
+| `cpfDigits`, `cnpjDigits`, `luhnDigit`, `eanDigit`, `ibanCheck` | The check-digit functions on their own. |
+| `ANCHOR` | The fixed instant the date verbs are drawn around, `2025-01-01T00:00:00Z`. |
+
+The plugin publishes one named type, `data.Row`: a map of string to string, which is what
+`data.csv` gives back per record.
+
+## Determinism
+
+`rng` is a module-level mulberry32 seeded with `1`. Draws advance one shared stream, so the
+sequence of calls a flow makes is what determines the values, not the wall clock. `resetRng()`
+rewinds it, which is how the tests here assert that a whole catalogue replays identically:
+
+```ts
+import { allFakerSpecs, resetRng, rng } from "@venn-lang/data";
+
+resetRng();
+const first = allFakerSpecs.map((spec) => spec.make(rng, []));
+resetRng();
+const again = allFakerSpecs.map((spec) => spec.make(rng, []));
+// `again` equals `first`: the same 96 values, in the same order
+```
+
+Dates are drawn around `ANCHOR` rather than `Date.now()`, for the same reason.
+
+## Limits
+
+`parseCsv` is a minimal splitter: it reads inline content only (no file paths yet), splits on
+commas and trims cells, and does not handle quoted commas.
+
+## See also
+
+- [`@venn-lang/crypto`](../std-crypto) for hashing and signing the values generated here.
+- [`@venn-lang/mock`](../std-mock) for freezing the clock and flipping flags.
+- [`@venn-lang/sdk`](../sdk) for `defineAction` and `definePlugin`.

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+import { ActionDefinition, ArgSpec, PluginDefinition } from "@venn-lang/sdk";
+import { TypeSpec } from "@venn-lang/types";
+//#region src/actions/index.d.ts
+/** Every verb in the `data` namespace. Adding one is a single line here. */
+declare const dataActions: ActionDefinition[];
+//#endregion
+//#region src/csv/csv.types.d.ts
+/** One parsed CSV record: header name → cell value, both strings. */
+type CsvRow = Record<string, string>;
+//#endregion
+//#region src/csv/parse-csv.d.ts
+/**
+ * Parse a CSV string into row objects. The first line supplies the headers.
+ *
+ * A minimal splitter: it takes inline content only (never a path) and does not
+ * understand quoting, so a quoted cell containing a comma splits in two.
+ *
+ * @param content The CSV text. Blank lines are skipped.
+ * @returns One object per data line, keyed by header. Empty when there is no header line.
+ */
+declare function parseCsv(content: string): CsvRow[];
+//#endregion
+//#region src/rng/rng.types.d.ts
+/** A deterministic pseudo-random generator: each call yields the next float in [0, 1). */
+type Rng = () => number;
+//#endregion
+//#region src/rng/mulberry32.d.ts
+/**
+ * Mulberry32: a tiny, fast, fully deterministic PRNG.
+ *
+ * @param seed Any number. It is coerced to a uint32, so the same seed always
+ * yields the same stream.
+ * @returns A generator producing the next float in [0, 1) on each call.
+ */
+declare function mulberry32(seed: number): Rng;
+//#endregion
+//#region src/rng/shared-rng.d.ts
+/** The module-level deterministic PRNG shared by every generator in this package. */
+declare const rng: Rng;
+/** Reset the shared PRNG to its seed so the same stream can be drawn again. Used by tests. */
+declare function resetRng(): void;
+//#endregion
+//#region src/rng/shuffle.d.ts
+/**
+ * Fisher-Yates shuffle driven by the given PRNG.
+ *
+ * @returns A new array holding the same elements in a new order. `items` is untouched.
+ */
+declare function shuffleWith(items: readonly unknown[], rng: Rng): unknown[];
+//#endregion
+//#region src/faker/faker.types.d.ts
+/**
+ * One `data.faker.*` verb: what it is called, what it means, and how to draw a
+ * value. A spec is plain data, so the action wiring reads the list as it stands
+ * and needs no edit when a category grows.
+ */
+interface FakerSpec {
+  /** The verb, without the namespace: `email`, `br.cpf`. */
+  name: string;
+  /** One line, in the user's domain. Shown on hover and in completion. */
+  doc: string;
+  /** The type it draws. A `TypeSpec`, not a name, so the checker can act on it. */
+  result: TypeSpec;
+  /**
+   * The positional arguments `make` reads, in order. Most verbs read none and
+   * leave this out. The action wiring turns it into the signature the checker sees.
+   */
+  args?: readonly ArgSpec[];
+  /** Draw a value. `args` carries the call's positional arguments, if any. */
+  make(rng: Rng, args: readonly unknown[]): unknown;
+}
+//#endregion
+//#region src/faker/all-specs.d.ts
+/** Every `data.faker.*` verb. Adding a whole category is one line here. */
+declare const allFakerSpecs: readonly FakerSpec[];
+//#endregion
+//#region src/faker/brazil-documents.d.ts
+/**
+ * The two CPF check digits.
+ *
+ * @param base The first nine digits, unformatted.
+ * @returns Two digits to append.
+ */
+declare function cpfDigits(base: string): string;
+/**
+ * The two CNPJ check digits.
+ *
+ * @param base The first twelve digits, unformatted.
+ * @returns Two digits to append.
+ */
+declare function cnpjDigits(base: string): string;
+//#endregion
+//#region src/faker/check-digits.d.ts
+/**
+ * The Luhn check digit for a card number.
+ *
+ * @param base The digits preceding the check digit.
+ * @returns One digit. Appending it makes `base` pass the Luhn test.
+ */
+declare function luhnDigit(base: string): string;
+/**
+ * The EAN-13 check digit for the leading 12 digits of a barcode.
+ *
+ * @param base Exactly 12 digits.
+ * @returns The thirteenth digit.
+ */
+declare function eanDigit(base: string): string;
+/**
+ * The two IBAN check digits: mod-97 over the rearranged, letter-expanded account.
+ *
+ * @param country The two-letter country code, upper case.
+ * @param account The account part, without check digits.
+ * @returns Two digits, zero-padded, to be inserted after the country code.
+ */
+declare function ibanCheck(country: string, account: string): string;
+//#endregion
+//#region src/faker/datetime.d.ts
+/**
+ * The instant every generated date is measured from.
+ *
+ * Dates hang off a fixed anchor rather than the wall clock: `Date.now()` would
+ * give a different answer on every run and break the seeded replay guarantee.
+ */
+declare const ANCHOR: number;
+//#endregion
+//#region src/faker/ids.d.ts
+/** An RFC 4122 v4 UUID. The version and variant bits are stamped, not drawn. */
+declare function uuid(rng: Rng): string;
+//#endregion
+//#region src/faker/internet.d.ts
+/** An email on a reserved domain, e.g. `"grace.hopper@example.test"`. It reaches nobody. */
+declare function email(rng: Rng): string;
+//#endregion
+//#region src/faker/person.d.ts
+/** A given name, e.g. `"Grace"`. */
+declare function firstName(rng: Rng): string;
+/** A family name, e.g. `"Hopper"`. */
+declare function lastName(rng: Rng): string;
+/** A full name, e.g. `"Grace Hopper"`. */
+declare function fullName(rng: Rng): string;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `data` plugin: pure, deterministic test-data generators.
+ *
+ * Every verb draws from a seeded module-level PRNG, so the same script replays the
+ * same values. Nothing here does I/O, so there is no capability and no port to bind.
+ */
+declare const dataPlugin: PluginDefinition;
+//#endregion
+export { ANCHOR, type CsvRow, type FakerSpec, type Rng, allFakerSpecs, cnpjDigits, cpfDigits, dataActions, dataPlugin, dataPlugin as default, eanDigit, email, firstName, fullName, ibanCheck, lastName, luhnDigit, mulberry32, parseCsv, resetRng, rng, shuffleWith, uuid };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/actions/index.ts","../src/csv/csv.types.ts","../src/csv/parse-csv.ts","../src/rng/rng.types.ts","../src/rng/mulberry32.ts","../src/rng/shared-rng.ts","../src/rng/shuffle.ts","../src/faker/faker.types.ts","../src/faker/all-specs.ts","../src/faker/brazil-documents.ts","../src/faker/check-digits.ts","../src/faker/datetime.ts","../src/faker/ids.ts","../src/faker/internet.ts","../src/faker/person.ts","../src/plugin.ts"],"mappings":";;;;cAMa,aAAa;;;;KCLd,SAAS;;;;;;;;;;;;iBCUL,SAAS,kBAAkB;;;;KCV/B;;;;;;;;;;iBCQI,WAAW,eAAe;;;;cCA7B,KAAK;;iBAGF;;;;;;;;iBCLA,YAAY,2BAA2B,KAAK;;;;;;;;UCE3C;;EAEf;;EAEA;;EAEA,QAAQ;;;;;EAKR,gBAAgB;;EAEhB,KAAK,KAAK,KAAK;;;;;cCTJ,wBAAwB;;;;;;;;;iBCHrB,UAAU;;;;;;;iBAsBV,WAAW;;;;;;;;;iBCpBX,UAAU;;;;;;;iBAiBV,SAAS;;;;;;;;iBAeT,UAAU,iBAAiB;;;;;;;;;cChC9B;;;;iBCLG,KAAK,KAAK;;;;iBCWV,MAAM,KAAK;;;;iBCJX,UAAU,KAAK;;iBAKf,SAAS,KAAK;;iBAKd,SAAS,KAAK;;;;;;;;;cCdjB,YAAY"}