@flaredev/core 0.1.2 → 0.3.0

package/dist/chunk-434JXSDV.js

@@ -0,0 +1,410 @@
+// src/resource/fields.ts
+var STRING_FORMATS = ["email", "url", "tel", "domain", "country", "color", "slug"];
+var FILE_CATEGORIES = {
+  image: ["image/png", "image/jpeg", "image/gif", "image/webp", "image/avif"],
+  pdf: ["application/pdf"],
+  video: ["video/*"],
+  audio: ["audio/*"],
+  text: ["text/plain"],
+  csv: ["text/csv"],
+  document: [
+    "application/msword",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/vnd.oasis.opendocument.text"
+  ],
+  spreadsheet: [
+    "application/vnd.ms-excel",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.oasis.opendocument.spreadsheet"
+  ],
+  archive: ["application/zip"]
+};
+function mimeTypesFor(accept) {
+  return [...new Set(accept.flatMap((category) => FILE_CATEGORIES[category]))];
+}
+var DEFAULT_FILE_MAX_BYTES = 10 * 1024 * 1024;
+var fileMaxBytes = (field2) => field2.maxBytes ?? DEFAULT_FILE_MAX_BYTES;
+function build(kind, options, extra = {}) {
+  return { kind, ...extra, ...options, required: options?.required !== false };
+}
+var field = {
+  string: (options) => build("string", options),
+  text: (options) => build("text", options, { list: false, searchable: false }),
+  int: (options) => build("int", options),
+  float: (options) => build("float", options),
+  boolean: (options) => build("boolean", options),
+  date: (options) => build("date", options),
+  datetime: (options) => build("datetime", options),
+  enum: (values, options) => build("enum", options, { options: values }),
+  /** One of a list, picked from a dropdown. The same as `enum`. */
+  select: (values, options) => build("enum", options, { options: values, widget: "select" }),
+  /** One of a list, picked with radio buttons. Stored like `enum`. */
+  radio: (values, options) => build("enum", options, { options: values, widget: "radio" }),
+  /** Any number of a list, picked with checkboxes. Stored as a JSON array. */
+  multiselect: (values, options) => build("multiselect", options, { options: values, sortable: false }),
+  email: (options) => build("string", options, { format: "email" }),
+  url: (options) => build("string", options, { format: "url" }),
+  tel: (options) => build("string", options, { format: "tel" }),
+  domain: (options) => build("string", options, { format: "domain" }),
+  country: (options) => build("string", options, { format: "country" }),
+  color: (options) => build("string", options, { format: "color" }),
+  slug: (options) => build("string", options, { format: "slug" }),
+  file: (accept, options) => build("file", options, { accept, list: false, sortable: false }),
+  belongsTo: (target, options) => build("belongsTo", options, { target }),
+  hasMany: (target, options) => ({ kind: "hasMany", target, ...options, required: false })
+};
+
+// src/resource/naming.ts
+function words(value) {
+  return value.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).filter(Boolean).map((word) => word.toLowerCase());
+}
+var pascalCase = (value) => words(value).map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+var camelCase = (value) => {
+  const pascal = pascalCase(value);
+  return pascal ? pascal[0].toLowerCase() + pascal.slice(1) : pascal;
+};
+var snakeCase = (value) => words(value).join("_");
+var kebabCase = (value) => words(value).join("-");
+var humanize = (value) => {
+  const text = words(value).join(" ");
+  return text ? text[0].toUpperCase() + text.slice(1) : text;
+};
+var UNCOUNTABLE = /* @__PURE__ */ new Set(["equipment", "information", "rice", "money", "species", "series", "fish", "sheep", "data", "news"]);
+var IRREGULAR = { person: "people", man: "men", woman: "women", child: "children", mouse: "mice" };
+function pluralize(value) {
+  const match = /([A-Za-z]+)$/.exec(value);
+  if (!match) return value;
+  const word = match[1];
+  const lower = word.toLowerCase();
+  const head = value.slice(0, value.length - word.length);
+  const keepCase = (plural) => word[0] === word[0].toUpperCase() ? plural[0].toUpperCase() + plural.slice(1) : plural;
+  if (UNCOUNTABLE.has(lower)) return value;
+  if (IRREGULAR[lower]) return head + keepCase(IRREGULAR[lower]);
+  if (/[^aeiou]y$/i.test(word)) return head + word.slice(0, -1) + "ies";
+  if (/(s|x|z|ch|sh)$/i.test(word)) return head + word + "es";
+  return head + word + "s";
+}
+
+// src/resource/define.ts
+var RESERVED_FIELD_NAMES = ["id", "createdAt", "updatedAt"];
+var ResourceDefinitionError = class extends Error {
+  constructor(resource, message) {
+    super(`Resource "${resource}": ${message}`);
+    this.name = "ResourceDefinitionError";
+  }
+};
+var IDENTIFIER = /^[a-z][A-Za-z0-9]*$/;
+function defaultFieldLabel(key, field2) {
+  return humanize(field2.kind === "belongsTo" ? key.replace(/Id$/, "") : key);
+}
+function defineResource(config) {
+  const name = config.name;
+  const fail = (message) => {
+    throw new ResourceDefinitionError(name, message);
+  };
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(name) || pascalCase(name) !== name) fail('name must be PascalCase, e.g. "OrderItem".');
+  const entries = Object.entries(config.fields);
+  if (entries.length === 0) fail("define at least one field.");
+  const fields = {};
+  for (const [key, def] of entries) {
+    if (!IDENTIFIER.test(key)) fail(`field "${key}" must be camelCase (letters and digits, starting lowercase).`);
+    if (RESERVED_FIELD_NAMES.includes(key)) fail(`"${key}" is added automatically; don't declare it.`);
+    if (def.kind === "enum") {
+      if (def.options.length === 0) fail(`enum field "${key}" needs at least one option.`);
+      if (new Set(def.options).size !== def.options.length) fail(`enum field "${key}" has duplicate options.`);
+      if (def.default !== void 0 && !def.options.includes(def.default)) fail(`default of "${key}" isn't one of its options.`);
+    }
+    if (def.kind === "multiselect") {
+      if (def.options.length === 0) fail(`multiselect field "${key}" needs at least one option.`);
+      if (new Set(def.options).size !== def.options.length) fail(`multiselect field "${key}" has duplicate options.`);
+      if (def.default?.some((value) => !def.options.includes(value))) fail(`default of "${key}" includes a value that isn't one of its options.`);
+      if (def.minItems !== void 0 && def.maxItems !== void 0 && def.minItems > def.maxItems) fail(`"${key}": minItems is larger than maxItems.`);
+    }
+    if (def.kind === "string" && def.format && !STRING_FORMATS.includes(def.format)) {
+      fail(`field "${key}" has unknown format "${def.format}". Formats: ${STRING_FORMATS.join(", ")}.`);
+    }
+    if (def.kind === "belongsTo" && !key.endsWith("Id")) fail(`belongsTo field "${key}" must end in "Id", e.g. "${camelCase(def.target)}Id".`);
+    if ((def.kind === "belongsTo" || def.kind === "hasMany") && pascalCase(def.target) !== def.target) {
+      fail(`relation "${key}" must target a PascalCase resource name.`);
+    }
+    if (def.kind === "belongsTo" && def.onDelete === "set null" && def.required) {
+      fail(`"${key}" uses onDelete "set null" but is required; mark it required: false.`);
+    }
+    if (def.kind === "file" && def.accept.length === 0) fail(`file field "${key}" must accept at least one category.`);
+    fields[key] = { ...def, label: def.label ?? defaultFieldLabel(key, def) };
+  }
+  const stored = entries.filter(([, def]) => def.kind !== "hasMany");
+  const titleField = config.titleField ?? stored.find(([, def]) => def.kind === "string" && !["tel", "country", "color"].includes(def.format ?? ""))?.[0] ?? stored.find(([, def]) => def.kind === "string")?.[0] ?? stored[0]?.[0] ?? "id";
+  if (config.titleField && !stored.some(([key]) => key === config.titleField)) {
+    fail(`titleField "${config.titleField}" isn't a stored field.`);
+  }
+  const defaultSort = config.defaultSort ?? { field: "createdAt", direction: "desc" };
+  if (!["createdAt", "updatedAt"].includes(defaultSort.field) && !stored.some(([key]) => key === defaultSort.field)) {
+    fail(`defaultSort field "${defaultSort.field}" isn't a stored field.`);
+  }
+  const perPage = config.perPage ?? 25;
+  if (!Number.isInteger(perPage) || perPage < 1 || perPage > 100) fail("perPage must be an integer from 1 to 100.");
+  const pluralName = pluralize(name);
+  return {
+    name,
+    table: config.table ?? snakeCase(pluralName),
+    slug: config.slug ?? kebabCase(pluralName),
+    label: config.label ?? humanize(name),
+    pluralLabel: config.pluralLabel ?? humanize(pluralName),
+    icon: config.icon,
+    titleField,
+    defaultSort,
+    perPage,
+    fields,
+    $types: void 0
+  };
+}
+function storedFields(resource) {
+  return Object.entries(resource.fields).filter(([, def]) => def.kind !== "hasMany");
+}
+var columnName = (key) => snakeCase(key);
+
+// src/resource/formats.ts
+import {
+  getCountries,
+  getCountryCallingCode,
+  isValidPhoneNumber,
+  parsePhoneNumberFromString
+} from "libphonenumber-js/min";
+function flagEmoji(code) {
+  const upper = code.toUpperCase();
+  if (!/^[A-Z]{2}$/.test(upper)) return "";
+  return String.fromCodePoint(...[...upper].map((letter) => 127462 + letter.charCodeAt(0) - 65));
+}
+var namesCache = /* @__PURE__ */ new Map();
+function displayNames(locale) {
+  if (!namesCache.has(locale)) {
+    try {
+      namesCache.set(locale, new Intl.DisplayNames([locale, "en"], { type: "region" }));
+    } catch {
+      namesCache.set(locale, null);
+    }
+  }
+  return namesCache.get(locale);
+}
+function countryName(code, locale = "en") {
+  const upper = code.toUpperCase();
+  try {
+    return displayNames(locale)?.of(upper) ?? upper;
+  } catch {
+    return upper;
+  }
+}
+var listCache = /* @__PURE__ */ new Map();
+function countries(locale = "en") {
+  let list = listCache.get(locale);
+  if (!list) {
+    list = getCountries().map((code) => ({ code, name: countryName(code, locale), dialCode: getCountryCallingCode(code), flag: flagEmoji(code) })).filter((country) => country.name !== country.code).sort((a, b) => a.name.localeCompare(b.name, locale));
+    listCache.set(locale, list);
+  }
+  return list;
+}
+function isCountryCode(value) {
+  return getCountries().includes(value.toUpperCase());
+}
+function isPhoneNumber(value) {
+  return value.startsWith("+") && isValidPhoneNumber(value);
+}
+function formatPhone(value) {
+  return parsePhoneNumberFromString(value)?.formatInternational() ?? value;
+}
+function splitPhone(value) {
+  const parsed = value ? parsePhoneNumberFromString(value) : void 0;
+  if (!parsed) return { country: void 0, national: value.replace(/^\+/, "") };
+  return { country: parsed.country, national: parsed.nationalNumber };
+}
+function toE164(country, national) {
+  const digits = national.replace(/[^\d+]/g, "");
+  if (!digits) return "";
+  if (digits.startsWith("+")) return parsePhoneNumberFromString(digits)?.number ?? digits;
+  const parsed = parsePhoneNumberFromString(digits, country.toUpperCase());
+  return parsed?.number ?? `+${getCountryCallingCode(country.toUpperCase())}${digits.replace(/^0+/, "")}`;
+}
+var DOMAIN = /^(?=.{1,253}$)(?:(?!-)[a-z0-9-]{1,63}(?<!-)\.)+[a-z][a-z0-9-]{0,62}[a-z0-9]$/;
+function normalizeDomain(value) {
+  return value.trim().toLowerCase().replace(/^[a-z]+:\/\//, "").replace(/[/?#].*$/, "").replace(/\.$/, "");
+}
+var isDomain = (value) => DOMAIN.test(value);
+var isColor = (value) => /^#[0-9a-f]{6}$/i.test(value);
+var isSlug = (value) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+function slugify(value) {
+  return value.normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+// src/resource/validators.ts
+import { z } from "zod";
+var DEFAULT_STRING_MAX = 255;
+var DEFAULT_TEXT_MAX = 65535;
+var OBJECT_KEY = /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$)).{1,1024}$/;
+var typeError = (message) => (issue) => issue.input === void 0 || issue.input === null || issue.input === "" ? "Required" : message;
+function stringSchema(max, min, required) {
+  let s = z.string({ error: typeError("Enter text") });
+  if (max) s = s.max(max, `At most ${max} characters`);
+  if (min !== void 0) s = s.min(min, min === 1 ? "Required" : `At least ${min} characters`);
+  else if (required) s = s.min(1, "Required");
+  return s;
+}
+function fieldSchema(def) {
+  switch (def.kind) {
+    case "string": {
+      let s = z.string({ error: typeError("Enter text") }).trim().max(def.maxLength ?? DEFAULT_STRING_MAX, `At most ${def.maxLength ?? DEFAULT_STRING_MAX} characters`);
+      if (def.minLength !== void 0) s = s.min(def.minLength, `At least ${def.minLength} characters`);
+      else if (def.required) s = s.min(1, "Required");
+      if (def.pattern) s = s.regex(new RegExp(def.pattern), "Invalid format");
+      switch (def.format) {
+        case "email":
+          return s.pipe(z.email({ error: "Enter a valid email address" }));
+        case "url":
+          return s.pipe(z.url({ protocol: /^https?$/, error: "Enter a valid URL (http or https)" }));
+        case "tel":
+          return s.refine((value) => value === "" || isPhoneNumber(value), "Enter a valid phone number, including the country");
+        case "domain":
+          return s.transform(normalizeDomain).refine((value) => value === "" || isDomain(value), "Enter a domain such as example.com");
+        case "country":
+          return s.transform((value) => value.toUpperCase()).refine((value) => value === "" || isCountryCode(value), "Choose a country");
+        case "color":
+          return s.transform((value) => value.toLowerCase()).refine((value) => value === "" || isColor(value), "Enter a colour such as #f2541d");
+        case "slug":
+          return s.refine((value) => value === "" || isSlug(value), "Use lowercase letters, numbers and hyphens, e.g. my-first-post");
+        default:
+          return s;
+      }
+    }
+    case "text":
+      return stringSchema(def.maxLength ?? DEFAULT_TEXT_MAX, def.minLength, def.required);
+    case "int":
+    case "float": {
+      let s = z.number({ error: typeError("Enter a number") });
+      if (def.kind === "int") s = s.int("Enter a whole number");
+      if (def.min !== void 0) s = s.min(def.min, `Must be at least ${def.min}`);
+      if (def.max !== void 0) s = s.max(def.max, `Must be at most ${def.max}`);
+      return s;
+    }
+    case "boolean":
+      return z.boolean({ error: typeError("Choose yes or no") });
+    case "date":
+      return z.iso.date({ error: typeError("Enter a valid date") });
+    case "datetime":
+      return z.iso.datetime({ offset: true, error: typeError("Enter a valid date and time") });
+    case "enum":
+      return z.enum(def.options, { error: typeError("Choose one of the options") });
+    case "multiselect": {
+      let s = z.array(z.enum(def.options, { error: "Choose from the listed options" }), { error: typeError("Choose one or more options") }).refine((values) => new Set(values).size === values.length, "Each option can be picked once");
+      const min = def.minItems ?? (def.required ? 1 : 0);
+      if (min > 0) s = s.refine((values) => values.length >= min, min === 1 ? "Choose at least one" : `Choose at least ${min}`);
+      if (def.maxItems !== void 0) s = s.refine((values) => values.length <= def.maxItems, `Choose at most ${def.maxItems}`);
+      return s;
+    }
+    case "file":
+      return z.string({ error: typeError("Upload a file") }).regex(OBJECT_KEY, "Invalid file");
+    case "belongsTo":
+      return z.string({ error: typeError("Choose a record") }).min(1, "Required");
+  }
+}
+var fileKeyPrefix = (resource, fieldKey) => `${resource.table}/${fieldKey}/`;
+function createValidators(resource) {
+  const create = {};
+  const update = {};
+  for (const [key, def] of storedFields(resource)) {
+    let base = fieldSchema(def);
+    if (def.kind === "file") {
+      const prefix = fileKeyPrefix(resource, key);
+      base = base.refine(
+        (value2) => typeof value2 !== "string" || !OBJECT_KEY.test(value2) || value2.startsWith(prefix),
+        "This file wasn't uploaded for this field"
+      );
+    }
+    const value = def.required ? base : base.nullable();
+    update[key] = value.optional();
+    const hasDefault = "default" in def && def.default !== void 0;
+    create[key] = def.required && !hasDefault ? value : value.optional();
+  }
+  const unknownKeys = { error: (issue) => issue.code === "unrecognized_keys" ? `Unknown field(s): ${issue.keys?.join(", ")}` : void 0 };
+  return {
+    create: z.strictObject(create, unknownKeys),
+    update: z.strictObject(update, unknownKeys)
+  };
+}
+
+// src/resource/policy.ts
+var ROLE = /^(\*|[a-z][a-z0-9_-]{0,31})$/;
+var PolicyError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PolicyError";
+  }
+};
+function definePolicy(config) {
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(config.resource)) {
+    throw new PolicyError(`Policy resource "${config.resource}" must be a PascalCase resource name.`);
+  }
+  const clean = (action) => {
+    const roles = config[action] ?? [];
+    for (const role of roles) {
+      if (!ROLE.test(role)) throw new PolicyError(`Policy ${config.resource}.${action}: invalid role "${role}" (lowercase letters, digits, _ or -, or "*").`);
+    }
+    return [...new Set(roles)];
+  };
+  return { resource: config.resource, read: clean("read"), create: clean("create"), update: clean("update"), delete: clean("delete") };
+}
+function can(policy, role, action) {
+  if (!policy) return true;
+  const allowed = policy[action === "list" ? "read" : action];
+  if (allowed.includes("*")) return Boolean(role);
+  return Boolean(role) && allowed.includes(role);
+}
+function allowedActions(policy, role) {
+  return {
+    read: can(policy, role, "read"),
+    create: can(policy, role, "create"),
+    update: can(policy, role, "update"),
+    delete: can(policy, role, "delete")
+  };
+}
+
+export {
+  STRING_FORMATS,
+  FILE_CATEGORIES,
+  mimeTypesFor,
+  DEFAULT_FILE_MAX_BYTES,
+  fileMaxBytes,
+  field,
+  words,
+  pascalCase,
+  camelCase,
+  snakeCase,
+  kebabCase,
+  humanize,
+  pluralize,
+  RESERVED_FIELD_NAMES,
+  ResourceDefinitionError,
+  defaultFieldLabel,
+  defineResource,
+  storedFields,
+  columnName,
+  flagEmoji,
+  countryName,
+  countries,
+  isCountryCode,
+  isPhoneNumber,
+  formatPhone,
+  splitPhone,
+  toE164,
+  normalizeDomain,
+  isDomain,
+  isColor,
+  isSlug,
+  slugify,
+  fieldSchema,
+  fileKeyPrefix,
+  createValidators,
+  PolicyError,
+  definePolicy,
+  can,
+  allowedActions
+};

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as Field, C as CreateInput, U as UpdateInput, R as Resource, S as StoredField } from './define-D5CtCkOm.js';
-export { B as BelongsToField, a as BooleanField, D as DEFAULT_FILE_MAX_BYTES, b as DateField, c as DateTimeField, E as EnumField, d as FILE_CATEGORIES, e as FieldKind, f as FieldValue, g as FileCategory, h as FileField, i as FloatField, H as HasManyField, I as IntField, j as RESERVED_FIELD_NAMES, k as RecordOf, l as ResourceConfig, m as ResourceDefinitionError, n as StringField, T as TextField, o as columnName, p as defaultFieldLabel, q as defineResource, r as field, s as fileMaxBytes, t as mimeTypesFor, u as storedFields } from './define-D5CtCkOm.js';
+import { F as Field, C as CreateInput, U as UpdateInput, R as Resource, S as StoredField } from './policy-BqRg9RVM.js';
+export { B as BelongsToField, a as BooleanField, D as DEFAULT_FILE_MAX_BYTES, b as DateField, c as DateTimeField, E as EnumField, d as FILE_CATEGORIES, e as FieldKind, f as FieldValue, g as FileCategory, h as FileField, i as FloatField, H as HasManyField, I as IntField, M as MultiSelectField, P as Policy, j as PolicyAction, k as PolicyConfig, l as PolicyError, m as RESERVED_FIELD_NAMES, n as RecordOf, o as ResourceConfig, p as ResourceDefinitionError, q as STRING_FORMATS, r as StringField, s as StringFormat, T as TextField, t as allowedActions, u as can, v as columnName, w as defaultFieldLabel, x as definePolicy, y as defineResource, z as field, A as fileMaxBytes, G as mimeTypesFor, J as storedFields } from './policy-BqRg9RVM.js';
 import { z } from 'zod';
 
 /**
@@ -358,7 +358,8 @@ declare function formatValue(def: StoredField | {
 }, value: unknown, options?: FormatOptions): string;
 
 /**
- * Form state for a resource: strings for text-like inputs, booleans for toggles.
+ * Form state for a resource: strings for text-like inputs, booleans for toggles, and a
+ * JSON array string for multiselects.
  * These helpers convert between records, form state, and API input so every admin
  * form handles empty values, numbers, and defaults the same way.
  */
@@ -371,47 +372,108 @@ declare function initialFormValues(resource: Resource, record?: Record<string, u
  * empty required fields are left for validation to report as "Required".
  */
 declare function formValuesToInput(resource: Resource, values: FormValues, mode: "create" | "edit"): Record<string, unknown>;
+/** A multiselect's form state (a JSON array string) as the picked values. */
+declare function parseMultiValue(raw: string | boolean | undefined): string[];
 /** Field errors keyed by field name, from validation or API issues (first message wins). */
 declare function issuesByField(issues: {
     path: string | PropertyKey[];
     message: string;
 }[]): Record<string, string>;
 
+interface Country {
+    /** ISO 3166-1 alpha-2, e.g. "UG". */
+    code: string;
+    name: string;
+    /** International dialling code without "+", e.g. "256". */
+    dialCode: string;
+    flag: string;
+}
+/** 🇺🇬 from "UG": two regional-indicator letters. */
+declare function flagEmoji(code: string): string;
+declare function countryName(code: string, locale?: string): string;
+/** Every country with a dialling code, sorted by name in `locale`. */
+declare function countries(locale?: string): Country[];
+declare function isCountryCode(value: string): boolean;
+/** A valid international number, e.g. "+256772123456". */
+declare function isPhoneNumber(value: string): boolean;
+/** "+256 772 123456" for display; the value itself when it can't be parsed. */
+declare function formatPhone(value: string): string;
+/** The country and national part of a stored number, to fill the admin input. */
+declare function splitPhone(value: string): {
+    country: string | undefined;
+    national: string;
+};
+/** E.164 from a country and whatever the person typed, e.g. ("UG", "0772 123456") → "+256772123456". */
+declare function toE164(country: string, national: string): string;
+/** "https://Example.com/path" → "example.com": what someone pasted, as a bare hostname. */
+declare function normalizeDomain(value: string): string;
+declare const isDomain: (value: string) => boolean;
+declare const isColor: (value: string) => boolean;
+declare const isSlug: (value: string) => boolean;
+/** "My First Post!" → "my-first-post". */
+declare function slugify(value: string): string;
+
 /**
- * Resource-level policies: which roles may read, create, update, or delete a resource.
+ * Sample data for seeds. Small on purpose: a handful of word lists and a seeded
+ * random number generator, so a million rows cost nothing to produce and the same
+ * seed always gives the same data.
  *
- * Policies are plain data, like descriptors, so the API layer and the admin UI read the
- * same rules at runtime. Field-level rules and per-record ownership are deliberately out
- * of scope for v1.
+ *   const fake = createFake();
+ *   fake.fullName();  // "Amina Okello"
+ *   fake.email();     // "amina.okello4@example.com"
  */
-type PolicyAction = "list" | "read" | "create" | "update" | "delete";
-/** Roles allowed per action; `"*"` means any signed-in user. */
-interface Policy {
-    resource: string;
-    read: string[];
-    create: string[];
-    update: string[];
-    delete: string[];
-}
-interface PolicyConfig {
-    resource: string;
-    read?: string[];
-    create?: string[];
-    update?: string[];
-    delete?: string[];
+interface Fake {
+    /** Whole number in [min, max]. */
+    int(min: number, max: number): number;
+    /** Number in [min, max], rounded to `decimals` places (default 2). */
+    float(min: number, max: number, decimals?: number): number;
+    /** True with the given probability (default 0.5). */
+    bool(chance?: number): boolean;
+    pick<T>(items: readonly T[]): T;
+    /** Between `min` and `max` distinct items, in the order they appear. */
+    some<T>(items: readonly T[], min?: number, max?: number): T[];
+    firstName(): string;
+    lastName(): string;
+    fullName(): string;
+    /** A unique address: the counter keeps it unique however many rows are made. */
+    email(name?: string): string;
+    company(): string;
+    jobTitle(): string;
+    city(): string;
+    /** ISO 3166-1 alpha-2, e.g. "UG". */
+    country(): string;
+    /** E.164, e.g. "+256772431980". */
+    phone(): string;
+    domain(): string;
+    url(): string;
+    slug(text?: string): string;
+    color(): string;
+    words(count?: number): string;
+    sentence(): string;
+    paragraph(sentences?: number): string;
+    /** "YYYY-MM-DD" within the last `daysBack` days (default 365). */
+    date(daysBack?: number): string;
+    /** ISO timestamp within the last `daysBack` days (default 365). */
+    datetime(daysBack?: number): string;
+    /** Milliseconds since the epoch, within the last `daysBack` days. */
+    timestamp(daysBack?: number): number;
+    uuid(): string;
+    /**
+     * A ULID: a 26-character id that sorts by the time it was made. Rows seeded with
+     * these go in at the end of the primary key's index instead of all over it, which
+     * measured 4× quicker than random ids at a few hundred thousand rows.
+     */
+    id(): string;
+    /** How many values this generator has produced; unique per row. */
+    readonly count: number;
 }
-declare class PolicyError extends Error {
-    constructor(message: string);
-}
-declare function definePolicy(config: PolicyConfig): Policy;
 /**
- * Whether `role` may perform `action`. Without a policy any signed-in user is allowed
- * (callers must already have required a session); generate one with
- * `flare gen policy <Resource> --roles …` to restrict a resource.
+ * A generator of sample values. `seed` makes runs reproducible; leave it out for a
+ * different set every time.
  */
-declare function can(policy: Policy | undefined | null, role: string | null | undefined, action: PolicyAction): boolean;
-/** Actions `role` may perform, for hiding UI it can't use. */
-declare function allowedActions(policy: Policy | undefined | null, role: string | null | undefined): Record<Exclude<PolicyAction, "list">, boolean>;
+declare function createFake(seed?: number): Fake;
+/** A shared generator, for seeds that don't need their own. */
+declare const fake: Fake;
 
 /**
  * Seed files: `seeds/<name>.seed.ts`, run by `flare seed` against the local D1 database.
@@ -419,20 +481,32 @@ declare function allowedActions(policy: Policy | undefined | null, role: string
  *   import { defineSeed } from "@flaredev/core";
  *   import { contacts } from "@/db/schema";
  *
- *   export default defineSeed(async ({ db }) => {
+ *   export default defineSeed(async ({ db, insertMany, fake }) => {
  *     await db.insert(contacts).values([{ name: "Ada", email: "ada@example.com" }]);
+ *     await insertMany(contacts, 10_000, () => ({ name: fake.fullName(), email: fake.email() }));
  *   });
  */
+
+/**
+ * Insert many rows at once. `rows` is either the rows themselves or a function called
+ * once per row, which keeps a million rows out of memory. Far quicker than a Drizzle
+ * insert of the same size: the values go into the SQL rather than into D1's
+ * 100-parameter budget.
+ */
+type InsertMany = <T extends object>(table: unknown, count: number | readonly T[], build?: (index: number) => T) => Promise<number>;
 interface SeedContext {
     /** Drizzle client over the app's schema, bound to the local D1 database. */
     db: any;
     /** All local bindings and variables (D1, R2, .dev.vars). */
     env: Record<string, unknown>;
     log: (message: string) => void;
+    insertMany: InsertMany;
+    /** Sample values: names, emails, sentences, dates. */
+    fake: Fake;
 }
 type Seed = (context: SeedContext) => void | Promise<void>;
 declare function defineSeed(seed: Seed): Seed;
 
-declare const FLARE_VERSION = "0.1.2";
+declare const FLARE_VERSION = "0.3.0";
 
-export { type BelongsToRelation, CreateInput, FLARE_VERSION, Field, type FormValues, type FormatOptions, type HasManyRelation, type MailMessage, type MailResult, type Mailer, type MailerOptions, PBKDF2_ITERATIONS, type Policy, type PolicyAction, type PolicyConfig, PolicyError, type ReadUrlOptions, RelationError, type RelationGraph, Resource, type ResourceRelations, type ResourceValidators, SNIFF_BYTES, SUBSCRIPTION_STATUSES, type Seed, type SeedContext, type Storage, type StorageBucket, type StorageOptions, StoredField, type SubscriptionLike, type SubscriptionState, type SubscriptionStatus, type Tone, type TransactionalEmail, UpdateInput, type UploadUrlOptions, allowedActions, camelCase, can, checkoutPaid, createMailer, createObjectKey, createStorage, createValidators, currentPeriodEnd, definePolicy, defineSeed, fieldSchema, fileKeyPrefix, formValuesToInput, formatValue, grantsAccess, hashPassword, humanize, importSigningKey, initialFormValues, isLiveSubscription, issuesByField, kebabCase, matchesContentType, optionLabel, pascalCase, pluralize, randomLetters, relationGraph, renderTransactionalEmail, shouldApplySubscription, signToken, snakeCase, sniffMatches, statusTone, subscriptionPriceId, subscriptionState, toSubscriptionStatus, verifyPassword, verifyToken, words };
+export { type BelongsToRelation, type Country, CreateInput, FLARE_VERSION, type Fake, Field, type FormValues, type FormatOptions, type HasManyRelation, type InsertMany, type MailMessage, type MailResult, type Mailer, type MailerOptions, PBKDF2_ITERATIONS, type ReadUrlOptions, RelationError, type RelationGraph, Resource, type ResourceRelations, type ResourceValidators, SNIFF_BYTES, SUBSCRIPTION_STATUSES, type Seed, type SeedContext, type Storage, type StorageBucket, type StorageOptions, StoredField, type SubscriptionLike, type SubscriptionState, type SubscriptionStatus, type Tone, type TransactionalEmail, UpdateInput, type UploadUrlOptions, camelCase, checkoutPaid, countries, countryName, createFake, createMailer, createObjectKey, createStorage, createValidators, currentPeriodEnd, defineSeed, fake, fieldSchema, fileKeyPrefix, flagEmoji, formValuesToInput, formatPhone, formatValue, grantsAccess, hashPassword, humanize, importSigningKey, initialFormValues, isColor, isCountryCode, isDomain, isLiveSubscription, isPhoneNumber, isSlug, issuesByField, kebabCase, matchesContentType, normalizeDomain, optionLabel, parseMultiValue, pascalCase, pluralize, randomLetters, relationGraph, renderTransactionalEmail, shouldApplySubscription, signToken, slugify, snakeCase, sniffMatches, splitPhone, statusTone, subscriptionPriceId, subscriptionState, toE164, toSubscriptionStatus, verifyPassword, verifyToken, words };