@n8n/frontend-module-sdk 0.10.1 → 0.11.0

package/README.md

@@ -3,8 +3,9 @@
 The frontend module contract and registries for n8n editor modules.
 
 This package owns the `FrontendModuleDescription` descriptor type, the
-`defineFrontendModule()` helper that declares one, plus the modal and resource
-registries that features register against. The editor shell keeps the wiring
+`defineFrontendModule()` helper that declares one, plus the modal, resource and
+capability registries that features register against. The "Capabilities" section
+of the frontend module guide covers when to declare a capability. The editor shell keeps the wiring
 (`moduleInitializer`) that drives the two-phase lifecycle; this package only
 defines the contract and the registry state.
 

package/package.json

@@ -1,17 +1,17 @@
 {
   "type": "module",
   "name": "@n8n/frontend-module-sdk",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "main": "src/index.ts",
   "import": "src/index.ts",
   "exports": {
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@n8n/api-types": "1.40.1",
-    "@n8n/design-system": "2.39.1",
+    "@n8n/api-types": "1.41.0",
+    "@n8n/design-system": "2.40.0",
     "@n8n/utils": "1.48.0",
-    "n8n-workflow": "2.40.1",
+    "n8n-workflow": "2.41.0",
     "vue": "^3.5.13",
     "vue-router": "^4.5.0"
   },

package/src/capabilities/index.ts

@@ -0,0 +1,2 @@
+export { modalOpeners } from './modalOpeners';
+export { workflowMcpAccessSync } from './workflowMcpAccessSync';

package/src/capabilities/modalOpeners.ts

@@ -0,0 +1,8 @@
+import { declareCapability } from '../declareCapability';
+import type { ModalOpeners } from '../types/capability';
+
+/**
+ * Opens a shell-owned modal. Modals live in the shell's `ui.store`, which a
+ * module cannot reach.
+ */
+export const modalOpeners = declareCapability<ModalOpeners>('modal-openers');

package/src/capabilities/workflowMcpAccessSync.ts

@@ -0,0 +1,12 @@
+import { declareCapability } from '../declareCapability';
+
+/**
+ * Writes an MCP access toggle back into the shell's workflow stores, so the list
+ * and the open document agree with the server without a refetch.
+ *
+ * Declared ahead of its provider: the shell provides it when the MCP feature
+ * moves into its own module package.
+ */
+export const workflowMcpAccessSync = declareCapability<(ids: string[], enabled: boolean) => void>(
+	'workflow-mcp-access-sync',
+);

package/src/declareCapability.test.ts

@@ -0,0 +1,17 @@
+import { declareCapability } from './declareCapability';
+
+describe('declareCapability', () => {
+	it('returns a token carrying the key and the fallback', () => {
+		const noop = () => {};
+		const token = declareCapability<() => void>('test-key', { fallback: noop });
+
+		expect(token.key).toBe('test-key');
+		expect(token.fallback).toBe(noop);
+	});
+
+	it('leaves the fallback undefined when it is omitted', () => {
+		const token = declareCapability<() => void>('test-key');
+
+		expect(token.fallback).toBeUndefined();
+	});
+});

package/src/declareCapability.ts

@@ -0,0 +1,26 @@
+import type { CapabilityToken } from './types/capability';
+
+/**
+ * Declares a capability: an action the shell owns and a module calls, but cannot
+ * import.
+ *
+ * Reach for one only when all three hold:
+ *
+ * - the module needs a runtime action or a reactive read, not a component;
+ * - the target is shell-core state with no path down to an L2 package;
+ * - no existing contribution surface fits (modals, components, commands,
+ *   resources, push handlers, parameter inputs).
+ *
+ * If any of the three fails, use the surface that fits instead.
+ *
+ * Give `T` explicitly. It is the contract both sides are checked against, and it
+ * cannot be inferred from the key.
+ */
+export function declareCapability<T>(
+	key: string,
+	options: { fallback?: T } = {},
+): CapabilityToken<T> {
+	// Only carry the property when the caller declared one: `use()` reads presence,
+	// so an always-present `fallback: undefined` would suppress its throw.
+	return 'fallback' in options ? { key, fallback: options.fallback } : { key };
+}

package/src/index.ts

@@ -2,6 +2,7 @@ export type * from './types';
 
 export { defineFrontendModule } from './defineFrontendModule';
 export { assertUniqueRouteNames } from './routeNames';
+export { declareCapability } from './declareCapability';
 
 export * as modalRegistry from './registries/modalRegistry';
 export * from './registries/resourceRegistry';
@@ -9,3 +10,7 @@ export * as pushHandlerRegistry from './registries/pushHandlerRegistry';
 export * as commandRegistry from './registries/commandRegistry';
 export * as componentRegistry from './registries/componentRegistry';
 export * as parameterInputRegistry from './registries/parameterInputRegistry';
+export * as capabilityRegistry from './registries/capabilityRegistry';
+
+// Namespaced so a token does not clash with a same-named local const in the shell.
+export * as capabilities from './capabilities';

package/src/registries/capabilityRegistry.test.ts

@@ -0,0 +1,102 @@
+import * as capabilityRegistry from './capabilityRegistry';
+import { declareCapability } from '../declareCapability';
+
+type Greeter = (name: string) => string;
+
+// Local tokens on purpose: the registry contract must not depend on the tokens
+// the shell happens to ship in `../capabilities`.
+const greeter = declareCapability<Greeter>('test-greeter');
+const greeterWithFallback = declareCapability<Greeter>('test-greeter-with-fallback', {
+	fallback: () => 'fallback',
+});
+
+const hello: Greeter = (name) => `hello ${name}`;
+const goodbye: Greeter = (name) => `goodbye ${name}`;
+
+describe('capabilityRegistry', () => {
+	beforeEach(() => {
+		capabilityRegistry.clear();
+	});
+
+	it('returns the provided implementation from use', () => {
+		capabilityRegistry.provide(greeter, hello);
+
+		expect(capabilityRegistry.use(greeter)).toBe(hello);
+		expect(capabilityRegistry.has(greeter)).toBe(true);
+	});
+
+	it('throws from use when nothing is provided and no fallback was declared', () => {
+		expect(() => capabilityRegistry.use(greeter)).toThrowError(
+			'Capability "test-greeter" has no provider. Call capabilityRegistry.provide() at app bootstrap.',
+		);
+	});
+
+	it('returns the fallback from use when nothing is provided', () => {
+		expect(capabilityRegistry.use(greeterWithFallback)('ada')).toBe('fallback');
+	});
+
+	it('prefers a provided nullish implementation over the fallback', () => {
+		const nullableGreeter = declareCapability<Greeter | null>('test-nullable-greeter', {
+			fallback: goodbye,
+		});
+		capabilityRegistry.provide(nullableGreeter, null);
+
+		expect(capabilityRegistry.use(nullableGreeter)).toBeNull();
+	});
+
+	it('prefers a provided implementation over the fallback', () => {
+		capabilityRegistry.provide(greeterWithFallback, hello);
+
+		expect(capabilityRegistry.use(greeterWithFallback)).toBe(hello);
+	});
+
+	it('returns undefined from tryUse when nothing is provided, even with a fallback', () => {
+		expect(capabilityRegistry.tryUse(greeter)).toBeUndefined();
+		expect(capabilityRegistry.tryUse(greeterWithFallback)).toBeUndefined();
+		expect(capabilityRegistry.has(greeterWithFallback)).toBe(false);
+	});
+
+	it('treats re-providing the same implementation as a no-op', () => {
+		const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+		capabilityRegistry.provide(greeter, hello);
+		capabilityRegistry.provide(greeter, hello);
+
+		expect(capabilityRegistry.use(greeter)).toBe(hello);
+		expect(warn).not.toHaveBeenCalled();
+	});
+
+	it('keeps the first implementation and warns when a different one is provided', () => {
+		const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+		capabilityRegistry.provide(greeter, hello);
+		capabilityRegistry.provide(greeter, goodbye);
+
+		expect(capabilityRegistry.use(greeter)).toBe(hello);
+		expect(warn).toHaveBeenCalledWith('Capability "test-greeter" is already provided. Skipping.');
+	});
+
+	it('gives two tokens that share a key string their own slot', () => {
+		const sameKey = declareCapability<() => number>('test-greeter');
+		capabilityRegistry.provide(greeter, hello);
+
+		expect(capabilityRegistry.tryUse(sameKey)).toBeUndefined();
+		expect(capabilityRegistry.use(greeter)).toBe(hello);
+	});
+
+	it('frees the slot on unprovide', () => {
+		capabilityRegistry.provide(greeter, hello);
+		capabilityRegistry.unprovide(greeter);
+
+		expect(capabilityRegistry.tryUse(greeter)).toBeUndefined();
+		expect(capabilityRegistry.has(greeter)).toBe(false);
+	});
+
+	it('removes every provider on clear', () => {
+		capabilityRegistry.provide(greeter, hello);
+		capabilityRegistry.provide(greeterWithFallback, goodbye);
+
+		capabilityRegistry.clear();
+
+		expect(capabilityRegistry.has(greeter)).toBe(false);
+		expect(capabilityRegistry.has(greeterWithFallback)).toBe(false);
+	});
+});

package/src/registries/capabilityRegistry.ts

@@ -0,0 +1,66 @@
+import type { CapabilityToken } from '../types/capability';
+
+/**
+ * Shell-provided actions, keyed by capability token. The shell provides;
+ * modules read.
+ *
+ * Not reactive, unlike `componentRegistry`: a capability is an action a module
+ * calls from a handler or a guard, so nothing renders off it. A capability whose
+ * value changes should carry a `Ref` and stay one provider.
+ *
+ * Keyed by the token itself, not by `token.key`: two tokens that pick the same
+ * string then get their own slot instead of one reading the other's value.
+ */
+const providers = new Map<CapabilityToken<unknown>, unknown>();
+
+export function provide<T>(token: CapabilityToken<T>, implementation: T): void {
+	if (providers.has(token) && providers.get(token) !== implementation) {
+		console.warn(`Capability "${token.key}" is already provided. Skipping.`);
+		return;
+	}
+
+	providers.set(token, implementation);
+}
+
+/**
+ * The provided implementation, or `undefined` when there is none. Ignores the
+ * token's `fallback` on purpose: this is the presence check.
+ */
+export function tryUse<T>(token: CapabilityToken<T>): T | undefined {
+	// The one cast here. The token is the slot and `provide()` is the only writer,
+	// so whatever is stored under it came from a `provide()` call with the same `T`.
+	return providers.get(token) as T | undefined;
+}
+
+/**
+ * The provided implementation, or the token's fallback. Throws when there is
+ * neither — call it from a handler or a guard, never at module scope.
+ */
+export function use<T>(token: CapabilityToken<T>): T {
+	// Presence decides, not the value: a provider is free to supply `null` or
+	// `undefined` when `T` allows it, and must still win over the fallback.
+	if (has(token)) {
+		return providers.get(token) as T;
+	}
+
+	if ('fallback' in token) {
+		return token.fallback as T;
+	}
+
+	throw new Error(
+		`Capability "${token.key}" has no provider. Call capabilityRegistry.provide() at app bootstrap.`,
+	);
+}
+
+export function has(token: CapabilityToken<unknown>): boolean {
+	return providers.has(token);
+}
+
+export function unprovide(token: CapabilityToken<unknown>): void {
+	providers.delete(token);
+}
+
+/** Test isolation only. */
+export function clear(): void {
+	providers.clear();
+}

package/src/types/capability.ts

@@ -0,0 +1,22 @@
+/**
+ * A typed key for a capability. `declareCapability()` is the only way to make
+ * one, and the token is the only way to read or write its slot in the registry.
+ */
+export interface CapabilityToken<T> {
+	/** Labels the capability in registry warnings and errors. */
+	readonly key: string;
+	/** Returned by `use()` when nothing is provided. Absent means `use()` throws. */
+	readonly fallback?: T;
+}
+
+/**
+ * Structurally identical to `ModalOpeners` in `@n8n/stores`; declared here so a
+ * module needs no `@n8n/stores` import.
+ *
+ * Method syntax keeps the parameters bivariant, so the shell can provide openers
+ * typed with the narrower `ModalKey` union without a cast.
+ */
+export interface ModalOpeners {
+	openModal(name: string): void;
+	openModalWithData(payload: { name: string; data: Record<string, unknown> }): void;
+}

package/src/types/index.ts

@@ -10,3 +10,4 @@ export type * from './shortcut';
 export type * from './banner';
 export type * from './setup';
 export type * from './locale';
+export type * from './capability';