@pilotiq/pilotiq 0.24.1 → 0.24.2

package/src/Page.ts

@@ -1,208 +0,0 @@
-import type { Element } from './schema/Element.js'
-import type { SchemaContext, SchemaDefinition } from './schema/resolveSchema.js'
-import type { ResourceClass, NavigationBadgeColor, NavigationBadgeHandler } from './Resource.js'
-import type { ClusterClass } from './Cluster.js'
-import { type IconValue, serializeIcon } from './icons/types.js'
-
-/**
- * Per-custom-page collab configuration. Custom pages have no record id
- * to derive a room from, so `room` is required and must be supplied as
- * a literal string (e.g. `'team-settings'`). The plugin reads this off
- * the panel-level `pageCollab` map and uses it to seed the page's
- * Y.Doc.
- *
- *   room     — literal room identifier; namespaced internally so two
- *              pages with the same `room` literal collide deliberately.
- *   presence — when false, suppress the awareness layer (focus chips,
- *              cursor positions) while keeping value-sync. Defaults to true.
- *
- * Field-level `.collab(false)` always wins per field. Resource-bound
- * default pages (List/Create/Edit/View) ignore this — record-scoped
- * collab is governed by `Resource.collab`.
- */
-export interface PageCollabConfig {
-  room:     string
-  presence: boolean
-}
-
-/** Raw shape accepted by `static collab` before normalization. Unlike
- * `Resource.collab` there is no `true` shorthand — `room` is required. */
-export type PageCollabInput = {
-  room:      string
-  presence?: boolean
-}
-
-/**
- * Discriminator the framework uses for default rendering, route generation,
- * and breadcrumbs. `'custom'` is for standalone Pages that don't belong to
- * a Resource. `'record'` is for record-scoped sub-pages declared under a
- * Resource's `pages().record` map. The other four modes correspond to the
- * standard resource page roles.
- */
-export type PageMode = 'list' | 'create' | 'edit' | 'view' | 'record' | 'custom'
-
-export interface PageMeta {
-  slug:  string
-  label: string
-  /** Serialized: string registry key, `{ class }` manifest reference, or undefined. */
-  icon:  string | { class: string } | undefined
-  mode:  PageMode
-}
-
-export class Page {
-  /** URL slug (e.g. 'analytics'). Derived from class name if not set. */
-  static slug?: string
-
-  /** Sidebar label (e.g. 'Analytics'). Derived from class name if not set. */
-  static label?: string
-
-  /** Optional sidebar icon. Either a kebab-case name resolved through
-   * `registerIcons()` (e.g., `'newspaper'`), or a React component
-   * reference (e.g., `import { Newspaper } from 'lucide-react'`).
-   * Component refs serialize via the build-time `_components.ts`
-   * manifest emitted by the Pilotiq Vite plugin. */
-  static icon?: IconValue
-
-  // ─── Plan #9: navigation metadata ──────────────────────────
-  // Mirrors Resource's nav fields (minus `recordTitleAttribute`).
-  static navigationGroup:       string | undefined = undefined
-  static navigationSort:        number | undefined = undefined
-  static navigationLabel:       string | undefined = undefined
-  static navigationIcon:        IconValue          = undefined
-  static navigationBadge:       NavigationBadgeHandler | undefined = undefined
-  static navigationBadgeColor:  NavigationBadgeColor = 'default'
-  static navigationParentItem:  string | undefined = undefined
-
-  /**
-   * Cluster this page belongs to. When set, the page's URL gains the
-   * cluster's slug as a prefix segment and the page nests under the
-   * cluster's nav entry. The referenced class must be registered via
-   * `Pilotiq.clusters([…])`.
-   */
-  static cluster?: ClusterClass
-
-  /** Stored schema definition. */
-  protected static _schemaDef?: SchemaDefinition
-
-  /**
-   * Define the page content using a stored schema definition.
-   *
-   * @example
-   * static {
-   *   this.define(async (ctx) => [
-   *     Heading.make('Analytics'),
-   *   ])
-   * }
-   */
-  static define(def: SchemaDefinition): typeof Page {
-    this._schemaDef = def
-    return this
-  }
-
-  /**
-   * Return the page's schema elements.
-   * Override this method for full control, or use define() for inline definitions.
-   */
-  static schema(_ctx?: SchemaContext): Element[] | Promise<Element[]> {
-    if (!this._schemaDef) return []
-    return typeof this._schemaDef === 'function'
-      ? this._schemaDef(_ctx ?? {})
-      : this._schemaDef
-  }
-
-  static getSlug(): string {
-    if (this.slug) return this.slug
-    return this.name.replace(/Page$/, '').toLowerCase()
-  }
-
-  static getLabel(): string {
-    if (this.label) return this.label
-    const name = this.name.replace(/Page$/, '')
-    return name.replace(/([A-Z])/g, ' $1').trim()
-  }
-
-  /** Sidebar label: `navigationLabel` override falls through to `getLabel()`. */
-  static getNavigationLabel(): string {
-    return this.navigationLabel ?? this.getLabel()
-  }
-
-  /** Sidebar icon: `navigationIcon` override falls through to `icon`. */
-  static getNavigationIcon(): IconValue {
-    return this.navigationIcon ?? this.icon
-  }
-
-  static hasSchema(): boolean {
-    return this._schemaDef !== undefined || this.schema !== Page.schema
-  }
-
-  // ─── Realtime collab opt-in ────────────────────────────────
-  // Per-page opt-in for custom Pages. Resource-bound default pages
-  // (List/Create/Edit/View) ignore this — record-scoped collab is
-  // governed by `Resource.collab`. Set on a custom Page subclass to
-  // mount the plugin-registered custom-page wrapper around its content
-  // area at runtime.
-
-  /** Enable collab on this custom page. `room` is required (no recordId
-   * to derive one from). Omitting `static collab` keeps the page
-   * collab-free even when the `@pilotiq-pro/collab` plugin is installed. */
-  static collab: PageCollabInput | null = null
-
-  /**
-   * Normalize `static collab` into the canonical wire shape, or return
-   * `null` when the page has not opted in. Centralizes the `presence`
-   * default. Resource-bound default pages always return `null` here —
-   * use `Resource.collab` for those.
-   *
-   * Result lands on `panelInfo().pageCollab[slug]`; the gate reads it to
-   * decide whether to mount the custom-page wrapper.
-   */
-  static getResolvedCollabConfig(): PageCollabConfig | null {
-    if (this.getMode() !== 'custom') return null
-    const raw = this.collab
-    if (raw === null || raw === undefined) return null
-    if (typeof raw.room !== 'string' || raw.room.length === 0) return null
-    return {
-      room:     raw.room,
-      presence: raw.presence ?? true,
-    }
-  }
-
-  /** Plan #10: authorization. Custom pages get a single `canAccess` gate
-   * (no per-record predicates — pages are too freeform to assume a
-   * record concept). Resource-bound default page subclasses can still
-   * read their owning resource's predicates via `getResource()`.
-   *
-   * Record sub-pages (declared under `ResourcePages.record`) receive
-   * the loaded parent record as the second argument so subclasses can
-   * gate on record state in addition to user. The parameter is
-   * optional so existing custom-page subclasses with `canAccess(user)`
-   * keep type-checking. Record-aware sub-pages typically override as
-   * `canAccess(user, record)`. */
-  static async canAccess(_user: unknown, _record?: unknown): Promise<boolean> { return true }
-
-  /**
-   * Optional back-reference to the owning Resource. Auto-generated default
-   * pages set this; user subclasses may override for breadcrumb / title
-   * resolution. Standalone custom pages return undefined.
-   */
-  static getResource(): ResourceClass | undefined { return undefined }
-
-  /**
-   * Mode discriminator. Default `'custom'` (standalone page). Resource-bound
-   * pages override to one of `'list' | 'create' | 'edit' | 'view'`.
-   */
-  static getMode(): PageMode { return 'custom' }
-
-  /** @internal */
-  static toMeta(): PageMeta {
-    // Serialize via the icon-system helper so component-typed icons
-    // ship as `{ class: <name> }` rather than the raw forwardRef
-    // object — viewProps must be JSON-serializable.
-    return {
-      slug:  this.getSlug(),
-      label: this.getLabel(),
-      icon:  serializeIcon(this.icon, this.name),
-      mode:  this.getMode(),
-    }
-  }
-}

package/src/Pilotiq.perf.test.ts

@@ -1,252 +0,0 @@
-/**
- * Phase 5 perf sweep — covers the four hot-path changes that landed
- * 2026-05-22:
- *
- *  - 5b Per-user navigation-badge TTL cache (`Pilotiq.navigationBadgeTtl`)
- *  - 5c Map-based slug lookup (`Pilotiq.findResource/findGlobal/findPage`)
- *  - 5a Chunked import (`importFactory.runImport` honors `concurrency`)
- *
- *  5d (`policyGate`) is exercised indirectly by the existing routes /
- *  authorization tests — its contract is identical to the prior
- *  serial pair, just parallelized; no behavior change to assert here.
- */
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Pilotiq } from './Pilotiq.js'
-import { Resource } from './Resource.js'
-import { Global } from './Global.js'
-import { Page } from './Page.js'
-import { runImport } from './actions/importFactory.js'
-
-// ─── Fixtures ─────────────────────────────────────────────────
-
-class Articles extends Resource {
-  static override slug = 'articles'
-  static override label = 'Articles'
-}
-class Comments extends Resource {
-  static override slug = 'comments'
-  static override label = 'Comments'
-}
-class Settings extends Global {
-  static override slug = 'settings'
-  static override label = 'Settings'
-}
-class Branding extends Global {
-  static override slug = 'branding'
-  static override label = 'Branding'
-}
-class Reports extends Page {
-  static override slug = 'reports'
-  static override label = 'Reports'
-}
-class Health extends Page {
-  static override slug = 'health'
-  static override label = 'Health'
-}
-
-// ─── 5c — Map-based slug lookup ───────────────────────────────
-
-describe('Pilotiq.find{Resource,Global,Page}() — Plan 5c', () => {
-  it('returns the matching class by slug', () => {
-    const p = Pilotiq.make('admin')
-      .resources([Articles, Comments])
-      .globals([Settings, Branding])
-      .pages([Reports, Health])
-    assert.equal(p.findResource('articles'), Articles)
-    assert.equal(p.findResource('comments'), Comments)
-    assert.equal(p.findGlobal('settings'),   Settings)
-    assert.equal(p.findGlobal('branding'),   Branding)
-    assert.equal(p.findPage('reports'),      Reports)
-    assert.equal(p.findPage('health'),       Health)
-  })
-
-  it('returns undefined for unknown slugs', () => {
-    const p = Pilotiq.make('admin').resources([Articles])
-    assert.equal(p.findResource('nope'), undefined)
-    assert.equal(p.findGlobal('nope'),   undefined)
-    assert.equal(p.findPage('nope'),     undefined)
-  })
-
-  it('invalidates the cache when .resources() is reassigned', () => {
-    const p = Pilotiq.make('admin').resources([Articles])
-    assert.equal(p.findResource('articles'), Articles)
-    assert.equal(p.findResource('comments'), undefined)
-    p.resources([Articles, Comments])
-    assert.equal(p.findResource('comments'), Comments)
-  })
-
-  it('invalidates the page cache when .pages() is reassigned', () => {
-    const p = Pilotiq.make('admin').pages([Reports])
-    assert.equal(p.findPage('reports'), Reports)
-    assert.equal(p.findPage('health'),  undefined)
-    p.pages([Reports, Health])
-    assert.equal(p.findPage('health'), Health)
-  })
-
-  it('invalidates the page cache when .dashboard()/.profile() auto-append', () => {
-    class Dash extends Page {
-      static override slug = 'dash'
-      static override label = 'Dashboard'
-    }
-    const p = Pilotiq.make('admin')
-    assert.equal(p.findPage('dash'), undefined)
-    p.dashboard(Dash)
-    assert.equal(p.findPage('dash'), Dash)
-  })
-})
-
-// ─── 5b — Navigation badge TTL cache ──────────────────────────
-
-describe('Pilotiq.navigationBadgeTtl() + resolveNavigationBadge() — Plan 5b', () => {
-  it('default TTL is 30s', () => {
-    const p = Pilotiq.make('admin')
-    assert.equal(p.getNavigationBadgeTtl(), 30_000)
-  })
-
-  it('navigationBadgeTtl(ms) overrides; clamps negatives to 0', () => {
-    const p = Pilotiq.make('admin').navigationBadgeTtl(5_000)
-    assert.equal(p.getNavigationBadgeTtl(), 5_000)
-    p.navigationBadgeTtl(-1)
-    assert.equal(p.getNavigationBadgeTtl(), 0)
-  })
-
-  it('navigationBadgeTtl(null) restores the default', () => {
-    const p = Pilotiq.make('admin').navigationBadgeTtl(1_000)
-    p.navigationBadgeTtl(null)
-    assert.equal(p.getNavigationBadgeTtl(), 30_000)
-  })
-
-  it('resolveNavigationBadge caches within TTL, busts on user change', async () => {
-    const p = Pilotiq.make('admin')
-    let calls = 0
-    const resolver = async () => { calls++; return String(calls) }
-
-    // First call: miss → resolver fires → returns '1'.
-    assert.equal(await p.resolveNavigationBadge('Articles', { id: 1 }, resolver), '1')
-    assert.equal(calls, 1)
-    // Same user + owner: hit → no new call → still '1'.
-    assert.equal(await p.resolveNavigationBadge('Articles', { id: 1 }, resolver), '1')
-    assert.equal(calls, 1)
-    // Different user: miss → resolver fires again.
-    assert.equal(await p.resolveNavigationBadge('Articles', { id: 2 }, resolver), '2')
-    assert.equal(calls, 2)
-    // Different owner, same user: separate cache slot.
-    assert.equal(await p.resolveNavigationBadge('Comments', { id: 1 }, resolver), '3')
-    assert.equal(calls, 3)
-  })
-
-  it('TTL of 0 disables caching entirely', async () => {
-    const p = Pilotiq.make('admin').navigationBadgeTtl(0)
-    let calls = 0
-    const resolver = async () => { calls++; return 'x' }
-    await p.resolveNavigationBadge('Articles', { id: 1 }, resolver)
-    await p.resolveNavigationBadge('Articles', { id: 1 }, resolver)
-    assert.equal(calls, 2)
-  })
-
-  it('caches undefined results (no need to keep re-resolving "no badge")', async () => {
-    const p = Pilotiq.make('admin')
-    let calls = 0
-    const resolver = async () => { calls++; return undefined }
-    assert.equal(await p.resolveNavigationBadge('Articles', null, resolver), undefined)
-    assert.equal(await p.resolveNavigationBadge('Articles', null, resolver), undefined)
-    assert.equal(calls, 1)
-  })
-
-  it('navigationBadgeTtl(ms) clears the cache', async () => {
-    const p = Pilotiq.make('admin')
-    let calls = 0
-    const resolver = async () => { calls++; return 'x' }
-    await p.resolveNavigationBadge('A', null, resolver)
-    assert.equal(calls, 1)
-    p.navigationBadgeTtl(60_000)
-    await p.resolveNavigationBadge('A', null, resolver)
-    assert.equal(calls, 2)
-  })
-
-  it('anonymous users share one cache slot', async () => {
-    const p = Pilotiq.make('admin')
-    let calls = 0
-    const resolver = async () => { calls++; return 'x' }
-    await p.resolveNavigationBadge('A', null,      resolver)
-    await p.resolveNavigationBadge('A', undefined, resolver)
-    assert.equal(calls, 1)
-  })
-
-  it('falls back to JSON.stringify when user has no .id', async () => {
-    const p = Pilotiq.make('admin')
-    let calls = 0
-    const resolver = async () => { calls++; return 'x' }
-    await p.resolveNavigationBadge('A', { role: 'editor' }, resolver)
-    await p.resolveNavigationBadge('A', { role: 'editor' }, resolver)
-    assert.equal(calls, 1) // same JSON shape → cache hit
-    await p.resolveNavigationBadge('A', { role: 'admin'  }, resolver)
-    assert.equal(calls, 2) // different JSON → miss
-  })
-})
-
-// ─── 5a — Chunked importFactory.runImport ─────────────────────
-
-describe('importFactory.runImport — Plan 5a chunking', () => {
-  it('runs rows in chunks of `concurrency` and aggregates counts', async () => {
-    const created: string[] = []
-    let maxInFlight = 0
-    let inFlight = 0
-    const M = {
-      async create(row: { id: string }) {
-        inFlight++; if (inFlight > maxInFlight) maxInFlight = inFlight
-        await new Promise(r => setTimeout(r, 5))
-        inFlight--
-        created.push(row.id)
-      },
-      // unused for create-mode tests but the type wants them present
-      query() { return { where() { return { paginate: async () => ({ data: [] }) } } } },
-      async update() {},
-    }
-    const rows = Array.from({ length: 25 }, (_, i) => ({ id: `r${i}` }))
-    const summary = await runImport(rows, M, 'create', { concurrency: 5 }, { request: undefined })
-    assert.equal(summary.created, 25)
-    assert.equal(summary.errors.length, 0)
-    // With concurrency=5 we should see at least 4 in-flight at peak.
-    assert.ok(maxInFlight >= 4, `expected >=4 concurrent, saw ${maxInFlight}`)
-    // Never exceed the cap.
-    assert.ok(maxInFlight <= 5, `expected <=5 concurrent, saw ${maxInFlight}`)
-  })
-
-  it('preserves original-row indices in error messages despite chunking', async () => {
-    const M = {
-      async create(row: { id: string }) {
-        if (row.id === 'r2') throw new Error('boom')
-      },
-      query() { return { where() { return { paginate: async () => ({ data: [] }) } } } },
-      async update() {},
-    }
-    const rows = [{ id: 'r0' }, { id: 'r1' }, { id: 'r2' }, { id: 'r3' }]
-    const summary = await runImport(rows, M, 'create', { concurrency: 4 }, { request: undefined })
-    assert.equal(summary.created, 3)
-    assert.equal(summary.skipped, 1)
-    assert.equal(summary.errors.length, 1)
-    assert.equal(summary.errors[0]?.row, 3) // 1-based, original index 2 → row 3
-    assert.match(summary.errors[0]?.message ?? '', /boom/)
-  })
-
-  it('defaults to concurrency 10 when unset', async () => {
-    let maxInFlight = 0
-    let inFlight = 0
-    const M = {
-      async create() {
-        inFlight++; if (inFlight > maxInFlight) maxInFlight = inFlight
-        await new Promise(r => setTimeout(r, 3))
-        inFlight--
-      },
-      query() { return { where() { return { paginate: async () => ({ data: [] }) } } } },
-      async update() {},
-    }
-    const rows = Array.from({ length: 30 }, () => ({}))
-    await runImport(rows, M, 'create', {}, { request: undefined })
-    assert.ok(maxInFlight <= 10, `expected <=10 concurrent, saw ${maxInFlight}`)
-    assert.ok(maxInFlight >= 5,  `expected >=5 concurrent under default, saw ${maxInFlight}`)
-  })
-})

package/src/Pilotiq.test.ts

@@ -1,129 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-import type { Router } from '@rudderjs/router'
-import { Pilotiq, type PilotiqPlugin } from './Pilotiq.js'
-import { registerPilotiqRoutes } from './routes.js'
-
-describe('Pilotiq plugins', () => {
-  it('.use() invokes register() with the panel and records the plugin', () => {
-    const seen: Array<{ name: string; same: boolean }> = []
-    const p1: PilotiqPlugin = {
-      name: 'p1',
-      register(panel) { seen.push({ name: 'p1', same: panel instanceof Pilotiq }) },
-    }
-    const panel = Pilotiq.make('Admin').use(p1)
-    assert.deepEqual(seen, [{ name: 'p1', same: true }])
-    const installed = panel.getPlugins()
-    assert.equal(installed.length, 1)
-    assert.equal(installed[0]?.name, 'p1')
-  })
-
-  it('.plugins([…]) runs each plugin in array order', () => {
-    const order: string[] = []
-    const make = (name: string): PilotiqPlugin => ({
-      name,
-      register() { order.push(name) },
-    })
-    const panel = Pilotiq.make('Admin').plugins([make('a'), make('b'), make('c')])
-    assert.deepEqual(order, ['a', 'b', 'c'])
-    assert.deepEqual(panel.getPlugins().map((p) => p.name), ['a', 'b', 'c'])
-  })
-
-  it('.plugins([]) is a no-op', () => {
-    const panel = Pilotiq.make('Admin').plugins([])
-    assert.equal(panel.getPlugins().length, 0)
-  })
-
-  it('.plugins([…]) composes with .use()', () => {
-    const log: string[] = []
-    const mk = (n: string): PilotiqPlugin => ({ name: n, register() { log.push(n) } })
-    const panel = Pilotiq.make('Admin')
-      .use(mk('first'))
-      .plugins([mk('second'), mk('third')])
-      .use(mk('fourth'))
-    assert.deepEqual(log, ['first', 'second', 'third', 'fourth'])
-    assert.deepEqual(panel.getPlugins().map((p) => p.name), [
-      'first', 'second', 'third', 'fourth',
-    ])
-  })
-})
-
-// Minimal stub Router — `registerPilotiqRoutes` only calls `get` / `post`
-// / `put` / `delete` on the router; route bodies don't fire here. The
-// hook tests don't care about the route surface, only that the plugin's
-// `registerRoutes` callback fires with the right arguments.
-function makeStubRouter(): Router & { _calls: Array<{ method: string; path: string }> } {
-  const calls: Array<{ method: string; path: string }> = []
-  const noop = (path: string): void => { calls.push({ method: 'unknown', path }) }
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const stub: any = {
-    get:    (path: string) => noop(path),
-    post:   (path: string) => noop(path),
-    put:    (path: string) => noop(path),
-    delete: (path: string) => noop(path),
-    patch:  (path: string) => noop(path),
-    // `router.group(opts, fn)` runs `fn()` synchronously inside its
-    // scope. Stub mirrors that — `Pilotiq.guard()` middleware doesn't
-    // touch the stub, only `fn()` matters.
-    group:  (_opts: unknown, fn: () => void) => { fn() },
-    _calls: calls,
-  }
-  return stub
-}
-
-describe('PilotiqPlugin.registerRoutes hook', () => {
-  it('fires once per plugin during registerPilotiqRoutes, in registration order', () => {
-    const order: string[] = []
-    const router = makeStubRouter()
-    const mk = (n: string): PilotiqPlugin => ({
-      name: n,
-      register() { /* no-op */ },
-      registerRoutes(r, p) {
-        assert.equal(r, router)
-        assert.ok(p instanceof Pilotiq)
-        order.push(n)
-      },
-    })
-    const panel = Pilotiq.make('Admin').plugins([mk('a'), mk('b'), mk('c')])
-    registerPilotiqRoutes(router, panel)
-    assert.deepEqual(order, ['a', 'b', 'c'])
-  })
-
-  it('skips plugins that do not implement the hook', () => {
-    const order: string[] = []
-    const router = makeStubRouter()
-    const withHook: PilotiqPlugin = {
-      name: 'with-hook',
-      register() { /* no-op */ },
-      registerRoutes() { order.push('with-hook') },
-    }
-    const withoutHook: PilotiqPlugin = {
-      name: 'without-hook',
-      register() { /* no-op */ },
-    }
-    const panel = Pilotiq.make('Admin').plugins([withoutHook, withHook])
-    // No throw expected — the optional hook is skipped on plugins that
-    // omit it, so a "config-only" plugin remains a one-method object.
-    registerPilotiqRoutes(router, panel)
-    assert.deepEqual(order, ['with-hook'])
-  })
-
-  it('runs after core routes — at least one core call has fired before the first hook', () => {
-    const router = makeStubRouter()
-    let coreCallsAtHookTime = -1
-    const probe: PilotiqPlugin = {
-      name: 'probe',
-      register() { /* no-op */ },
-      registerRoutes() {
-        coreCallsAtHookTime = router._calls.length
-      },
-    }
-    // The dashboard route alone (`GET ${base}`) registers unconditionally
-    // — so any panel produces at least one core router call before the
-    // plugin hooks fire. Empty-resources panel is enough to cover this.
-    const panel = Pilotiq.make('Admin').plugins([probe])
-    registerPilotiqRoutes(router, panel)
-    assert.ok(coreCallsAtHookTime > 0,
-      `expected core routes to register before the hook, got ${coreCallsAtHookTime} calls`)
-  })
-})