@nivaro/extension-kit 0.1.1

package/dist/testing.d.ts

@@ -0,0 +1,193 @@
+/**
+ * A test double for the extension context (#829): every registration is
+ * recorded, every side effect is captured instead of sent, hooks and crons
+ * can be run by the test, and the database is an in-memory fake with the
+ * knex chain shape extensions actually use. Nothing here boots the API.
+ *
+ *   const ctx = createTestContext({ tables: { orders: [{ id: 1, total: 5 }] } })
+ *   await myExtension.register(ctx)
+ *   await ctx.runHooks('orders', 'create', 'after', { keys: [1], result: { id: 1, total: 5 } })
+ *   expect(ctx.calls.notifications).toHaveLength(1)
+ */
+import type { Knex } from 'knex';
+import type { ExtensionContext, ExtensionCronMeta, ExtensionCronOpts, ExtensionEventHandler, ExtensionSettingValue } from './context.js';
+import type { FlowOpRegistration, FlowTriggerRegistration } from './flows.js';
+import type { ExtensionHookContext, ExtensionHookHandler, HookAction, HookTiming } from './hooks.js';
+import type { ImportProcessorDef } from './imports.js';
+import type { DigestSectionProvider, MailTypeDef, NotificationChannelDef, NotificationSourceProvider, NotifyUserOptions } from './notifications.js';
+import type { ObligationKindDef, ObligationResolvePatch, ObligationTrigger, ObligationTriggerContext } from './obligations.js';
+import type { BotToolDef, BriefLineProvider, BulkActionDef, CallOptions, CallResult, CollectionViewDef, ConfigSeedDef, DashboardWidgetDef, EventSourceDef, FieldTypeDef, ImportParserDef, IntegrityCheck, ItemActionDef, LinkRegistration, MachineMarkerSet, OpsTaskDef, OpsTaskOutcome, ReadinessCheck, RelatedNoteProvider, SchemaStepDef, StorageAdapter, ValidatorDef } from './registrations.js';
+import type { IntegrationSignal, SignalActionHandler } from './signals.js';
+import type { ExtensionUser } from './user.js';
+type Row = Record<string, unknown>;
+export interface TestDbState {
+    tables: Record<string, Row[]>;
+    /** Every statement the fake ran, in order — assert on writes. */
+    log: Array<{
+        table: string;
+        op: 'select' | 'insert' | 'update' | 'delete' | 'raw' | 'schema';
+        detail?: unknown;
+    }>;
+}
+/**
+ * A knex-shaped in-memory database. Supports the chain extensions use:
+ * select / where (object, col=val, col op val, callback) / whereIn /
+ * whereNotIn / whereNull / whereNotNull / orderBy / limit / offset /
+ * first / pluck / count / insert(+returning) / update / del, `db.raw`
+ * (answers `[]` unless `raw` is given), `db.schema.hasColumn` / hasTable /
+ * createTable / alterTable / dropTable (tables recorded, columns not
+ * modelled), `db.transaction`, `db.fn.now`. Joins are accepted and ignored — a test
+ * seeds the joined columns on the row it expects back.
+ */
+export declare function createTestDb(opts?: {
+    tables?: Record<string, Row[]>;
+    raw?: (sql: string, bindings?: unknown) => unknown;
+}): Knex & {
+    state: TestDbState;
+};
+export interface TestRoute {
+    method: string;
+    url: string;
+    handler: (req: unknown, reply: unknown) => unknown;
+    opts: Record<string, unknown>;
+}
+export interface TestContextOptions {
+    /** A knex, or seed rows for the in-memory fake (`createTestDb`). */
+    db?: Knex;
+    tables?: Record<string, Row[]>;
+    /** The acting user hooks see; defaults to an active admin-less person. */
+    user?: Partial<ExtensionUser>;
+    /** Values `ctx.settings.get` answers. */
+    settings?: Record<string, ExtensionSettingValue>;
+    /** What `callExternalApi` answers; default `{status: 200, body: {}}`. */
+    externalApi?: (nameOrId: string | number, options?: CallOptions) => CallResult | Promise<CallResult>;
+    /** What `mail.renderTemplate` returns; default the template name. */
+    renderTemplate?: (name: string, data: Record<string, unknown>) => string;
+}
+export interface TestContext extends ExtensionContext {
+    database: Knex & {
+        state?: TestDbState;
+    };
+    user: ExtensionUser;
+    /** Every side effect the extension asked for, in order. */
+    calls: {
+        notifications: Array<{
+            userId: string;
+            opts: NotifyUserOptions;
+        }>;
+        externalApi: Array<{
+            nameOrId: string | number;
+            options?: CallOptions;
+            result: CallResult;
+        }>;
+        activity: Array<Parameters<ExtensionContext['logActivity']>[0]>;
+        flowsEmitted: Array<{
+            type: string;
+            payload: Record<string, unknown>;
+        }>;
+        eventsPublished: Array<{
+            eventType: string;
+            payload: unknown;
+        }>;
+        obligationsOpened: Array<{
+            ctx: ObligationTriggerContext;
+            trigger: ObligationTrigger;
+            trigger_ref: string | null;
+            id: number;
+        }>;
+        obligationsResolved: Array<{
+            id: number | null;
+            patch: ObligationResolvePatch;
+        }>;
+        longSql: Array<{
+            sql: string;
+            opts?: {
+                timeoutMs?: number;
+            };
+        }>;
+        log: Array<{
+            level: 'info' | 'warn' | 'error' | 'debug';
+            args: unknown[];
+        }>;
+    };
+    /** Everything the extension registered, by kind. */
+    registered: {
+        hooks: Array<{
+            collection: string;
+            action: string;
+            timing: HookTiming;
+            fn: ExtensionHookHandler;
+        }>;
+        crons: Map<string, {
+            expression: string;
+            fn: () => void | Promise<void>;
+            opts?: ExtensionCronOpts;
+            meta?: ExtensionCronMeta;
+        }>;
+        routes: TestRoute[];
+        eventHandlers: Array<{
+            eventType: string;
+            fn: ExtensionEventHandler;
+        }>;
+        bulkActions: BulkActionDef[];
+        itemActions: ItemActionDef[];
+        notificationChannels: NotificationChannelDef[];
+        notificationSources: NotificationSourceProvider[];
+        noteSources: RelatedNoteProvider[];
+        machineMarkers: MachineMarkerSet[];
+        dashboardWidgets: DashboardWidgetDef[];
+        storage: Map<string, StorageAdapter>;
+        activeStorage: string | null;
+        fieldTypes: FieldTypeDef[];
+        collectionViews: CollectionViewDef[];
+        importParsers: ImportParserDef[];
+        importProcessors: ImportProcessorDef[];
+        validators: ValidatorDef[];
+        briefLines: Array<{
+            collection: string;
+            fn: BriefLineProvider;
+        }>;
+        digestSections: DigestSectionProvider[];
+        readinessChecks: ReadinessCheck[];
+        tasks: OpsTaskDef[];
+        seeds: ConfigSeedDef[];
+        schemaSteps: SchemaStepDef[];
+        obligationKinds: ObligationKindDef[];
+        signals: IntegrationSignal[];
+        signalActions: SignalActionHandler[];
+        eventSources: EventSourceDef[];
+        integrityChecks: IntegrityCheck[];
+        links: LinkRegistration[];
+        mailTypes: MailTypeDef[];
+        flowOps: FlowOpRegistration[];
+        flowTriggers: FlowTriggerRegistration[];
+        botTools: BotToolDef[];
+    };
+    /** Run the registered hooks for a write, as the items service would. */
+    runHooks(collection: string, action: HookAction, timing: HookTiming, ctx: Partial<Omit<ExtensionHookContext, 'collection' | 'action' | 'database'>>): Promise<ExtensionHookContext>;
+    /** Run one registered cron job by its (unscoped) id. */
+    runCron(id: string): Promise<void>;
+    /** Run a registered operational task; its log lines come back with the outcome. */
+    runTask(key: string, opts?: {
+        execute?: boolean;
+    }): Promise<OpsTaskOutcome & {
+        log: string[];
+    }>;
+    /** Deliver an event to the registered handlers. */
+    deliverEvent(eventType: string, payload: unknown): Promise<void>;
+    /** Call a registered route with a fake request; answers `{status, body}`. */
+    invoke(method: string, url: string, req?: {
+        params?: Row;
+        query?: Row;
+        body?: unknown;
+        headers?: Record<string, string>;
+        user?: ExtensionUser | null;
+    }): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+}
+/** Build a context whose every effect is recorded. */
+export declare function createTestContext(opts?: TestContextOptions): TestContext;
+export {};
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}