Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,108 @@
|
||||
/**
|
||||
* Phase 06 #22 — Plugin hook emission helper.
|
||||
*
|
||||
* Wraps `publishOutboxEvent` so host call-sites stay one-line:
|
||||
*
|
||||
* await emitPluginHook(tx, PLUGIN_HOOK_TENANT_CREATED, payload);
|
||||
*
|
||||
* The helper:
|
||||
* 1. Validates the payload against the registered Zod schema.
|
||||
* 2. Publishes a `plugin.hook.<name>` outbox event inside the
|
||||
* surrounding Prisma transaction (atomic with the host write).
|
||||
* 3. Returns the persisted OutboxEvent row so callers can correlate
|
||||
* it in audit logs.
|
||||
*
|
||||
* Bad payloads throw {@link PluginHookValidationError} — callers MUST
|
||||
* either handle it (when the payload is user-derived) or let it
|
||||
* propagate so the host write rolls back.
|
||||
*
|
||||
* Subscriber resolution + fan-out into one outbox row per installed
|
||||
* plugin is intentionally deferred to the worker side: a single
|
||||
* `plugin.hook.<name>` event lands in the outbox queue and the
|
||||
* downstream consumer (worker) expands it into per-plugin invocations.
|
||||
* This keeps the producer path (web request) cheap and avoids
|
||||
* coupling the request thread to the Plugin table.
|
||||
*/
|
||||
|
||||
import type { z } from "zod";
|
||||
import {
|
||||
validatePluginHookPayload,
|
||||
type PluginHookDefinition,
|
||||
} from "./registry.js";
|
||||
|
||||
/**
|
||||
* JSON-compatible value type, structurally identical to
|
||||
* `Prisma.InputJsonValue` without taking the dependency on
|
||||
* `@toolctrl/db` (which would cycle through the worker bootstrap).
|
||||
*/
|
||||
export type PluginHookJsonValue =
|
||||
| string
|
||||
| number
|
||||
| boolean
|
||||
| null
|
||||
| { [key: string]: PluginHookJsonValue }
|
||||
| ReadonlyArray<PluginHookJsonValue>;
|
||||
|
||||
export class PluginHookValidationError extends Error {
|
||||
public override readonly name = "PluginHookValidationError";
|
||||
public readonly hookName: string;
|
||||
public readonly issues: ReadonlyArray<z.ZodIssue>;
|
||||
constructor(hookName: string, issues: ReadonlyArray<z.ZodIssue>) {
|
||||
super(`Invalid payload for plugin hook '${hookName}': ${JSON.stringify(issues)}`);
|
||||
this.hookName = hookName;
|
||||
this.issues = issues;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Minimal publish surface — kept identical to the @toolctrl/db helper
|
||||
* so this package does not have to depend on @toolctrl/db directly
|
||||
* (avoids a cycle with the worker bootstrap that pulls plugin-runtime
|
||||
* via @toolctrl/db).
|
||||
*/
|
||||
export type PluginHookOutboxPublisher = (
|
||||
tx: unknown,
|
||||
args: {
|
||||
tenantId?: string | null;
|
||||
type: string;
|
||||
payload: PluginHookJsonValue;
|
||||
dispatchKey?: string | null;
|
||||
}
|
||||
) => Promise<unknown>;
|
||||
|
||||
export type EmitPluginHookOptions = {
|
||||
tenantId?: string | null;
|
||||
/**
|
||||
* Optional idempotency key. When two writers might emit the same
|
||||
* hook for the same business object (e.g. two onboarding paths both
|
||||
* creating the same tenant) supplying a stable key prevents
|
||||
* duplicate downstream invocations.
|
||||
*/
|
||||
dispatchKey?: string | null;
|
||||
};
|
||||
|
||||
/**
|
||||
* Validate + publish a plugin-hook outbox event inside a transaction.
|
||||
* The transaction client is intentionally typed as `unknown` so this
|
||||
* package keeps zero runtime dependency on @toolctrl/db — the caller
|
||||
* (a `.server.ts` file in apps/web) already imports the prisma types
|
||||
* and passes the correct shape.
|
||||
*/
|
||||
export async function emitPluginHook<TPayload>(
|
||||
tx: unknown,
|
||||
def: PluginHookDefinition<TPayload>,
|
||||
payload: TPayload,
|
||||
publish: PluginHookOutboxPublisher,
|
||||
options: EmitPluginHookOptions = {}
|
||||
): Promise<void> {
|
||||
const validation = validatePluginHookPayload(def, payload);
|
||||
if (!validation.ok) {
|
||||
throw new PluginHookValidationError(def.name, validation.issues);
|
||||
}
|
||||
await publish(tx, {
|
||||
tenantId: options.tenantId ?? null,
|
||||
type: def.outboxEventType,
|
||||
payload: validation.payload as unknown as PluginHookJsonValue,
|
||||
dispatchKey: options.dispatchKey ?? null,
|
||||
});
|
||||
}
|
||||
Reference in new issue
Block a user