@feasibleone/blong 1.14.0 → 1.16.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.16.0](https://github.com/feasibleone/blong/compare/blong-v1.15.0...blong-v1.16.0) (2026-04-10)
+
+
+### Features
+
+* blong-ui ([9ca1281](https://github.com/feasibleone/blong/commit/9ca1281c0178c69dfc722bc4a5978f649bc1fa0d))
+
+## [1.15.0](https://github.com/feasibleone/blong/compare/blong-v1.14.0...blong-v1.15.0) (2026-04-01)
+
+
+### Features
+
+* implement ConfigRuntime for hot configuration reload ([#115](https://github.com/feasibleone/blong/issues/115)) ([61bab7c](https://github.com/feasibleone/blong/commit/61bab7ce8587bf83d72fe80138aaef68943f21c4))
+* unified test and handlers ([#117](https://github.com/feasibleone/blong/issues/117)) ([bf0ed96](https://github.com/feasibleone/blong/commit/bf0ed96c5df3d949fa225dd8a30fc25698a7855a))
+
 ## [1.14.0](https://github.com/feasibleone/blong/compare/blong-v1.13.0...blong-v1.14.0) (2026-03-29)
 
 

package/dist/types.d.ts

@@ -17625,6 +17625,22 @@ export type Config<T, C> = {
 	logLevel: Parameters<ILog["logger"]>[0];
 	namespace: string | string[];
 	imports: string | RegExp | (string | RegExp)[];
+	/**
+	 * Strip this many dot-separated namespace segments from the incoming method
+	 * name before looking up and calling a local handler.  Useful when the
+	 * adapter handles a namespace prefix (e.g. `backend`) that must be removed
+	 * before the real handler name is used.
+	 *
+	 * Only applied when the method name does NOT contain a `/` separator
+	 * (the `/` form is auto-stripped by `methodPath` already).
+	 */
+	stripNamespace?: number;
+	/**
+	 * Prepend this namespace segment (dot-separated) to the outgoing method
+	 * name when dispatching.  This is the dot-notation counterpart of the
+	 * existing `destination` field (which uses `/` as separator).
+	 */
+	appendNamespace?: string;
 } & T;
 export type RemoteMethod = (...params: unknown[]) => Promise<unknown>;
 export interface IRemote {
@@ -17640,6 +17656,7 @@ export interface IRpcServer {
 	unregister: (methods: string[], namespace: string, reply: boolean) => void;
 	start: () => Promise<IRpcServer>;
 	stop: () => Promise<IRpcServer>;
+	setAttachCheckpoint?: (fn: ((meta: IMeta) => void) | undefined) => void;
 }
 export interface ILocal {
 	register: (methods: object, namespace: string, reply: boolean, pkg: {
@@ -17683,6 +17700,7 @@ export interface IRegistry {
 	methods: Map<string, Handlers>;
 	modules: Map<string | symbol, IRegistry[]>;
 	createPort: (id: string) => Promise<ReturnType<IAdapterFactory>>;
+	getPort: (id: string) => ReturnType<IAdapterFactory> | undefined;
 	replaceHandlers: (id: string, handlers: object) => Promise<void>;
 	loadApi: (id: string, def: {
 		namespace: Record<string, string | string[]>;
@@ -17725,6 +17743,7 @@ export interface IApi {
 	utLog: {
 		createLog: ILog["logger"];
 	};
+	attachCheckpoint?: (meta: IMeta) => void;
 	handlers?: (api: {
 		utError: IError;
 		remote: IRemote;
@@ -17801,6 +17820,21 @@ export interface IAdapter<T, C> {
 		waiting: unknown;
 		buffer: unknown;
 	}) => void;
+	/**
+	 * Optional lifecycle hook called when configuration changes.
+	 * When present, the framework calls this instead of a full stop+start cycle.
+	 * The adapter should inspect `diff` and only recreate the resources that
+	 * actually changed (e.g. destroy and rebuild the DB connection pool when
+	 * the `knex` sub-key is in the diff, but leave everything else intact).
+	 *
+	 * @param diff   Flat map of dotted config paths to `{prev, next}` pairs
+	 * @param next   The full new effective config snapshot (via proxy)
+	 * @param prev   The full previous effective config snapshot
+	 */
+	configChanged?: (diff: Map<string, {
+		prev: unknown;
+		next: unknown;
+	}>, next: object, prev: object) => Promise<void>;
 }
 export interface IAdapterFactory<T = Record<string, unknown>, C = Record<string, unknown>> {
 	config?: Config<T, C> | false;
@@ -17878,6 +17912,13 @@ export interface IMeta {
 	};
 	gateway?: object;
 	validation?: unknown;
+	name?: string;
+	checkpoint?: CheckpointFn;
+	checkpoints?: Array<{
+		name: string;
+		data?: unknown;
+		timestamp: number;
+	}>;
 }
 export type HRTime = [
 	number,
@@ -18001,18 +18042,22 @@ export type ThenableProxy = Promise<unknown> & {
 export type ChainStep = ((assert: typeof Assert, context: {
 	$meta: IMeta;
 } & Record<string, Promise<unknown[]> & ThenableProxy>) => Promise<object>) | object;
+export type CheckpointFn = (this: IMeta, name: string, data?: unknown) => void;
 export interface ILib {
 	type: typeof Type;
 	error: <T>(errors: T) => Record<keyof T, (params?: unknown, $meta?: IMeta) => ITypedError>;
 	rename: <T extends object>(object: T, name: string) => T & {
 		name: string;
 	};
+	/** @deprecated The framework now auto-names step arrays from handler names. */
 	group: (name: string) => (handlers: ChainStep[]) => ChainStep[] & {
 		name: string;
 	};
+	assert: typeof Assert | undefined;
 	ulid: () => string;
 	uuid4: () => string;
 	uuid7: () => string;
+	setProperty: (obj: Record<string, unknown>, path: string, value: unknown) => void;
 	merge<T, S1>(target: T, source: S1): T & S1;
 	merge<T, S1, S2>(target: T, source1: S1, source2: S2): T & S1 & S2;
 	merge<T, S1, S2, S3>(target: T, source1: S1, source2: S2, source3: S3): T & S1 & S2 & S3;
@@ -18109,6 +18154,65 @@ export declare abstract class Internal {
 	start(...params: unknown[]): Promise<unknown>;
 }
 export declare const handler: <T = Record<string, unknown>, C = AdapterContext>(definition: Definition<T, C>) => Definition<T, C>;
+/**
+ * Browser-side equivalent of `handler`.  Use this to define a component handler
+ * in a realm's `component/` layer.  Functionally identical to `handler` — the
+ * distinction is semantic and makes intent clear in code review.
+ *
+ * The inner function should return a map whose keys are dot-notation method names
+ * (e.g. `'coral.browse'`) and values are async functions that return component
+ * metadata `{title, permission, icon, component: async () => ReactComponent}`.
+ *
+ * @example
+ * ```ts
+ * export default componentHandler(blong => function coralBrowse() {
+ *   return {
+ *     'coral.browse': async () => ({
+ *       title: 'Browse Corals',
+ *       permission: 'marine.coral.browse',
+ *       component: async () => (await import('./CoralBrowse.js')).default,
+ *     }),
+ *   };
+ * });
+ * ```
+ */
+export declare const componentHandler: <T = Record<string, unknown>, C = AdapterContext>(definition: Definition<T, C>) => Definition<T, C>;
+/** Action definition for use with `defineActions`. */
+export interface IActionDef {
+	title?: string;
+	permission?: string;
+	icon?: string;
+	/** Lazy-load a page component (page action). */
+	component?: () => Promise<unknown>;
+	/** Bus method name to invoke (query or mutation action). */
+	method?: string;
+	/** When true the action mutates data and should invalidate related caches. */
+	mutates?: boolean;
+	/** Action names whose query caches should be invalidated on success. */
+	invalidates?: string[];
+	/** Static params merged into every invocation. */
+	params?: Record<string, unknown> | ((params: Record<string, unknown>) => Record<string, unknown>);
+}
+/**
+ * Register action metadata for a realm's browser layer.
+ *
+ * Returns a handler-compatible function that the blong framework loads from
+ * the realm's `actions/` or `action/` folder.  Each entry in `actions` is
+ * wrapped in a no-argument function so the framework can call it as a method.
+ *
+ * @example
+ * ```ts
+ * // marine/actions/index.ts
+ * export default defineActions({
+ *   'marine.coral.browse': {
+ *     title: 'Browse Corals',
+ *     permission: 'marine.coral.browse',
+ *     component: () => import('./components/CoralBrowse.js'),
+ *   },
+ * });
+ * ```
+ */
+export declare const defineActions: (actions: Record<string, IActionDef>) => ((_blong: unknown) => Record<string, () => IActionDef>);
 export declare const library: <T = Record<string, unknown>>(definition: Lib<T>) => Lib<T>;
 export declare const validation: (validation: ValidationDefinition) => ValidationDefinition;
 export declare const api: (api: ApiDefinition) => ApiDefinition;
@@ -18125,6 +18229,8 @@ export type Kinds = "lib" | "validation" | "api" | "solution" | "server" | "brow
 export declare const kind: (what: {}) => Kinds | undefined;
 declare const _default: {
 	handler: <T = Record<string, unknown>, C = AdapterContext>(definition: Definition<T, C>) => Definition<T, C>;
+	componentHandler: <T = Record<string, unknown>, C = AdapterContext>(definition: Definition<T, C>) => Definition<T, C>;
+	defineActions: (actions: Record<string, IActionDef>) => ((_blong: unknown) => Record<string, () => IActionDef>);
 	library: <T = Record<string, unknown>>(definition: Lib<T>) => Lib<T>;
 	validation: (validation: ValidationDefinition) => ValidationDefinition;
 	api: (api: ApiDefinition) => ApiDefinition;

package/dist/types.js

@@ -21,6 +21,49 @@ export class Internal {
     }
 }
 export const handler = (definition) => Object.defineProperty(definition, Kind, { value: 'handler' });
+/**
+ * Browser-side equivalent of `handler`.  Use this to define a component handler
+ * in a realm's `component/` layer.  Functionally identical to `handler` — the
+ * distinction is semantic and makes intent clear in code review.
+ *
+ * The inner function should return a map whose keys are dot-notation method names
+ * (e.g. `'coral.browse'`) and values are async functions that return component
+ * metadata `{title, permission, icon, component: async () => ReactComponent}`.
+ *
+ * @example
+ * ```ts
+ * export default componentHandler(blong => function coralBrowse() {
+ *   return {
+ *     'coral.browse': async () => ({
+ *       title: 'Browse Corals',
+ *       permission: 'marine.coral.browse',
+ *       component: async () => (await import('./CoralBrowse.js')).default,
+ *     }),
+ *   };
+ * });
+ * ```
+ */
+export const componentHandler = (definition) => Object.defineProperty(definition, Kind, { value: 'handler' });
+/**
+ * Register action metadata for a realm's browser layer.
+ *
+ * Returns a handler-compatible function that the blong framework loads from
+ * the realm's `actions/` or `action/` folder.  Each entry in `actions` is
+ * wrapped in a no-argument function so the framework can call it as a method.
+ *
+ * @example
+ * ```ts
+ * // marine/actions/index.ts
+ * export default defineActions({
+ *   'marine.coral.browse': {
+ *     title: 'Browse Corals',
+ *     permission: 'marine.coral.browse',
+ *     component: () => import('./components/CoralBrowse.js'),
+ *   },
+ * });
+ * ```
+ */
+export const defineActions = (actions) => Object.defineProperty((_blong) => Object.fromEntries(Object.entries(actions).map(([key, value]) => [key, () => value])), Kind, { value: 'handler' });
 export const library = (definition) => Object.defineProperty(definition, Kind, { value: 'lib' });
 export const validation = (validation) => Object.defineProperty(validation, Kind, { value: 'validation' });
 export const api = (api) => Object.defineProperty(api, Kind, { value: 'api' });
@@ -41,6 +84,8 @@ export const orchestrator = (definition) => Object.defineProperty(definition, Ki
 export const kind = (what) => what[Kind];
 export default {
     handler,
+    componentHandler,
+    defineActions,
     library,
     validation,
     api,

package/dist/types.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "API and DRY focused RAD framework https://feasibleone.github.io/blong-docs",
   "keywords": [
     "blong",

package/types.ts

@@ -113,6 +113,22 @@ export type Config<T, C> = {
     logLevel: Parameters<ILog['logger']>[0];
     namespace: string | string[];
     imports: string | RegExp | (string | RegExp)[];
+    /**
+     * Strip this many dot-separated namespace segments from the incoming method
+     * name before looking up and calling a local handler.  Useful when the
+     * adapter handles a namespace prefix (e.g. `backend`) that must be removed
+     * before the real handler name is used.
+     *
+     * Only applied when the method name does NOT contain a `/` separator
+     * (the `/` form is auto-stripped by `methodPath` already).
+     */
+    stripNamespace?: number;
+    /**
+     * Prepend this namespace segment (dot-separated) to the outgoing method
+     * name when dispatching.  This is the dot-notation counterpart of the
+     * existing `destination` field (which uses `/` as separator).
+     */
+    appendNamespace?: string;
 } & T;
 
 export type RemoteMethod = (...params: unknown[]) => Promise<unknown>;
@@ -128,6 +144,7 @@ export interface IRpcServer {
     unregister: (methods: string[], namespace: string, reply: boolean) => void;
     start: () => Promise<IRpcServer>;
     stop: () => Promise<IRpcServer>;
+    setAttachCheckpoint?: (fn: ((meta: IMeta) => void) | undefined) => void;
 }
 
 export interface ILocal {
@@ -172,6 +189,7 @@ export interface IRegistry {
     methods: Map<string, Handlers>;
     modules: Map<string | symbol, IRegistry[]>;
     createPort: (id: string) => Promise<ReturnType<IAdapterFactory>>;
+    getPort: (id: string) => ReturnType<IAdapterFactory> | undefined;
     replaceHandlers: (id: string, handlers: object) => Promise<void>;
     loadApi: (
         id: string,
@@ -220,6 +238,7 @@ export interface IApi {
     utLog: {
         createLog: ILog['logger'];
     };
+    attachCheckpoint?: (meta: IMeta) => void;
     handlers?: (api: {utError: IError; remote: IRemote; type: typeof Type}) => {
         extends?:
             | string
@@ -303,6 +322,22 @@ export interface IAdapter<T, C> {
         what: unknown,
         context: {requests: unknown; waiting: unknown; buffer: unknown},
     ) => void;
+    /**
+     * Optional lifecycle hook called when configuration changes.
+     * When present, the framework calls this instead of a full stop+start cycle.
+     * The adapter should inspect `diff` and only recreate the resources that
+     * actually changed (e.g. destroy and rebuild the DB connection pool when
+     * the `knex` sub-key is in the diff, but leave everything else intact).
+     *
+     * @param diff   Flat map of dotted config paths to `{prev, next}` pairs
+     * @param next   The full new effective config snapshot (via proxy)
+     * @param prev   The full previous effective config snapshot
+     */
+    configChanged?: (
+        diff: Map<string, {prev: unknown; next: unknown}>,
+        next: object,
+        prev: object,
+    ) => Promise<void>;
 }
 
 export interface IAdapterFactory<T = Record<string, unknown>, C = Record<string, unknown>> {
@@ -382,6 +417,9 @@ export interface IMeta {
     };
     gateway?: object;
     validation?: unknown;
+    name?: string;
+    checkpoint?: CheckpointFn;
+    checkpoints?: Array<{name: string; data?: unknown; timestamp: number}>;
 }
 
 export type HRTime = [number, number];
@@ -520,14 +558,19 @@ export type ChainStep =
       ) => Promise<object>)
     | object;
 
+export type CheckpointFn = (this: IMeta, name: string, data?: unknown) => void;
+
 export interface ILib {
     type: typeof Type;
     error: <T>(errors: T) => Record<keyof T, (params?: unknown, $meta?: IMeta) => ITypedError>;
     rename: <T extends object>(object: T, name: string) => T & {name: string};
+    /** @deprecated The framework now auto-names step arrays from handler names. */
     group: (name: string) => (handlers: ChainStep[]) => ChainStep[] & {name: string};
+    assert: typeof Assert | undefined;
     ulid: () => string;
     uuid4: () => string;
     uuid7: () => string;
+    setProperty: (obj: Record<string, unknown>, path: string, value: unknown) => void;
     merge<T, S1>(target: T, source: S1): T & S1;
     merge<T, S1, S2>(target: T, source1: S1, source2: S2): T & S1 & S2;
     merge<T, S1, S2, S3>(target: T, source1: S1, source2: S2, source3: S3): T & S1 & S2 & S3;
@@ -653,6 +696,81 @@ export abstract class Internal {
 export const handler = <T = Record<string, unknown>, C = AdapterContext>(
     definition: Definition<T, C>,
 ): Definition<T, C> => Object.defineProperty(definition, Kind, {value: 'handler'});
+
+/**
+ * Browser-side equivalent of `handler`.  Use this to define a component handler
+ * in a realm's `component/` layer.  Functionally identical to `handler` — the
+ * distinction is semantic and makes intent clear in code review.
+ *
+ * The inner function should return a map whose keys are dot-notation method names
+ * (e.g. `'coral.browse'`) and values are async functions that return component
+ * metadata `{title, permission, icon, component: async () => ReactComponent}`.
+ *
+ * @example
+ * ```ts
+ * export default componentHandler(blong => function coralBrowse() {
+ *   return {
+ *     'coral.browse': async () => ({
+ *       title: 'Browse Corals',
+ *       permission: 'marine.coral.browse',
+ *       component: async () => (await import('./CoralBrowse.js')).default,
+ *     }),
+ *   };
+ * });
+ * ```
+ */
+export const componentHandler = <T = Record<string, unknown>, C = AdapterContext>(
+    definition: Definition<T, C>,
+): Definition<T, C> => Object.defineProperty(definition, Kind, {value: 'handler'});
+
+/** Action definition for use with `defineActions`. */
+export interface IActionDef {
+    title?: string;
+    permission?: string;
+    icon?: string;
+    /** Lazy-load a page component (page action). */
+    component?: () => Promise<unknown>;
+    /** Bus method name to invoke (query or mutation action). */
+    method?: string;
+    /** When true the action mutates data and should invalidate related caches. */
+    mutates?: boolean;
+    /** Action names whose query caches should be invalidated on success. */
+    invalidates?: string[];
+    /** Static params merged into every invocation. */
+    params?: Record<string, unknown> | ((params: Record<string, unknown>) => Record<string, unknown>);
+}
+
+/**
+ * Register action metadata for a realm's browser layer.
+ *
+ * Returns a handler-compatible function that the blong framework loads from
+ * the realm's `actions/` or `action/` folder.  Each entry in `actions` is
+ * wrapped in a no-argument function so the framework can call it as a method.
+ *
+ * @example
+ * ```ts
+ * // marine/actions/index.ts
+ * export default defineActions({
+ *   'marine.coral.browse': {
+ *     title: 'Browse Corals',
+ *     permission: 'marine.coral.browse',
+ *     component: () => import('./components/CoralBrowse.js'),
+ *   },
+ * });
+ * ```
+ */
+export const defineActions = (
+    actions: Record<string, IActionDef>,
+): ((_blong: unknown) => Record<string, () => IActionDef>) =>
+    Object.defineProperty(
+        (_blong: unknown) =>
+            Object.fromEntries(
+                Object.entries(actions).map(([key, value]) => [key, () => value]),
+            ),
+        Kind,
+        {value: 'handler'},
+    );
+
 export const library = <T = Record<string, unknown>>(definition: Lib<T>): Lib<T> =>
     Object.defineProperty(definition, Kind, {value: 'lib'});
 export const validation = (validation: ValidationDefinition): ValidationDefinition =>
@@ -709,6 +827,8 @@ export const kind = (what: {[Kind]: Kinds | undefined}): Kinds | undefined => wh
 
 export default {
     handler,
+    componentHandler,
+    defineActions,
     library,
     validation,
     api,