@lunora/seed 0.0.0 → 1.0.0-alpha.1

package/dist/index.d.mts

@@ -0,0 +1,64 @@
+import { Schema } from '@lunora/server';
+import { O as OverrideContext } from "./packem_shared/plan.d-BQ6LiWIk.mjs";
+export { type S as SeedCounts, type a as SeedOptions, type b as SeedOverrides, type T as TablePlan, s as seedPlan } from "./packem_shared/plan.d-BQ6LiWIk.mjs";
+/**
+* A typed, schema-aware seed client — the ergonomic DX layer over {@link seedPlan}.
+*
+* Where `seedPlan` generates every table at once, the client lets you author one
+* table at a time, with autocomplete on each table's columns and live foreign-key
+* connection to whatever was seeded earlier this run. Pass your generated
+* `InsertModel` type as the type argument — or let `lunora/_generated/seed.ts`
+* do that for you — for full type inference on each table's columns.
+*
+* The client is deterministic (same `seed` ⇒ same rows and ids) and pure unless a
+* `persist` hook is supplied, in which case each generated batch is also written
+* through it (the test harness, an admin import, …). Because every row carries an
+* explicit `_id`, the returned ids are known whether or not anything is persisted.
+*/
+/** Picks a concrete count: a fixed number, or a deterministic value within `[min, max]`. */
+type CountHelper = (countOrRange: number | readonly [number, number]) => number;
+/** The per-call population spec: a count, an inclusive range, explicit partial rows, or a count callback. */
+type SeedSpec<Row> = number | ReadonlyArray<Partial<Row>> | readonly [number, number] | ((x: CountHelper) => number);
+/** A per-field override: a fixed value or a function of the row context. */
+type FieldOverride<Value> = ((context: OverrideContext) => Value) | Value;
+/** Options for a single table call. `overrides` win over any explicit partial rows. */
+interface SeedCallOptions<Row> {
+  overrides?: { [K in keyof Row]?: FieldOverride<Row[K]> };
+}
+/** The id columns the client emits, keyed by table — the result of a single table call. */
+type SeedCallResult<InsertModel, Table extends keyof InsertModel> = { [K in Table]: string[] };
+/** The seeder function exposed for one table. */
+type TableSeeder<InsertModel, Table extends keyof InsertModel> = (spec?: SeedSpec<InsertModel[Table]>, options?: SeedCallOptions<InsertModel[Table]>) => Promise<SeedCallResult<InsertModel, Table>>;
+/** The `$`-prefixed run state shared by every client. */
+interface SeedClientState {
+  /** Every id generated this run, keyed by table (includes auto-seeded FK parents). */
+  readonly $ids: Readonly<Record<string, ReadonlyArray<string>>>;
+  /** Clear all accumulated rows/ids so the client can drive a fresh run. */
+  $reset: () => void;
+  /** Every row generated this run, keyed by table. */
+  readonly $store: Readonly<Record<string, ReadonlyArray<Record<string, unknown>>>>;
+}
+/** The per-table seeder methods plus the `$`-prefixed run state. */
+type SeedClient<InsertModel> = SeedClientState & { [Table in keyof InsertModel]: TableSeeder<InsertModel, Table> };
+/** Options for {@link createSeedClient}. */
+interface SeedClientOptions {
+  /** Default row count when a table call passes no spec (default `10`). */
+  defaultCount?: number;
+  /** Persist each generated batch (e.g. insert through the test harness). Pure when omitted. */
+  persist?: (table: string, rows: ReadonlyArray<Record<string, unknown>>) => Promise<void> | void;
+  /** Deterministic mapping selector — same seed ⇒ same rows and ids. Default `0`. */
+  seed?: number;
+}
+/**
+* Create a typed seed client for `schema`. Each table is a method; call it with a
+* count, a range, or explicit partial rows, and its foreign keys connect to rows
+* seeded earlier this run. State accumulates on `$store`/`$ids` and clears with
+* `$reset()`.
+* @example
+* const seed = createSeedClient<InsertModel>(schema, { seed: 1 });
+* const { users } = await seed.users(5);
+* const { posts } = await seed.posts((x) => x([10, 20]));
+* // posts.authorId values are drawn from `users`.
+*/
+declare const createSeedClient: <InsertModel = Record<string, Record<string, unknown>>>(schema: Schema, options?: SeedClientOptions) => SeedClient<InsertModel>;
+export { type CountHelper, type OverrideContext, type SeedCallOptions, type SeedCallResult, type SeedClient, type SeedClientOptions, type SeedSpec, createSeedClient };

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import { Schema } from '@lunora/server';
+import { O as OverrideContext } from "./packem_shared/plan.d-BQ6LiWIk.js";
+export { type S as SeedCounts, type a as SeedOptions, type b as SeedOverrides, type T as TablePlan, s as seedPlan } from "./packem_shared/plan.d-BQ6LiWIk.js";
+/**
+* A typed, schema-aware seed client — the ergonomic DX layer over {@link seedPlan}.
+*
+* Where `seedPlan` generates every table at once, the client lets you author one
+* table at a time, with autocomplete on each table's columns and live foreign-key
+* connection to whatever was seeded earlier this run. Pass your generated
+* `InsertModel` type as the type argument — or let `lunora/_generated/seed.ts`
+* do that for you — for full type inference on each table's columns.
+*
+* The client is deterministic (same `seed` ⇒ same rows and ids) and pure unless a
+* `persist` hook is supplied, in which case each generated batch is also written
+* through it (the test harness, an admin import, …). Because every row carries an
+* explicit `_id`, the returned ids are known whether or not anything is persisted.
+*/
+/** Picks a concrete count: a fixed number, or a deterministic value within `[min, max]`. */
+type CountHelper = (countOrRange: number | readonly [number, number]) => number;
+/** The per-call population spec: a count, an inclusive range, explicit partial rows, or a count callback. */
+type SeedSpec<Row> = number | ReadonlyArray<Partial<Row>> | readonly [number, number] | ((x: CountHelper) => number);
+/** A per-field override: a fixed value or a function of the row context. */
+type FieldOverride<Value> = ((context: OverrideContext) => Value) | Value;
+/** Options for a single table call. `overrides` win over any explicit partial rows. */
+interface SeedCallOptions<Row> {
+  overrides?: { [K in keyof Row]?: FieldOverride<Row[K]> };
+}
+/** The id columns the client emits, keyed by table — the result of a single table call. */
+type SeedCallResult<InsertModel, Table extends keyof InsertModel> = { [K in Table]: string[] };
+/** The seeder function exposed for one table. */
+type TableSeeder<InsertModel, Table extends keyof InsertModel> = (spec?: SeedSpec<InsertModel[Table]>, options?: SeedCallOptions<InsertModel[Table]>) => Promise<SeedCallResult<InsertModel, Table>>;
+/** The `$`-prefixed run state shared by every client. */
+interface SeedClientState {
+  /** Every id generated this run, keyed by table (includes auto-seeded FK parents). */
+  readonly $ids: Readonly<Record<string, ReadonlyArray<string>>>;
+  /** Clear all accumulated rows/ids so the client can drive a fresh run. */
+  $reset: () => void;
+  /** Every row generated this run, keyed by table. */
+  readonly $store: Readonly<Record<string, ReadonlyArray<Record<string, unknown>>>>;
+}
+/** The per-table seeder methods plus the `$`-prefixed run state. */
+type SeedClient<InsertModel> = SeedClientState & { [Table in keyof InsertModel]: TableSeeder<InsertModel, Table> };
+/** Options for {@link createSeedClient}. */
+interface SeedClientOptions {
+  /** Default row count when a table call passes no spec (default `10`). */
+  defaultCount?: number;
+  /** Persist each generated batch (e.g. insert through the test harness). Pure when omitted. */
+  persist?: (table: string, rows: ReadonlyArray<Record<string, unknown>>) => Promise<void> | void;
+  /** Deterministic mapping selector — same seed ⇒ same rows and ids. Default `0`. */
+  seed?: number;
+}
+/**
+* Create a typed seed client for `schema`. Each table is a method; call it with a
+* count, a range, or explicit partial rows, and its foreign keys connect to rows
+* seeded earlier this run. State accumulates on `$store`/`$ids` and clears with
+* `$reset()`.
+* @example
+* const seed = createSeedClient<InsertModel>(schema, { seed: 1 });
+* const { users } = await seed.users(5);
+* const { posts } = await seed.posts((x) => x([10, 20]));
+* // posts.authorId values are drawn from `users`.
+*/
+declare const createSeedClient: <InsertModel = Record<string, Record<string, unknown>>>(schema: Schema, options?: SeedClientOptions) => SeedClient<InsertModel>;
+export { type CountHelper, type OverrideContext, type SeedCallOptions, type SeedCallResult, type SeedClient, type SeedClientOptions, type SeedSpec, createSeedClient };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+export { createSeedClient } from './packem_shared/createSeedClient-CI9LRLTi.mjs';
+export { s as seedPlan } from './packem_shared/plan-DirmkctQ.mjs';

package/dist/packem_shared/createSeedClient-CI9LRLTi.mjs

@@ -0,0 +1,92 @@
+import { a as setHashKey, s as seedPlan, c as copycat } from './plan-DirmkctQ.mjs';
+
+const isRange = (spec) => Array.isArray(spec) && spec.length === 2 && typeof spec[0] === "number" && typeof spec[1] === "number";
+const resolveSpec = (spec, table, seed, defaultCount) => {
+  const pick = (countOrRange) => typeof countOrRange === "number" ? countOrRange : copycat.int([seed, table, "count"], { max: countOrRange[1], min: countOrRange[0] });
+  if (spec === void 0) {
+    return { count: defaultCount };
+  }
+  if (typeof spec === "number") {
+    return { count: spec };
+  }
+  if (typeof spec === "function") {
+    return { count: spec(pick) };
+  }
+  if (isRange(spec)) {
+    return { count: pick(spec) };
+  }
+  return { count: spec.length, partials: spec };
+};
+const buildOverrides = (partials, fieldOverrides, offset) => {
+  const overrides = {};
+  if (partials !== void 0) {
+    const fields = new Set(partials.flatMap((partial) => Object.keys(partial)));
+    for (const field of fields) {
+      overrides[field] = (context) => partials[context.index - offset]?.[field];
+    }
+  }
+  for (const [field, value] of Object.entries(fieldOverrides ?? {})) {
+    overrides[field] = value;
+  }
+  return overrides;
+};
+const createSeedClient = (schema, options = {}) => {
+  const { defaultCount = 10, persist, seed = 0 } = options;
+  const store = {};
+  const idsByTable = {};
+  const createdCount = {};
+  const seedTable = async (table, spec, callOptions) => {
+    setHashKey(seed);
+    const { count, partials } = resolveSpec(spec, table, seed, defaultCount);
+    const offset = createdCount[table] ?? 0;
+    const plan = seedPlan(schema, {
+      counts: { [table]: count },
+      existingIds: idsByTable,
+      indexOffset: { [table]: offset },
+      only: [table],
+      overrides: { [table]: buildOverrides(partials, callOptions?.overrides, offset) },
+      seed
+    });
+    let created = [];
+    for (const { rows, table: planned } of plan) {
+      const ids = rows.map((row) => row._id);
+      store[planned] ??= [];
+      store[planned].push(...rows);
+      idsByTable[planned] ??= [];
+      idsByTable[planned].push(...ids);
+      createdCount[planned] = (createdCount[planned] ?? 0) + rows.length;
+      if (planned === table) {
+        created = ids;
+      }
+      if (persist !== void 0) {
+        await persist(planned, rows);
+      }
+    }
+    return { [table]: created };
+  };
+  const state = {
+    $ids: idsByTable,
+    $reset: () => {
+      for (const key of Object.keys(store)) {
+        delete store[key];
+      }
+      for (const key of Object.keys(idsByTable)) {
+        delete idsByTable[key];
+      }
+      for (const key of Object.keys(createdCount)) {
+        delete createdCount[key];
+      }
+    },
+    $store: store
+  };
+  return /* @__PURE__ */ new Proxy(state, {
+    get(target, property, receiver) {
+      if (typeof property === "string" && !property.startsWith("$") && Object.hasOwn(schema.tables, property)) {
+        return (spec, callOptions) => seedTable(property, spec, callOptions);
+      }
+      return Reflect.get(target, property, receiver);
+    }
+  });
+};
+
+export { createSeedClient };