@moku-labs/core 0.1.0-alpha.4 → 0.1.0-alpha.5

package/dist/index.cjs

@@ -742,6 +742,32 @@ function assertValidApi(frameworkId, pluginName, api) {
 function assertValidCreateState(frameworkId, pluginName, createState) {
 	if (createState !== void 0 && typeof createState !== "function") throw new TypeError(`[${frameworkId}] Plugin "${pluginName}" has invalid createState: expected a function.\n  Provide a function like: createState: ctx => ({ key: initialValue })`);
 }
+/** PluginInstance field names that cannot be used as helper names. */
+const PLUGIN_INSTANCE_RESERVED_KEYS = new Set([
+	"name",
+	"spec",
+	"_phantom"
+]);
+/**
+* Validates that `helpers` is a plain object of functions if provided.
+* Also rejects helper names that collide with PluginInstance properties.
+*
+* @param frameworkId - Framework identifier used in error messages.
+* @param pluginName - Validated plugin name.
+* @param helpers - Candidate helpers value from plugin spec.
+* @example
+* ```ts
+* assertValidHelpers("my-app", "router", { route: () => ({}) });
+* ```
+*/
+function assertValidHelpers(frameworkId, pluginName, helpers) {
+	if (helpers === void 0) return;
+	if (!isRecord(helpers)) throw new TypeError(`[${frameworkId}] Plugin "${pluginName}" has invalid helpers: expected an object.\n  Provide an object of functions: helpers: { myHelper: (...args) => result }`);
+	for (const [key, value] of Object.entries(helpers)) {
+		if (typeof value !== "function") throw new TypeError(`[${frameworkId}] Plugin "${pluginName}" has invalid helper "${key}": expected a function.\n  Each helper must be a function.`);
+		if (PLUGIN_INSTANCE_RESERVED_KEYS.has(key)) throw new TypeError(`[${frameworkId}] Plugin "${pluginName}" helper "${key}" conflicts with a PluginInstance property.\n  Choose a different helper name.`);
+	}
+}
 /**
 * Creates a bound `createPlugin` function that captures framework generics.
 *
@@ -780,10 +806,12 @@ function createPluginFactory(frameworkId) {
 		assertValidHooks(frameworkId, name, spec.hooks);
 		assertValidApi(frameworkId, name, spec.api);
 		assertValidCreateState(frameworkId, name, spec.createState);
+		assertValidHelpers(frameworkId, name, spec.helpers);
 		return {
 			name,
 			spec,
-			_phantom: {}
+			_phantom: {},
+			...isRecord(spec.helpers) ? spec.helpers : {}
 		};
 	};
 	return createPlugin;

package/dist/index.d.cts

@@ -781,7 +781,7 @@ type RegisterFunction = {
 * >;
 * ```
 */
-type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap extends FrameworkEventMap, PluginEventMap extends Record<string, unknown>, PluginConfig extends Record<string, unknown>, PluginState, PluginApi extends Record<string, unknown>, DependencyPlugins extends DependencyPluginTuple, CoreApis extends Record<string, unknown> = {}> = {
+type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap extends FrameworkEventMap, PluginEventMap extends Record<string, unknown>, PluginConfig extends Record<string, unknown>, PluginState, PluginApi extends Record<string, unknown>, DependencyPlugins extends DependencyPluginTuple, CoreApis extends Record<string, unknown> = {}, Helpers extends Record<string, (...arguments_: any[]) => any> = Record<never, never>> = {
   /**
   * Declare plugin-specific events via a register callback.
   * Used for compile-time type inference only — the kernel does not call this at runtime.
@@ -893,6 +893,20 @@ type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap exten
   * ```
   */
   hooks?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState, CoreApis>) => { [EventName in string & keyof MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>]?: (payload: MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>[EventName]) => void | Promise<void> };
+  /**
+  * Static helper functions exposed directly on the plugin instance.
+  * Helpers run before createApp — they receive no context.
+  * Use for typed factories and builders that produce config values.
+  *
+  * @example
+  * ```ts
+  * helpers: {
+  *   route: (path: string, component: string) => ({ path, component }),
+  *   redirect: (from: string, to: string) => ({ from, to, type: 'redirect' as const }),
+  * }
+  * ```
+  */
+  helpers?: Helpers;
 };
 /**
 * Bound createPlugin function type, parameterized by the framework's Config and Events.
@@ -907,9 +921,10 @@ type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap exten
 * ```
 */
 type BoundCreatePluginFunction<GlobalConfig extends FrameworkConfig, GlobalEventMap extends FrameworkEventMap, CoreApis extends Record<string, unknown> = {}> = {
-  <const PluginName extends string = string, PluginConfig extends Record<string, unknown> = Record<string, never>, PluginState = Record<string, never>, PluginApi extends Record<string, unknown> = Record<string, never>, DependencyPlugins extends DependencyPluginTuple = readonly [], PluginEventMap extends Record<string, unknown> = EmptyPluginEventMap, HookHandlerMap extends Record<string, any> = Record<never, never>>(name: PluginName, spec: Omit<CreatePluginSpec<GlobalConfig, GlobalEventMap, PluginEventMap, PluginConfig, PluginState, PluginApi, DependencyPlugins, CoreApis>, "hooks"> & {
+  <const PluginName extends string = string, PluginConfig extends Record<string, unknown> = Record<string, never>, PluginState = Record<string, never>, PluginApi extends Record<string, unknown> = Record<string, never>, DependencyPlugins extends DependencyPluginTuple = readonly [], PluginEventMap extends Record<string, unknown> = EmptyPluginEventMap, HookHandlerMap extends Record<string, any> = Record<never, never>, Helpers extends Record<string, (...arguments_: any[]) => any> = Record<never, never>>(name: PluginName, spec: Omit<CreatePluginSpec<GlobalConfig, GlobalEventMap, PluginEventMap, PluginConfig, PluginState, PluginApi, DependencyPlugins, CoreApis>, "hooks" | "helpers"> & {
     hooks?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState, CoreApis>) => { [K in keyof HookHandlerMap]: K extends string & keyof MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins> ? (payload: MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>[K & keyof MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>]) => void | Promise<void> : never };
-  }): PluginInstance<PluginName, PluginConfig, PluginState, PluginApi, PluginEventMap>;
+    helpers?: Helpers;
+  }): PluginInstance<PluginName, PluginConfig, PluginState, PluginApi, PluginEventMap> & Helpers;
 };
 /**
 * Creates a bound `createPlugin` function that captures framework generics.

package/dist/index.d.mts

@@ -781,7 +781,7 @@ type RegisterFunction = {
 * >;
 * ```
 */
-type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap extends FrameworkEventMap, PluginEventMap extends Record<string, unknown>, PluginConfig extends Record<string, unknown>, PluginState, PluginApi extends Record<string, unknown>, DependencyPlugins extends DependencyPluginTuple, CoreApis extends Record<string, unknown> = {}> = {
+type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap extends FrameworkEventMap, PluginEventMap extends Record<string, unknown>, PluginConfig extends Record<string, unknown>, PluginState, PluginApi extends Record<string, unknown>, DependencyPlugins extends DependencyPluginTuple, CoreApis extends Record<string, unknown> = {}, Helpers extends Record<string, (...arguments_: any[]) => any> = Record<never, never>> = {
   /**
   * Declare plugin-specific events via a register callback.
   * Used for compile-time type inference only — the kernel does not call this at runtime.
@@ -893,6 +893,20 @@ type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap exten
   * ```
   */
   hooks?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState, CoreApis>) => { [EventName in string & keyof MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>]?: (payload: MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>[EventName]) => void | Promise<void> };
+  /**
+  * Static helper functions exposed directly on the plugin instance.
+  * Helpers run before createApp — they receive no context.
+  * Use for typed factories and builders that produce config values.
+  *
+  * @example
+  * ```ts
+  * helpers: {
+  *   route: (path: string, component: string) => ({ path, component }),
+  *   redirect: (from: string, to: string) => ({ from, to, type: 'redirect' as const }),
+  * }
+  * ```
+  */
+  helpers?: Helpers;
 };
 /**
 * Bound createPlugin function type, parameterized by the framework's Config and Events.
@@ -907,9 +921,10 @@ type CreatePluginSpec<GlobalConfig extends FrameworkConfig, GlobalEventMap exten
 * ```
 */
 type BoundCreatePluginFunction<GlobalConfig extends FrameworkConfig, GlobalEventMap extends FrameworkEventMap, CoreApis extends Record<string, unknown> = {}> = {
-  <const PluginName extends string = string, PluginConfig extends Record<string, unknown> = Record<string, never>, PluginState = Record<string, never>, PluginApi extends Record<string, unknown> = Record<string, never>, DependencyPlugins extends DependencyPluginTuple = readonly [], PluginEventMap extends Record<string, unknown> = EmptyPluginEventMap, HookHandlerMap extends Record<string, any> = Record<never, never>>(name: PluginName, spec: Omit<CreatePluginSpec<GlobalConfig, GlobalEventMap, PluginEventMap, PluginConfig, PluginState, PluginApi, DependencyPlugins, CoreApis>, "hooks"> & {
+  <const PluginName extends string = string, PluginConfig extends Record<string, unknown> = Record<string, never>, PluginState = Record<string, never>, PluginApi extends Record<string, unknown> = Record<string, never>, DependencyPlugins extends DependencyPluginTuple = readonly [], PluginEventMap extends Record<string, unknown> = EmptyPluginEventMap, HookHandlerMap extends Record<string, any> = Record<never, never>, Helpers extends Record<string, (...arguments_: any[]) => any> = Record<never, never>>(name: PluginName, spec: Omit<CreatePluginSpec<GlobalConfig, GlobalEventMap, PluginEventMap, PluginConfig, PluginState, PluginApi, DependencyPlugins, CoreApis>, "hooks" | "helpers"> & {
     hooks?: (context: PluginExecutionContext<GlobalConfig, MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>, PluginConfig, PluginState, CoreApis>) => { [K in keyof HookHandlerMap]: K extends string & keyof MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins> ? (payload: MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>[K & keyof MergedPluginEvents<GlobalEventMap, PluginEventMap, DependencyPlugins>]) => void | Promise<void> : never };
-  }): PluginInstance<PluginName, PluginConfig, PluginState, PluginApi, PluginEventMap>;
+    helpers?: Helpers;
+  }): PluginInstance<PluginName, PluginConfig, PluginState, PluginApi, PluginEventMap> & Helpers;
 };
 /**
 * Creates a bound `createPlugin` function that captures framework generics.

package/dist/index.mjs

@@ -740,6 +740,32 @@ function assertValidApi(frameworkId, pluginName, api) {
 function assertValidCreateState(frameworkId, pluginName, createState) {
 	if (createState !== void 0 && typeof createState !== "function") throw new TypeError(`[${frameworkId}] Plugin "${pluginName}" has invalid createState: expected a function.\n  Provide a function like: createState: ctx => ({ key: initialValue })`);
 }
+/** PluginInstance field names that cannot be used as helper names. */
+const PLUGIN_INSTANCE_RESERVED_KEYS = new Set([
+	"name",
+	"spec",
+	"_phantom"
+]);
+/**
+* Validates that `helpers` is a plain object of functions if provided.
+* Also rejects helper names that collide with PluginInstance properties.
+*
+* @param frameworkId - Framework identifier used in error messages.
+* @param pluginName - Validated plugin name.
+* @param helpers - Candidate helpers value from plugin spec.
+* @example
+* ```ts
+* assertValidHelpers("my-app", "router", { route: () => ({}) });
+* ```
+*/
+function assertValidHelpers(frameworkId, pluginName, helpers) {
+	if (helpers === void 0) return;
+	if (!isRecord(helpers)) throw new TypeError(`[${frameworkId}] Plugin "${pluginName}" has invalid helpers: expected an object.\n  Provide an object of functions: helpers: { myHelper: (...args) => result }`);
+	for (const [key, value] of Object.entries(helpers)) {
+		if (typeof value !== "function") throw new TypeError(`[${frameworkId}] Plugin "${pluginName}" has invalid helper "${key}": expected a function.\n  Each helper must be a function.`);
+		if (PLUGIN_INSTANCE_RESERVED_KEYS.has(key)) throw new TypeError(`[${frameworkId}] Plugin "${pluginName}" helper "${key}" conflicts with a PluginInstance property.\n  Choose a different helper name.`);
+	}
+}
 /**
 * Creates a bound `createPlugin` function that captures framework generics.
 *
@@ -778,10 +804,12 @@ function createPluginFactory(frameworkId) {
 		assertValidHooks(frameworkId, name, spec.hooks);
 		assertValidApi(frameworkId, name, spec.api);
 		assertValidCreateState(frameworkId, name, spec.createState);
+		assertValidHelpers(frameworkId, name, spec.helpers);
 		return {
 			name,
 			spec,
-			_phantom: {}
+			_phantom: {},
+			...isRecord(spec.helpers) ? spec.helpers : {}
 		};
 	};
 	return createPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/core",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.5",
   "author": "Alex Kucherenko",
   "repository": {
     "type": "git",