lacspace-fake 0.1.0

package/dist/lib.d.cts

@@ -0,0 +1,160 @@
+/**
+ * Seeded pseudo-random number generator (mulberry32).
+ *
+ * Deterministic: the same seed always yields the same sequence, which is what
+ * makes fake-data fixtures reproducible across runs and machines. Every
+ * generator in this package draws exclusively from an `RNG` instance so that a
+ * fixed `--seed` produces byte-identical output.
+ */
+/** Hash an arbitrary string to a 32-bit unsigned integer (for string seeds). */
+declare function hashSeed(input: string): number;
+/** Coerce a user-supplied seed (number, numeric string, or arbitrary string). */
+declare function normalizeSeed(seed: number | string): number;
+/** A seeded random source with typed convenience helpers. */
+declare class RNG {
+    private readonly _next;
+    readonly seed: number;
+    constructor(seed: number | string);
+    /** Uniform float in [0, 1). */
+    next(): number;
+    /** Inclusive integer in [min, max]. */
+    int(min: number, max: number): number;
+    /** Float in [min, max) rounded to `decimals` places (default 2). */
+    float(min: number, max: number, decimals?: number): number;
+    /** `true` with probability `prob` (default 0.5). */
+    bool(prob?: number): boolean;
+    /** Pick one element uniformly. Throws on an empty array. */
+    pick<T>(items: readonly T[]): T;
+    /** Pick `n` distinct elements (Fisher–Yates partial shuffle). */
+    sample<T>(items: readonly T[], n: number): T[];
+    /** Return a shuffled copy. */
+    shuffle<T>(items: readonly T[]): T[];
+    /** Weighted pick. Entries are `[value, weight]`; weights need not sum to 1. */
+    weighted<T>(entries: readonly (readonly [T, number])[]): T;
+    /** A string of `len` random hex characters. */
+    hex(len: number): string;
+    /** A string of `len` random decimal digits. */
+    digits(len: number): string;
+    /** Pick `len` characters from an alphabet. */
+    chars(alphabet: string, len: number): string;
+    /** An RFC-4122 version-4 UUID, drawn deterministically from this RNG. */
+    uuid(): string;
+}
+
+/**
+ * Locale data tables. `en` (default) is generic English/US-ish; `ne` is
+ * Nepal-aware (romanized Nepali names, districts, provinces, NPR, +977 phones).
+ * Everything here is a plain constant so generators stay pure functions of the
+ * RNG plus a locale table.
+ */
+type Locale = "en" | "ne";
+interface LocaleData {
+    firstNamesMale: string[];
+    firstNamesFemale: string[];
+    lastNames: string[];
+    cities: string[];
+    states: string[];
+    country: string;
+    countryCode: string;
+    streetNames: string[];
+    streetSuffixes: string[];
+    /** How to build a postal/ZIP code for this locale. */
+    zip: (r: {
+        digits: (n: number) => string;
+    }) => string;
+    currency: {
+        code: string;
+        symbol: string;
+    };
+    /** E.164 phone (with +country) and a local-format phone. */
+    phone: (r: {
+        digits: (n: number) => string;
+        pick: <T>(a: readonly T[]) => T;
+    }) => {
+        e164: string;
+        local: string;
+    };
+}
+declare const LOCALES: Record<Locale, LocaleData>;
+declare function isLocale(v: string): v is Locale;
+
+/**
+ * The generator library. Each generator is a pure function of a `GenContext`
+ * (an RNG + locale + row index + the partially-built row) and an optional list
+ * of positional args. Generators are looked up by name from the `generators`
+ * registry, which powers the CLI, the schema engine and the `list` command.
+ */
+
+interface GenContext {
+    rng: RNG;
+    locale: Locale;
+    /** Zero-based row index — used by `autoincrement`. */
+    index: number;
+    /** The row built so far; lets `email` derive from an earlier `firstName`. */
+    row: Record<string, unknown>;
+}
+type GenArg = string | number;
+type Generator = (ctx: GenContext, args: GenArg[]) => unknown;
+/** Strip accents/spaces/punctuation to a lowercase URL slug. */
+declare function slugify(input: string): string;
+declare const generators: Record<string, Generator>;
+/** Short human sample values for the `list` command / discovery. */
+declare const GEN_ORDER: string[];
+/** Look up + invoke a generator by name, throwing a clear error if unknown. */
+declare function callGen(name: string, ctx: GenContext, args: GenArg[]): unknown;
+declare function hasGen(name: string): boolean;
+
+type Spec = (ctx: GenContext) => unknown;
+interface Field {
+    key: string;
+    spec: Spec;
+}
+/** Parse the inner arg string of `gen(...)` into positional args. */
+declare function parseArgString(inner: string): GenArg[];
+/** Compile a string spec like `fullName` or `int(18..65)` into a resolver. */
+declare function specFromString(raw: string): Spec;
+/** Compile any JSON schema value (string | object | primitive) into a resolver. */
+declare function specFromJson(value: unknown): Spec;
+/** Parse an inline `--fields` string into an ordered list of fields. */
+declare function parseFields(input: string): Field[];
+/** Parse a JSON schema object into an ordered list of fields. */
+declare function parseJsonSchema(schema: unknown): Field[];
+interface GenerateOptions {
+    count?: number;
+    seed?: number | string;
+    locale?: Locale;
+}
+/** Generate `count` rows from a compiled field list. Deterministic under `seed`. */
+declare function generateRows(fields: Field[], opts?: GenerateOptions): Record<string, unknown>[];
+/** Generate `count` scalar values from a single generator spec string. */
+declare function generateValues(specStr: string, opts?: GenerateOptions): unknown[];
+
+/**
+ * Output formatters: JSON (array), NDJSON (one object per line), CSV (with a
+ * header row) and SQL `INSERT` statements. String values in SQL and CSV are
+ * escaped so a value containing a quote can't break — or inject into — the
+ * output.
+ */
+type Format = "json" | "ndjson" | "csv" | "sql";
+declare function isFormat(v: string): v is Format;
+interface FormatOptions {
+    format: Format;
+    pretty?: boolean;
+    /** Required for `sql`: the target table name. */
+    table?: string;
+}
+type Row = Record<string, unknown>;
+/** The union of keys across rows, preserving first-seen order. */
+declare function columnsOf(rows: Row[]): string[];
+declare function toCsv(rows: Row[]): string;
+/** Escape a single SQL value. Strings are single-quoted with `'` doubled. */
+declare function sqlValue(v: unknown): string;
+/** Quote a SQL identifier (table/column) defensively with double quotes. */
+declare function sqlIdent(name: string): string;
+declare function toSql(rows: Row[], table: string): string;
+/** Format an array of rows in the requested output format. */
+declare function formatRows(rows: Row[], opts: FormatOptions): string;
+/** Format an array of scalar values (single-generator mode). */
+declare function formatValues(values: unknown[], column: string, opts: FormatOptions): string;
+
+export { type Field, type Format, type FormatOptions, GEN_ORDER, type GenArg, type GenContext, type GenerateOptions, type Generator, LOCALES, type Locale, type LocaleData, RNG, type Spec, callGen, columnsOf, formatRows, formatValues, generateRows, generateValues, generators, hasGen, hashSeed, isFormat, isLocale, normalizeSeed, parseArgString, parseFields, parseJsonSchema, slugify, specFromJson, specFromString, sqlIdent, sqlValue, toCsv, toSql };

package/dist/lib.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Seeded pseudo-random number generator (mulberry32).
+ *
+ * Deterministic: the same seed always yields the same sequence, which is what
+ * makes fake-data fixtures reproducible across runs and machines. Every
+ * generator in this package draws exclusively from an `RNG` instance so that a
+ * fixed `--seed` produces byte-identical output.
+ */
+/** Hash an arbitrary string to a 32-bit unsigned integer (for string seeds). */
+declare function hashSeed(input: string): number;
+/** Coerce a user-supplied seed (number, numeric string, or arbitrary string). */
+declare function normalizeSeed(seed: number | string): number;
+/** A seeded random source with typed convenience helpers. */
+declare class RNG {
+    private readonly _next;
+    readonly seed: number;
+    constructor(seed: number | string);
+    /** Uniform float in [0, 1). */
+    next(): number;
+    /** Inclusive integer in [min, max]. */
+    int(min: number, max: number): number;
+    /** Float in [min, max) rounded to `decimals` places (default 2). */
+    float(min: number, max: number, decimals?: number): number;
+    /** `true` with probability `prob` (default 0.5). */
+    bool(prob?: number): boolean;
+    /** Pick one element uniformly. Throws on an empty array. */
+    pick<T>(items: readonly T[]): T;
+    /** Pick `n` distinct elements (Fisher–Yates partial shuffle). */
+    sample<T>(items: readonly T[], n: number): T[];
+    /** Return a shuffled copy. */
+    shuffle<T>(items: readonly T[]): T[];
+    /** Weighted pick. Entries are `[value, weight]`; weights need not sum to 1. */
+    weighted<T>(entries: readonly (readonly [T, number])[]): T;
+    /** A string of `len` random hex characters. */
+    hex(len: number): string;
+    /** A string of `len` random decimal digits. */
+    digits(len: number): string;
+    /** Pick `len` characters from an alphabet. */
+    chars(alphabet: string, len: number): string;
+    /** An RFC-4122 version-4 UUID, drawn deterministically from this RNG. */
+    uuid(): string;
+}
+
+/**
+ * Locale data tables. `en` (default) is generic English/US-ish; `ne` is
+ * Nepal-aware (romanized Nepali names, districts, provinces, NPR, +977 phones).
+ * Everything here is a plain constant so generators stay pure functions of the
+ * RNG plus a locale table.
+ */
+type Locale = "en" | "ne";
+interface LocaleData {
+    firstNamesMale: string[];
+    firstNamesFemale: string[];
+    lastNames: string[];
+    cities: string[];
+    states: string[];
+    country: string;
+    countryCode: string;
+    streetNames: string[];
+    streetSuffixes: string[];
+    /** How to build a postal/ZIP code for this locale. */
+    zip: (r: {
+        digits: (n: number) => string;
+    }) => string;
+    currency: {
+        code: string;
+        symbol: string;
+    };
+    /** E.164 phone (with +country) and a local-format phone. */
+    phone: (r: {
+        digits: (n: number) => string;
+        pick: <T>(a: readonly T[]) => T;
+    }) => {
+        e164: string;
+        local: string;
+    };
+}
+declare const LOCALES: Record<Locale, LocaleData>;
+declare function isLocale(v: string): v is Locale;
+
+/**
+ * The generator library. Each generator is a pure function of a `GenContext`
+ * (an RNG + locale + row index + the partially-built row) and an optional list
+ * of positional args. Generators are looked up by name from the `generators`
+ * registry, which powers the CLI, the schema engine and the `list` command.
+ */
+
+interface GenContext {
+    rng: RNG;
+    locale: Locale;
+    /** Zero-based row index — used by `autoincrement`. */
+    index: number;
+    /** The row built so far; lets `email` derive from an earlier `firstName`. */
+    row: Record<string, unknown>;
+}
+type GenArg = string | number;
+type Generator = (ctx: GenContext, args: GenArg[]) => unknown;
+/** Strip accents/spaces/punctuation to a lowercase URL slug. */
+declare function slugify(input: string): string;
+declare const generators: Record<string, Generator>;
+/** Short human sample values for the `list` command / discovery. */
+declare const GEN_ORDER: string[];
+/** Look up + invoke a generator by name, throwing a clear error if unknown. */
+declare function callGen(name: string, ctx: GenContext, args: GenArg[]): unknown;
+declare function hasGen(name: string): boolean;
+
+type Spec = (ctx: GenContext) => unknown;
+interface Field {
+    key: string;
+    spec: Spec;
+}
+/** Parse the inner arg string of `gen(...)` into positional args. */
+declare function parseArgString(inner: string): GenArg[];
+/** Compile a string spec like `fullName` or `int(18..65)` into a resolver. */
+declare function specFromString(raw: string): Spec;
+/** Compile any JSON schema value (string | object | primitive) into a resolver. */
+declare function specFromJson(value: unknown): Spec;
+/** Parse an inline `--fields` string into an ordered list of fields. */
+declare function parseFields(input: string): Field[];
+/** Parse a JSON schema object into an ordered list of fields. */
+declare function parseJsonSchema(schema: unknown): Field[];
+interface GenerateOptions {
+    count?: number;
+    seed?: number | string;
+    locale?: Locale;
+}
+/** Generate `count` rows from a compiled field list. Deterministic under `seed`. */
+declare function generateRows(fields: Field[], opts?: GenerateOptions): Record<string, unknown>[];
+/** Generate `count` scalar values from a single generator spec string. */
+declare function generateValues(specStr: string, opts?: GenerateOptions): unknown[];
+
+/**
+ * Output formatters: JSON (array), NDJSON (one object per line), CSV (with a
+ * header row) and SQL `INSERT` statements. String values in SQL and CSV are
+ * escaped so a value containing a quote can't break — or inject into — the
+ * output.
+ */
+type Format = "json" | "ndjson" | "csv" | "sql";
+declare function isFormat(v: string): v is Format;
+interface FormatOptions {
+    format: Format;
+    pretty?: boolean;
+    /** Required for `sql`: the target table name. */
+    table?: string;
+}
+type Row = Record<string, unknown>;
+/** The union of keys across rows, preserving first-seen order. */
+declare function columnsOf(rows: Row[]): string[];
+declare function toCsv(rows: Row[]): string;
+/** Escape a single SQL value. Strings are single-quoted with `'` doubled. */
+declare function sqlValue(v: unknown): string;
+/** Quote a SQL identifier (table/column) defensively with double quotes. */
+declare function sqlIdent(name: string): string;
+declare function toSql(rows: Row[], table: string): string;
+/** Format an array of rows in the requested output format. */
+declare function formatRows(rows: Row[], opts: FormatOptions): string;
+/** Format an array of scalar values (single-generator mode). */
+declare function formatValues(values: unknown[], column: string, opts: FormatOptions): string;
+
+export { type Field, type Format, type FormatOptions, GEN_ORDER, type GenArg, type GenContext, type GenerateOptions, type Generator, LOCALES, type Locale, type LocaleData, RNG, type Spec, callGen, columnsOf, formatRows, formatValues, generateRows, generateValues, generators, hasGen, hashSeed, isFormat, isLocale, normalizeSeed, parseArgString, parseFields, parseJsonSchema, slugify, specFromJson, specFromString, sqlIdent, sqlValue, toCsv, toSql };