/** * PluginHandle — Opaque branded handle and output key utilities for plugin instances. * * Extracted into its own module to break circular dependencies: * both block_storage.ts and plugin_model.ts can import from here * without depending on each other. * * @module plugin_handle */ import type { Branded } from "@milaboratories/helpers"; /** * Phantom-only base type for constraining PluginHandle's type parameter. * * PluginFactory has create() → PluginInstance with function properties, making it invariant * under strictFunctionTypes. PluginFactoryLike exposes only the covariant `__types` phantom, * avoiding the contravariance chain. Handles only need `__types` for type extraction. * * PluginFactory extends PluginFactoryLike, so every concrete factory satisfies this constraint. */ export interface PluginFactoryLike< Data extends Record = Record, Params extends undefined | Record = undefined | Record, Outputs extends Record = Record, ModelServices = unknown, UiServices = unknown, > { readonly __types?: { data: Data; params: Params; outputs: Outputs; modelServices: ModelServices; uiServices: UiServices; }; } /** Extract the Data type from a PluginFactoryLike phantom. */ export type InferFactoryData = NonNullable< F extends PluginFactoryLike ? D : Record >; /** Extract the Params type from a PluginFactoryLike phantom. */ export type InferFactoryParams = NonNullable< F extends PluginFactoryLike ? P : undefined >; /** Extract the Outputs type from a PluginFactoryLike phantom. */ export type InferFactoryOutputs = NonNullable< F extends PluginFactoryLike ? O : Record >; /** Extract the pre-resolved model services type from a PluginFactoryLike phantom. */ export type InferFactoryModelServices = F extends PluginFactoryLike ? ModelServices : {}; /** Extract the pre-resolved UI services type from a PluginFactoryLike phantom. */ export type InferFactoryUiServices = F extends PluginFactoryLike ? UiServices : {}; /** * Derive a typed PluginHandle from a PluginFactory type. * Normalizes the brand to data/params/outputs/services (strips config) so handles * from InferPluginUiEntries match handles from InferPluginHandle. */ export type InferPluginHandle = NonNullable< F extends PluginFactoryLike< infer Data, infer Params, infer Outputs, infer ModelServices, infer UiServices > ? PluginHandle> : PluginHandle >; /** * Opaque handle for a plugin instance. Runtime value is the plugin instance ID string. * Branded with factory phantom `F` for type-safe data/outputs extraction. * Constrained with PluginFactoryLike (not PluginFactory) to avoid variance issues. */ export type PluginHandle = Branded; const PLUGIN_OUTPUT_PREFIX = "plugin-output#"; /** Construct the output key for a plugin output in the block outputs map. */ export function pluginOutputKey( handle: PluginHandle, outputKey: string, ): string { return `${PLUGIN_OUTPUT_PREFIX}${handle}#${outputKey}`; } /** Check whether an output key belongs to a plugin (vs block-level output). */ export function isPluginOutputKey(key: string): boolean { return key.startsWith(PLUGIN_OUTPUT_PREFIX); } /** Get the prefix used for all outputs of a specific plugin instance. */ export function pluginOutputPrefix(handle: PluginHandle): string { return pluginOutputKey(handle, ""); }