@pilotiq/pilotiq 0.23.1 → 0.24.2

package/src/actions/importFactory.ts

@@ -1,243 +0,0 @@
-/**
- * Internals for the `Action.import` factory. Lives in its own module
- * to keep the cycle between `Action.ts` and the field types (Select /
- * FileUpload) honest — `Action.import` calls in here via dynamic import
- * inside the handler.
- */
-
-import type { ActionContext } from './Action.js'
-import { parseCsv } from '../io/csv.js'
-import type { Element } from '../schema/Element.js'
-import { FileUpload } from '../fields/FileUploadField.js'
-import { SelectField } from '../fields/SelectField.js'
-
-export type ImportFormat = 'csv' | 'json'
-
-export interface ImportSummary {
-  created:  number
-  updated:  number
-  skipped:  number
-  /** Per-row failure messages (non-empty `validate` returns + thrown
-   *  errors during create / update). 1-indexed for human-friendly
-   *  display in the success notification. */
-  errors:   Array<{ row: number; message: string }>
-}
-
-export interface ImportContext extends ActionContext {
-  rowIndex?: number
-}
-
-export interface ImportOptions {
-  /** CSV / JSON header → model attribute key. Default: identity (the
-   *  CSV header IS the model attribute). For JSON, this remaps the
-   *  parsed object keys 1:1. */
-  columns?: Record<string, string>
-  /** Output format. Default `'csv'`. JSON-format imports parse the
-   *  uploaded file as `JSON.parse(text)`; arrays import as-is, single
-   *  objects wrap into `[obj]`. */
-  format?: ImportFormat
-  /** Model attribute used as the upsert key. When set, the importer
-   *  looks up an existing record by `M.query().where(upsertBy, row[upsertBy])`
-   *  before deciding create vs update. When omitted, every row is a
-   *  create. */
-  upsertBy?: string
-  /** Per-row guard. Return a string to skip the row + accumulate as a
-   *  failure; return `null` (or `undefined`) to allow the row through.
-   *  Async-aware. */
-  validate?: (
-    row: Record<string, unknown>,
-    ctx: ImportContext,
-  ) => string | null | undefined | Promise<string | null | undefined>
-  /** Mutate the row payload before `M.create`. Async-aware. */
-  beforeCreate?: (
-    row: Record<string, unknown>,
-    ctx: ImportContext,
-  ) => Record<string, unknown> | Promise<Record<string, unknown>>
-  /** Mutate the row payload before `M.update`. Receives the existing
-   *  record so the hook can copy / preserve fields the import shouldn't
-   *  overwrite. Async-aware. */
-  beforeUpdate?: (
-    row: Record<string, unknown>,
-    existing: unknown,
-    ctx: ImportContext,
-  ) => Record<string, unknown> | Promise<Record<string, unknown>>
-  /** Hard cap on the row count. Aborts with an error notification when
-   *  exceeded — protects against accidental million-row uploads. Default
-   *  `10_000`. */
-  maxRows?: number
-  /** Number of rows to process in parallel. The importer chunks the row
-   *  list into batches of this size and runs each chunk via `Promise.all`.
-   *  Order within a chunk is non-deterministic; row indices in error
-   *  messages still match the original CSV/JSON position. Default `10`. */
-  concurrency?: number
-  /** Final hook after the import loop. Useful for audit-log writes,
-   *  cache invalidation, etc. Async-aware. */
-  onComplete?: (summary: ImportSummary, ctx: ImportContext) => void | Promise<void>
-}
-
-/**
- * Parse an uploaded file's text into an array of row objects keyed by
- * model attribute (after applying `opts.columns` remap for CSV).
- *
- * Throws on invalid CSV / JSON; the caller's outer `try` surfaces the
- * error message via the result notification.
- */
-export function parseImportText(
-  text:    string,
-  format:  ImportFormat,
-  columns?: Record<string, string>,
-): Array<Record<string, unknown>> {
-  if (format === 'json') {
-    const parsed = JSON.parse(text) as unknown
-    if (Array.isArray(parsed)) return parsed as Array<Record<string, unknown>>
-    if (parsed && typeof parsed === 'object') return [parsed as Record<string, unknown>]
-    throw new Error('JSON import expected an array or object')
-  }
-  const csv = parseCsv(text)
-  if (!columns || Object.keys(columns).length === 0) {
-    return csv.rows
-  }
-  // Remap CSV headers → model keys. CSV cells stay as strings; the ORM
-  // does any final coercion (or the user's `beforeCreate` hook).
-  return csv.rows.map(row => {
-    const out: Record<string, unknown> = {}
-    for (const [csvKey, value] of Object.entries(row)) {
-      const modelKey = columns[csvKey] ?? csvKey
-      out[modelKey] = value
-    }
-    return out
-  })
-}
-
-/**
- * Run the per-row import loop. Pulled out of the factory body so the
- * factory stays at the level of "compose modal + handler" instead of
- * "do the work".
- *
- * Returns the aggregated summary (counts + per-row error messages).
- * Failures don't roll back — partial-success is the contract. The
- * caller surfaces the summary via a notification.
- */
-export async function runImport(
-  rows: Array<Record<string, unknown>>,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  M:    any,
-  mode: 'create' | 'upsert',
-  opts: ImportOptions,
-  ctx:  ImportContext,
-): Promise<ImportSummary> {
-  const summary: ImportSummary = { created: 0, updated: 0, skipped: 0, errors: [] }
-  const upsertBy = opts.upsertBy
-  const concurrency = Math.max(1, opts.concurrency ?? 10)
-
-  // Per-row outcome — a small value type so chunks can resolve in any
-  // order and we still accumulate `summary` in original-row order.
-  type RowOutcome =
-    | { kind: 'created' }
-    | { kind: 'updated' }
-    | { kind: 'skipped'; row: number; message: string }
-
-  async function processRow(row: Record<string, unknown>, i: number): Promise<RowOutcome> {
-    const rowCtx: ImportContext = { ...ctx, rowIndex: i }
-    try {
-      const guard = await opts.validate?.(row, rowCtx)
-      if (typeof guard === 'string' && guard.length > 0) {
-        return { kind: 'skipped', row: i + 1, message: guard }
-      }
-
-      if (mode === 'upsert' && upsertBy) {
-        const slice = await M.query().where(upsertBy, row[upsertBy]).paginate(1, 1)
-        const existing = (slice?.data ?? [])[0]
-        if (existing) {
-          const id = String((existing as { id?: unknown }).id ?? '')
-          const payload = opts.beforeUpdate
-            ? await opts.beforeUpdate(row, existing, rowCtx)
-            : row
-          await M.update(id, payload)
-          return { kind: 'updated' }
-        }
-      }
-
-      const payload = opts.beforeCreate
-        ? await opts.beforeCreate(row, rowCtx)
-        : row
-      await M.create(payload)
-      return { kind: 'created' }
-    } catch (err) {
-      return { kind: 'skipped', row: i + 1, message: err instanceof Error ? err.message : 'unknown' }
-    }
-  }
-
-  for (let start = 0; start < rows.length; start += concurrency) {
-    const slice = rows.slice(start, start + concurrency)
-    const outcomes = await Promise.all(slice.map((row, idx) => processRow(row, start + idx)))
-    for (const outcome of outcomes) {
-      if (outcome.kind === 'created')      summary.created++
-      else if (outcome.kind === 'updated') summary.updated++
-      else {
-        summary.skipped++
-        summary.errors.push({ row: outcome.row, message: outcome.message })
-      }
-    }
-  }
-
-  await opts.onComplete?.(summary, ctx)
-  return summary
-}
-
-/** Build the modal-form schema for an import action. v1 ships:
- *
- *  - `FileUpload.make('file')` — required, capped at 10 MB, accepts
- *    `.csv,.json` by default; users can override the field via the
- *    `Action.schema([...])` chain.
- *  - When `upsertBy` is set, a `Select.make('mode')` toggles between
- *    "Create only" and "Create or update" with `'upsert'` as the
- *    default selection.
- *
- *  Returns an `Element[]` the factory drops into `Action.schema(...)`
- *  to drive the auto-built modal form. */
-export function buildImportSchema(opts: ImportOptions): Element[] {
-  const elements: Element[] = []
-
-  const file = FileUpload.make('file')
-    .label('File')
-    .accept(['.csv', '.json', 'text/csv', 'application/json'])
-    .maxSize(10_000_000)
-    .required()
-  elements.push(file as unknown as Element)
-
-  if (typeof opts.upsertBy === 'string' && opts.upsertBy.length > 0) {
-    const mode = SelectField.make('mode')
-      .label('Mode')
-      .options([
-        { value: 'create', label: 'Create only' },
-        { value: 'upsert', label: 'Create or update' },
-      ])
-      .default('upsert')
-    elements.push(mode as unknown as Element)
-  }
-
-  return elements
-}
-
-/** Build a one-line success / warning notification body for the
- *  import summary — surfaces the first 5 row failures inline so users
- *  see what went wrong without hunting through logs. */
-export function buildImportNotification(summary: ImportSummary, opts: { upsert: boolean }): {
-  type:  'success' | 'warning' | 'error'
-  title: string
-  body?: string
-} {
-  const total = summary.created + summary.updated + summary.skipped
-  if (total === 0) {
-    return { type: 'warning', title: 'Import complete — no rows processed' }
-  }
-  const parts: string[] = [`${summary.created} created`]
-  if (opts.upsert) parts.push(`${summary.updated} updated`)
-  if (summary.skipped > 0) parts.push(`${summary.skipped} skipped`)
-  const title = `Import complete — ${parts.join(', ')}`
-  const type: 'success' | 'warning' = summary.errors.length > 0 ? 'warning' : 'success'
-  if (summary.errors.length === 0) return { type, title }
-  const body = summary.errors.slice(0, 5).map(e => `Row ${e.row}: ${e.message}`).join('\n')
-  return { type, title, body }
-}

package/src/actions/index.ts

@@ -1,17 +0,0 @@
-export {
-  Action,
-  type ActionPlacement,
-  type ActionContext,
-  type ActionHandler,
-  type ActionConfirm,
-  type ActionMeta,
-  type ActionColor,
-  type ActionSize,
-  type ActionVisibilityContext,
-  type VisibilityRule,
-} from './Action.js'
-
-export {
-  ActionGroup,
-  type ActionGroupMeta,
-} from './ActionGroup.js'

package/src/actions/m2mFactories.ts

@@ -1,193 +0,0 @@
-/**
- * M2M relation Action factories — `relationAttach` (header, modal-form
- * picker → POST `_action/relationAttach`), `relationDetach` (row, direct
- * POST to `_detach/:childId`), `relationBulkDetach` (bulk, handler-
- * dispatched).
- *
- * Sibling of `relationCreate / Edit / Delete` for every M2M mode
- * (`belongsToMany`, `morphToMany` (owning polymorphic side),
- * `morphedByMany` (inverse polymorphic side)). All three modes share
- * the same `attach` / `detach` / `sync` accessor surface — the rudder
- * ORM stamps + filters the polymorphic discriminator on the morph
- * variants automatically, so pilotiq's pivot factories are mode-agnostic
- * beyond the visibility gate.
- *
- * All three auto-hide outside any M2M mode so dropping a factory into
- * a non-M2M manager is a no-op (visible=false) instead of a confusing
- * 404.
- *
- * The first and third route through the manager-scoped
- * `_action/:actionName` endpoint (added in routes.ts) so handlers
- * see `ctx.relation = { parent, parentId, relationship }`.
- *
- * See `docs/plans/action-split.md` for the split plan.
- */
-
-import { Action, type ActionResult } from './Action.js'
-import {
-  safeManagerPolicy,
-  type RelationManager,
-  type RelationManagerContext,
-} from '../RelationManager.js'
-import { resolveM2MAccessor } from '../orm/m2mAccessor.js'
-import { buildAttachModalSchema } from './attachFactory.js'
-import { isM2MMode, relationUrlPrefix } from './factoryHelpers.js'
-
-/** Resolve the M2M accessor on `rel.parent`, null-check the requested
- *  method, run it, and shape the per-failure-mode error envelope.
- *  Used by `relationAttachAction` and `relationBulkDetachAction` —
- *  both follow the same pattern (resolve → null-check method →
- *  try/catch). Keeps the "Pivot accessor missing on …" error string
- *  consistent across both call sites. */
-async function callM2MAccessor(
-  rel:         { parent: unknown; relationship: string },
-  method:      'attach' | 'detach',
-  ids:         string[],
-  failureLabel: string,
-): Promise<{ ok: true } | { ok: false; result: ActionResult }> {
-  const accessor = resolveM2MAccessor(rel.parent, rel.relationship) as
-    | { attach?: (ids: string[]) => Promise<unknown>; detach?: (ids: string[]) => Promise<unknown> }
-    | null
-  const fn = accessor?.[method]
-  if (typeof fn !== 'function') {
-    return {
-      ok:     false,
-      result: { notify: { title: `Pivot accessor missing on ${rel.relationship} — wrong relation type or ORM version?`, type: 'error' } as never },
-    }
-  }
-  try {
-    await fn(ids)
-    return { ok: true }
-  } catch (err) {
-    return {
-      ok:     false,
-      result: { notify: { title: `${failureLabel}: ${err instanceof Error ? err.message : String(err)}`, type: 'error' } as never },
-    }
-  }
-}
-
-/** Header-placement attach factory — opens a modal with a SelectField
- *  listing related records that aren't already attached, and POSTs the
- *  selected id to the manager's `_action/relationAttach` endpoint.
- *
- *  Visibility delegates to `M.canAttach(user, parentRecord)` AND
- *  guards against being dropped into a non-M2M manager. */
-export function relationAttachAction(
-  M:   typeof RelationManager,
-  ctx: RelationManagerContext,
-): Action {
-  const labelSingular = M.getLabelSingular()
-  const a = Action.make('relationAttach')
-    .label(`Attach ${labelSingular}`)
-    .header()
-    .modalHeading(`Attach ${labelSingular}`)
-    .modalSubmitLabel('Attach')
-    .modalCancelLabel('Cancel')
-    .handler(async (hctx) => {
-      const rel = hctx.relation
-      if (!rel) {
-        return { notify: { title: 'Attach handler missing parent context — manager-scoped _action route not wired', type: 'error' } as never }
-      }
-      const Related = ctx.related
-      if (!Related?.model) {
-        return { notify: { title: 'Cannot attach: related Resource has no model', type: 'error' } as never }
-      }
-      const idStr = String((hctx.values?.['_attachId'] as unknown) ?? '')
-      if (idStr.length === 0) {
-        return { notify: { title: 'Pick a record to attach', type: 'error' } as never }
-      }
-      const call = await callM2MAccessor(rel, 'attach', [idStr], 'Attach failed')
-      if (!call.ok) return call.result
-      return { notify: { title: `${labelSingular} attached`, type: 'success' } as never }
-    })
-    .visible(({ user }) => {
-      if (!isM2MMode(ctx.mode)) return false
-      return safeManagerPolicy(M, 'canAttach', ctx.related, user, ctx.parentRecord)
-    })
-
-  // Build the modal-form schema only when this is actually an M2M
-  // manager — non-M2M drops keep the action hidden via the visibility
-  // predicate, but still need a schema-less Action so the meta walker
-  // doesn't blow up. Static import is fine: `attachFactory` only
-  // depends on `SelectField` + ORM helpers, no cycle back to Action.
-  if (isM2MMode(ctx.mode) && ctx.related?.model) {
-    a.schema(buildAttachModalSchema({
-      Related:         ctx.related,
-      relationship:    ctx.relationship,
-      recordTitleAttr: M.getRecordTitleAttribute() ?? ctx.related.recordTitleAttribute,
-      labelSingular,
-    }))
-  }
-  return a
-}
-
-/** Row-placement detach factory — POSTs to
- *  `${base}/${parentSlug}/${parentId}/${relationship}/${recordId ?? ':id'}/_detach`,
- *  destructive style with a confirmation prompt that says "Detach"
- *  (not "Delete") so users understand the target record stays.
- *  Visibility delegates to `M.canDetach`. */
-export function relationDetachAction(
-  M:        typeof RelationManager,
-  ctx:      RelationManagerContext,
-  recordId?: string,
-): Action {
-  const id = recordId ?? ':id'
-  const singular = M.getLabelSingular().toLowerCase()
-  return Action.make('relationDetach')
-    .label('Detach')
-    .destructive()
-    .method('post')
-    .action(`${relationUrlPrefix(ctx)}/${id}/_detach`)
-    .confirm(`Detach this ${singular}? The ${singular} record stays in place; only the link is removed.`)
-    .visible(async ({ user, record }) => {
-      if (!isM2MMode(ctx.mode)) return false
-      return safeManagerPolicy(M, 'canDetach', ctx.related, user, ctx.parentRecord, record)
-    })
-}
-
-/** Bulk-placement bulk-detach factory — handler-dispatched. Calls
- *  `parent.related(rel).detach(ids)` for the selected rows. Visibility
- *  delegates to `M.canAttach` (acts like a "manager admin" gate; we
- *  intentionally don't enforce per-row `canDetach` on the visibility
- *  side because the bulk button needs to be visible before the user
- *  has selected anything — per-row gating happens inside the handler). */
-export function relationBulkDetachAction(
-  M:   typeof RelationManager,
-  ctx: RelationManagerContext,
-): Action {
-  const labelPlural = M.getLabel().toLowerCase()
-  return Action.make('relationBulkDetach')
-    .label('Detach selected')
-    .destructive()
-    .bulk()
-    .confirm(`Detach the selected ${labelPlural}? The records stay in place; only the links are removed.`)
-    .handler(async (hctx) => {
-      const rel = hctx.relation
-      if (!rel) {
-        return { notify: { title: 'Bulk-detach handler missing parent context — manager-scoped _action route not wired', type: 'error' } as never }
-      }
-      const records = hctx.records ?? []
-      // Parallelize the per-row policy probes; the accessor call itself stays a single batched op.
-      const allowedFlags = await Promise.all(
-        records.map(r => safeManagerPolicy(M, 'canDetach', ctx.related, hctx.user, ctx.parentRecord, r)),
-      )
-      const ids: string[] = []
-      for (let i = 0; i < records.length; i++) {
-        if (!allowedFlags[i]) continue
-        const id = String((records[i] as { id?: unknown }).id ?? '')
-        if (id) ids.push(id)
-      }
-      if (ids.length === 0) {
-        return { notify: { title: 'Nothing to detach (no permitted rows)', type: 'warning' } as never }
-      }
-      const call = await callM2MAccessor(rel, 'detach', ids, 'Bulk detach failed')
-      if (!call.ok) return call.result
-      return { notify: { title: `${ids.length} ${labelPlural} detached`, type: 'success' } as never }
-    })
-    .visible(({ user }) => {
-      if (!isM2MMode(ctx.mode)) return false
-      // Bulk gate uses canAttach as a stand-in for "manager admin" —
-      // per-row canDetach is enforced inside the handler.
-      return safeManagerPolicy(M, 'canAttach', ctx.related, user, ctx.parentRecord)
-    })
-}