@rljson/edge 0.0.0 → 0.0.1

package/dist/car-world/scene-builder.d.ts

@@ -0,0 +1,40 @@
+import { ECadConfig } from '../config/config.ts';
+import { EEmitter } from '../core/emitter.ts';
+import { EVariant } from './plan.ts';
+/** What a scene builder needs */
+export interface ESceneBuilderOptions {
+    /** Receives the rows */
+    emitter: EEmitter;
+    /** The CAD layer configuration */
+    config: Required<ECadConfig>;
+    /** Who the scene belongs to */
+    variant: EVariant;
+    /** The parts of the variant's bill of materials, for linking meshes */
+    partRefs: readonly string[];
+}
+/**
+ * Emits the scene of a variant as a tree, from the meshes up.
+ *
+ * Every node carries the variant in its meta data, so two variants never
+ * share a node. Nodes are numbered in the order they are emitted, children
+ * before their group. Build once per instance.
+ */
+export declare class ESceneBuilder {
+    private readonly options;
+    /**
+     * Constructor
+     * @param options - The emitter, the CAD layer, the variant and its parts
+     */
+    constructor(options: ESceneBuilderOptions);
+    /** Emits the scene and returns the hash of its root */
+    build(): Promise<string>;
+    private index;
+    private system;
+    private components;
+    private details;
+    private group;
+    private mesh;
+    private node;
+    private meta;
+    private partRefOf;
+}

package/dist/car-world/table-cfgs.d.ts

@@ -0,0 +1,22 @@
+import { TableCfg } from '@rljson/rljson';
+import { ECarWorldTableKey } from './car-world.ts';
+/** Returns the configuration of the manufacturers table: the root of the world */
+export declare const manufacturersTableCfg: () => TableCfg;
+/** Returns the configuration of the addresses table */
+export declare const addressesTableCfg: () => TableCfg;
+/** Returns the configuration of the persons table */
+export declare const personsTableCfg: () => TableCfg;
+/** Returns the configuration of the workshops table */
+export declare const workshopsTableCfg: () => TableCfg;
+/** Returns the configuration of the prices table */
+export declare const pricesTableCfg: () => TableCfg;
+/** Returns the configuration of the brands table */
+export declare const brandsTableCfg: () => TableCfg;
+/** Returns the configuration of the parts table */
+export declare const partsTableCfg: () => TableCfg;
+/** Returns the configuration of the revisions table */
+export declare const revisionsTableCfg: () => TableCfg;
+/** Returns the configuration of the tableCfgs table itself */
+export declare const tableCfgsTableCfg: () => TableCfg;
+/** Returns the configurations of all tables of a car world, by table key */
+export declare const carWorldTableCfgs: () => Record<ECarWorldTableKey, TableCfg>;

package/dist/car-world/workshops.d.ts

@@ -0,0 +1,39 @@
+import { EWorkshopsConfig } from '../config/config.ts';
+import { EEmitter } from '../core/emitter.ts';
+import { ECity } from '../dictionaries/places.ts';
+import { EAddress, EPerson } from './car-world.ts';
+/** The services a workshop can offer */
+export declare const services: readonly string[];
+/**
+ * Returns the address with an index in a city. Street and house number
+ * derive from the index, so no two indices share an address.
+ * @param city - The city
+ * @param index - Any non-negative index
+ */
+export declare const addressRow: (city: ECity, index: number) => EAddress;
+/**
+ * Returns the person with an index. The phone number makes every index a
+ * different person, even when the names repeat.
+ * @param index - Any non-negative index
+ * @param country - The country the phone number belongs to
+ */
+export declare const personRow: (index: number, country: string) => EPerson;
+/** What the workshops of a catalog depend on */
+export interface EWorkshopsOptions {
+    /** Receives the rows */
+    emitter: EEmitter;
+    /** The workshops layer configuration */
+    config: Required<EWorkshopsConfig>;
+    /** The index of the manufacturer, for the owner pool */
+    manufacturerIndex: number;
+    /** The index of the catalog within the world */
+    catalogIndex: number;
+    /** The country of the manufacturer */
+    country: string;
+}
+/**
+ * Emits the workshops of a catalog with their addresses and owners, and
+ * returns the hashes of the workshops.
+ * @param options - The emitter, the layer and the catalog
+ */
+export declare const generateWorkshops: (options: EWorkshopsOptions) => Promise<string[]>;

package/dist/config/config.d.ts

@@ -0,0 +1,177 @@
+import { TableKey } from '@rljson/rljson';
+/** Who shares a bill of materials or a CAD scene */
+export type ESharing = 'perCar' | 'perModel' | 'perCatalog';
+/** The prices layer */
+export interface EPricesConfig {
+    /** The currencies; each catalog uses one of them. Default ['EUR'] */
+    currencies?: string[];
+    /** The range of the prices. Default 5 000 to 150 000 */
+    range?: {
+        min: number;
+        max: number;
+    };
+    /** Prices are rounded to a multiple of this. Default 10 */
+    roundTo?: number;
+    /** The share of cars with a discount, between 0 and 1. Default 0 */
+    discountShare?: number;
+}
+/** The brands layer */
+export interface EBrandsConfig {
+    /** How many models of a manufacturer the cars use. Default 5 */
+    modelsPerManufacturer?: number;
+    /** How the cars spread over the models. Default 'uniform' */
+    popularity?: 'uniform' | 'zipf';
+}
+/** The workshops layer */
+export interface EWorkshopsConfig {
+    /** How many workshops serve a catalog. Default 10 */
+    perCatalog?: number;
+    /** How many persons own the workshops of a manufacturer. Default 5 */
+    ownersPerManufacturer?: number;
+}
+/** The parts layer: bills of materials */
+export interface EPartsConfig {
+    /** Levels below the bill of materials, 1 to 4. Default 4 */
+    depth?: 1 | 2 | 3 | 4;
+    /** Sub parts per part, 1 to 6. Default 3 */
+    fanOut?: number;
+    /** Who shares a bill of materials. Default 'perModel' */
+    sharing?: ESharing;
+    /** How many distinct standard parts the lowest level uses, 1 to 40. Default 20 */
+    standardPartsPool?: number;
+}
+/** The CAD layer: scenes as trees */
+export interface ECadConfig {
+    /** Levels below the scene, 1 to 4. Default 3 */
+    depth?: 1 | 2 | 3 | 4;
+    /** Children per group, 1 to 6. Default 4 */
+    fanOut?: number;
+    /** Who shares a scene. Default 'perModel' */
+    sharing?: ESharing;
+    /** Whether a mesh refers to a part of the bill of materials. Default true */
+    linkToParts?: boolean;
+}
+/** The layers of every catalog. A layer set to false is left out. */
+export interface ELayersConfig {
+    /** The prices of the cars */
+    prices?: EPricesConfig | false;
+    /** The brands and models of the cars */
+    brands?: EBrandsConfig | false;
+    /** The workshops that service the cars */
+    workshops?: EWorkshopsConfig | false;
+    /** The bills of materials of the cars */
+    parts?: EPartsConfig | false;
+    /** The CAD scenes of the cars */
+    cad?: ECadConfig | false;
+}
+/** Further model years of every catalog */
+export interface ERevisionsConfig {
+    /** How many model years follow the first one. Default 0 */
+    count?: number;
+    /** The share of cars a model year adds, between 0 and 1. Default 0.2 */
+    addShare?: number;
+    /** The share of cars a model year removes, between 0 and 1. Default 0.1 */
+    removeShare?: number;
+    /** The share of cars whose price a model year changes, between 0 and 1. Default 0.2 */
+    changeShare?: number;
+}
+/** The progress of a run */
+export interface EProgress {
+    /** The phase of the run, e.g. the table being generated */
+    phase: string;
+    /** The rows handed to the sink so far */
+    rowsDone: number;
+    /** The rows the run produces at most, from the estimate */
+    rowsTotal: number;
+    /** The table of the row that triggered the report, if any */
+    table?: TableKey;
+}
+/**
+ * The configuration of a car world.
+ *
+ * Every field has a default. Nothing is random: the same configuration yields
+ * the same data and the same hashes, on every machine.
+ */
+export interface EConfig {
+    /** The manufacturers, the entry point of the world */
+    manufacturers?: {
+        /** How many manufacturers. Default 1 */
+        count?: number;
+        /** How many catalogs each manufacturer has. Default 1 */
+        catalogsPerManufacturer?: number;
+    };
+    /** The catalogs: cakes whose slices are cars */
+    catalogs?: {
+        /** How many cars a catalog lists, up to a million. Default 10 */
+        carsPerCatalog?: number;
+        /** The model year of the first version of every catalog. Default 2026 */
+        startYear?: number;
+        /** Further model years */
+        revisions?: ERevisionsConfig;
+    };
+    /** The layers of every catalog. A layer set to false is left out. */
+    layers?: ELayersConfig;
+    /** Lets Edge choose the cars per catalog for a number of rows */
+    scale?: {
+        /** The number of rows the world should have at most; null for no target */
+        targetRows?: number | null;
+    };
+    /** Receives the progress of a run */
+    progress?: (progress: EProgress) => void;
+    /** Report progress after every this many rows. Default 1000 */
+    progressEvery?: number;
+    /** Stops a run when aborted */
+    abortSignal?: AbortSignal;
+}
+/** The layers with every default filled in; a layer that is off stays false */
+export interface EResolvedLayers {
+    prices: Required<EPricesConfig> | false;
+    brands: Required<EBrandsConfig> | false;
+    workshops: Required<EWorkshopsConfig> | false;
+    parts: Required<EPartsConfig> | false;
+    cad: Required<ECadConfig> | false;
+}
+/** The configuration with every default filled in */
+export interface EResolvedConfig {
+    manufacturers: {
+        count: number;
+        catalogsPerManufacturer: number;
+    };
+    catalogs: {
+        carsPerCatalog: number;
+        startYear: number;
+        revisions: Required<ERevisionsConfig>;
+    };
+    layers: EResolvedLayers;
+    scale: {
+        targetRows: number | null;
+    };
+    progress?: (progress: EProgress) => void;
+    progressEvery: number;
+    abortSignal?: AbortSignal;
+}
+/** The deepest level below a bill of materials or a scene */
+export declare const maxDepth = 4;
+/** The most children a part or a group has: the dictionaries list six */
+export declare const maxFanOut = 6;
+/** The most cars a catalog may list */
+export declare const maxCarsPerCatalog = 1000000;
+/** Returns the defaults of every section */
+export declare const edgeDefaults: () => EResolvedConfig;
+/**
+ * Returns the fallback with every defined value of the overrides on top.
+ * A value that is undefined keeps its default.
+ * @param fallback - The defaults
+ * @param overrides - The values of the user, or undefined
+ */
+export declare const withDefaults: <T extends object>(fallback: T, overrides: Partial<T> | undefined) => T;
+/**
+ * Fills the defaults into a configuration and checks its values.
+ * @param config - The configuration of the user
+ */
+export declare const resolveEdgeConfig: (config: EConfig) => EResolvedConfig;
+/**
+ * Throws when a value of the configuration is out of range.
+ * @param config - The resolved configuration
+ */
+export declare const validateEdgeConfig: (config: EResolvedConfig) => void;

package/dist/config/presets.d.ts

@@ -0,0 +1,13 @@
+import { EConfig } from './config.ts';
+/** The names of the presets, from the smallest to the largest */
+export declare const edgePresetNames: readonly ["tiny", "small", "medium", "large", "xl"];
+/** The name of a preset */
+export type EPresetName = (typeof edgePresetNames)[number];
+/**
+ * Ready-made configurations.
+ *
+ * tiny and small fit unit and component tests, medium an integration test.
+ * large reaches more than 20 million rows by giving every car a bill of
+ * materials and a scene of its own; xl reaches 20 million cars.
+ */
+export declare const edgePresets: Readonly<Record<EPresetName, EConfig>>;

package/dist/core/emitter.d.ts

@@ -0,0 +1,71 @@
+import { Json } from '@rljson/json';
+import { TableCfg, TableKey } from '@rljson/rljson';
+import { EProgress } from '../config/config.ts';
+import { ESink } from './sink.ts';
+/** A row with the hash that hsh wrote into it */
+export type EHashed<T extends Json> = T & {
+    _hash: string;
+};
+/** What an emitter needs */
+export interface EEmitterOptions {
+    /** Receives the rows */
+    sink: ESink;
+    /** The number of rows the run will produce at most, from the estimate */
+    rowsTotal: number;
+    /** Report progress after every this many rows */
+    progressEvery: number;
+    /** Receives the progress */
+    progress?: (progress: EProgress) => void;
+    /** Stops the run when aborted */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Hashes rows, drops duplicates and hands the rest to the sink.
+ *
+ * Equal content has an equal hash, so a row that was emitted before is not
+ * emitted again; the emitter keeps one set of hashes per table for that.
+ * The rows are handed over one after the other, and every handover is
+ * awaited: a row may only follow the rows it refers to, and a slow sink
+ * slows the generator down.
+ */
+export declare class EEmitter {
+    private readonly options;
+    /**
+     * Constructor
+     * @param options - The sink and the progress settings
+     */
+    constructor(options: EEmitterOptions);
+    /**
+     * Announces a table: hands its configuration to the sink and writes the
+     * configuration into the tableCfgs table.
+     * @param tableCfg - The configuration of the table
+     */
+    table(tableCfg: TableCfg): Promise<EHashed<TableCfg>>;
+    /**
+     * Sets the phase of the run and reports it.
+     * @param phase - The name of the phase, e.g. the table being generated
+     */
+    phaseIs(phase: string): void;
+    /**
+     * Hashes a row and hands it to the sink, unless an equal row was emitted
+     * before. Returns the hashed row either way.
+     * @param table - The key of the table
+     * @param row - The row without hash
+     */
+    emit<T extends Json>(table: TableKey, row: T): Promise<EHashed<T>>;
+    /** The number of rows handed to the sink */
+    get rowsDone(): number;
+    /** The number of rows produced, including the duplicates that were dropped */
+    get rowsProduced(): number;
+    /** The number of rows handed to the sink, per table */
+    get rowsPerTable(): Record<string, number>;
+    private phase;
+    private done;
+    private produced;
+    private readonly counts;
+    private readonly seen;
+    private isDuplicate;
+    private throwIfAborted;
+    private count;
+    private report;
+}

package/dist/core/estimate.d.ts

@@ -0,0 +1,33 @@
+import { EResolvedConfig } from '../config/config.ts';
+/** How big a world will be, calculated from the configuration alone */
+export interface EEstimate {
+    /** How many different cars the world holds */
+    cars: number;
+    /** How many rows the world has at most; rows that happen to be equal fold into one */
+    rowsTotal: number;
+    /** How many rows each table has at most */
+    rowsPerTable: Record<string, number>;
+    /** The approximate size of the world as JSON, in bytes */
+    approxBytes: number;
+}
+/** The most cars Edge puts into one catalog when it fits a target */
+export declare const maxFittedCarsPerCatalog = 100000;
+/**
+ * Estimates the rows of a car world without generating a single one.
+ *
+ * The counts are exact for everything that is unique by construction, and an
+ * upper bound where two rows may happen to be equal, like prices.
+ * @param config - The resolved configuration
+ */
+export declare const estimateCarWorld: (config: EResolvedConfig) => EEstimate;
+/**
+ * Returns the largest number of cars per catalog whose world stays within a
+ * number of rows: at least 1, at most maxFittedCarsPerCatalog.
+ *
+ * When the rows never reach the target, because the cars share their bills
+ * of materials and scenes, the result is maxFittedCarsPerCatalog. More rows
+ * then come from more catalogs or from sharing per car.
+ * @param config - The resolved configuration
+ * @param targetRows - The number of rows the world should have at most
+ */
+export declare const fitCarsPerCatalog: (config: EResolvedConfig, targetRows: number) => number;

package/dist/core/pick.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Returns the entry at an index, wrapping around the end of the list.
+ * @param list - The list to pick from
+ * @param index - Any non-negative index
+ */
+export declare const pick: <T>(list: readonly T[], index: number) => T;
+/**
+ * Returns count entries starting at an offset, wrapping around the end.
+ *
+ * The entries are distinct as long as count does not exceed the length.
+ * @param list - The list to pick from
+ * @param offset - The index of the first entry
+ * @param count - The number of entries
+ */
+export declare const pickMany: <T>(list: readonly T[], offset: number, count: number) => T[];
+/**
+ * Tells whether an index falls into a share of a sequence.
+ *
+ * Of n consecutive indices, exactly round(n * share) are in the share, spread
+ * evenly: with a share of 0.25 every fourth index is in.
+ * @param index - The index within the sequence
+ * @param share - The share between 0 and 1
+ */
+export declare const inShare: (index: number, share: number) => boolean;
+/** Where an index sits and how many buckets share the sequence */
+export interface EZipfOptions {
+    /** The index within the sequence */
+    index: number;
+    /** The length of the sequence */
+    count: number;
+    /** The number of buckets */
+    buckets: number;
+}
+/**
+ * Returns the harmonic number of n: 1 + 1/2 + … + 1/n.
+ * @param n - The number of terms
+ */
+export declare const harmonic: (n: number) => number;
+/**
+ * Maps an index of a sequence to a bucket, following a Zipf distribution.
+ *
+ * Bucket 0 receives the most indices, bucket 1 half as many, bucket 2 a
+ * third, and so on. Consecutive indices land in the same bucket.
+ * @param options - The index, the length of the sequence and the buckets
+ */
+export declare const zipfBucket: (options: EZipfOptions) => number;
+/**
+ * Pads a number with leading zeros.
+ * @param value - The number
+ * @param width - The minimum number of digits
+ */
+export declare const padded: (value: number, width: number) => string;
+/**
+ * Turns a name into a kebab case slug: lower case, ASCII letters and digits.
+ * @param name - The name, e.g. "Lynk & Co"
+ */
+export declare const slug: (name: string) => string;
+/**
+ * Rounds a value to the nearest multiple of a step.
+ * @param value - The value
+ * @param step - The step, e.g. 100
+ */
+export declare const roundTo: (value: number, step: number) => number;
+/**
+ * Rounds a value to a number of decimals.
+ * @param value - The value
+ * @param decimals - The decimals to keep
+ */
+export declare const roundDecimals: (value: number, decimals: number) => number;

package/dist/core/sink.d.ts

@@ -0,0 +1,49 @@
+import { Rljson, Row, TableCfg, TableKey } from '@rljson/rljson';
+/**
+ * Receives the rows of a run.
+ *
+ * Edge writes nothing itself: no file, no database. The application decides
+ * where the rows go, in Node.js, in the browser or in a Web Worker.
+ */
+export interface ESink {
+    /**
+     * Receives a row of a table. The rows come in the order of their
+     * references. A returned promise is awaited, so a slow sink slows the
+     * generator down.
+     * @param table - The key of the table
+     * @param row - The hashed row
+     */
+    onRow(table: TableKey, row: Row): void | Promise<void>;
+    /**
+     * Receives the configuration of a table before its first row. A database
+     * creates the table here.
+     * @param table - The key of the table
+     * @param tableCfg - The hashed configuration of the table
+     */
+    onTable?(table: TableKey, tableCfg: TableCfg): void | Promise<void>;
+}
+/** Collects the rows of a run in memory: the sink behind generate() */
+export declare class EMemorySink implements ESink {
+    /**
+     * Remembers the configuration of a table.
+     * @param table - The key of the table
+     * @param tableCfg - The hashed configuration of the table
+     */
+    onTable(table: TableKey, tableCfg: TableCfg): void;
+    /**
+     * Collects a row.
+     * @param table - The key of the table
+     * @param row - The hashed row
+     */
+    onRow(table: TableKey, row: Row): void;
+    /**
+     * Returns the collected rows as an Rljson object.
+     *
+     * Every table carries its content type, the hash of its configuration and
+     * a hash of its own.
+     */
+    toRljson(): Rljson;
+    private readonly tables;
+    private entry;
+    private tableOf;
+}

package/dist/dictionaries/cad.d.ts

@@ -0,0 +1,13 @@
+/** A system group of a CAD scene (level 1) with its component groups (level 2) */
+export interface ECadSystem {
+    /** The id of the group, unique among the children of the scene */
+    id: string;
+    /** The ids of the component groups below the system */
+    children: readonly string[];
+}
+/** The system groups of a car scene, each with six components */
+export declare const cadSystems: readonly ECadSystem[];
+/** Names for the nodes below the component groups (level 3 and deeper) */
+export declare const cadDetails: readonly string[];
+/** The materials of meshes, picked by index */
+export declare const cadMaterials: readonly string[];

package/dist/dictionaries/manufacturers.d.ts

@@ -0,0 +1,21 @@
+/** A car manufacturer or brand with a few facts about it */
+export interface EManufacturerEntry {
+    /** The id of the manufacturer: the brand in kebab case */
+    id: string;
+    /** The name of the company */
+    name: string;
+    /** The brand name the cars carry */
+    brand: string;
+    /** The ISO 3166 country code of the headquarters */
+    country: string;
+    /** The city of the headquarters, listed in the places dictionary */
+    city: string;
+    /** The year the brand was founded, approximately */
+    founded: number;
+}
+/**
+ * Car manufacturers and brands from around the world.
+ *
+ * The facts are approximate and meant for test data only.
+ */
+export declare const manufacturers: readonly EManufacturerEntry[];

package/dist/dictionaries/parts.d.ts

@@ -0,0 +1,29 @@
+/** A sub assembly of an assembly, with the names of its parts (level 2 and 3) */
+export interface ESubAssembly {
+    /** The name of the sub assembly */
+    name: string;
+    /** The names of the parts the sub assembly consists of */
+    parts: readonly string[];
+}
+/** An assembly of a car: level 1 of a bill of materials */
+export interface EAssembly {
+    /** The name of the assembly */
+    name: string;
+    /** The category of the assembly and of everything below it */
+    category: string;
+    /** The sub assemblies the assembly consists of */
+    subAssemblies: readonly ESubAssembly[];
+}
+/** A standard part shared by many bills of materials: level 4 */
+export interface EStandardPart {
+    /** The name of the standard part */
+    name: string;
+    /** The material of the standard part */
+    material: string;
+}
+/** The assemblies of a car, each with six sub assemblies of six parts */
+export declare const assemblies: readonly EAssembly[];
+/** Standard parts: screws, seals, bearings, shared by every bill of materials */
+export declare const standardParts: readonly EStandardPart[];
+/** The materials of the parts of a category, picked by index */
+export declare const materialsOf: Readonly<Record<string, readonly string[]>>;

package/dist/dictionaries/people.d.ts

@@ -0,0 +1,4 @@
+/** First names from many countries */
+export declare const firstNames: readonly string[];
+/** Last names from many countries */
+export declare const lastNames: readonly string[];

package/dist/dictionaries/places.d.ts

@@ -0,0 +1,27 @@
+/** A city with its country, a postal code and coordinates */
+export interface ECity {
+    /** The name of the city */
+    name: string;
+    /** The ISO 3166 country code, e.g. DE */
+    country: string;
+    /** A postal code of the city */
+    zip: string;
+    /** The latitude in degrees */
+    lat: number;
+    /** The longitude in degrees */
+    lng: number;
+}
+/** Cities around the world, including the headquarters of every manufacturer */
+export declare const cities: readonly ECity[];
+/** Street names from many countries */
+export declare const streets: readonly string[];
+/**
+ * Returns the cities of a country, or all cities when the country has none.
+ * @param country - The ISO 3166 country code
+ */
+export declare const citiesIn: (country: string) => readonly ECity[];
+/**
+ * Returns the city with a name, or throws when the dictionary has none.
+ * @param name - The name of the city
+ */
+export declare const cityNamed: (name: string) => ECity;

package/dist/dictionaries/vehicles.d.ts

@@ -0,0 +1,22 @@
+/** The body types of the vehicles */
+export type EBodyType = 'sedan' | 'hatchback' | 'wagon' | 'suv' | 'coupe' | 'convertible' | 'van' | 'pickup' | 'truck' | 'sportscar' | 'minivan' | 'microcar';
+/** The fuels of the vehicles */
+export type EFuel = 'petrol' | 'diesel' | 'hybrid' | 'electric' | 'hydrogen';
+/** A vehicle model of a brand */
+export interface EVehicleModel {
+    /** The brand, as in the manufacturers dictionary */
+    brand: string;
+    /** The name of the model */
+    model: string;
+    /** The body type of the model */
+    bodyType: EBodyType;
+    /** The fuel of the model */
+    fuel: EFuel;
+}
+/** Vehicle models of every brand in the manufacturers dictionary */
+export declare const vehicles: readonly EVehicleModel[];
+/**
+ * Returns the models of a brand, in the order of the dictionary.
+ * @param brand - The brand, as in the manufacturers dictionary
+ */
+export declare const modelsOf: (brand: string) => readonly EVehicleModel[];