@embedpdf/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,567 @@
+import { Rotation, PdfDocumentObject, PdfPageObject, PdfPageObjectWithRotatedSize, PdfEngine } from '@embedpdf/models';
+
+/** Represents an action with a type and optional payload */
+interface Action {
+    type: string;
+    payload?: any;
+}
+/** A reducer function that updates a specific state based on an action */
+type Reducer<State, Action> = (state: State, action: Action) => State;
+/**
+ * Represents the overall store state, with a typed core and plugin states
+ */
+interface StoreState<CoreState> {
+    core: CoreState;
+    plugins: Record<string, any>;
+}
+/**
+ * The signature of a main-store listener. You now receive:
+ * - `action`    => The action that was dispatched
+ * - `newState` => The store state *after* the update
+ * - `oldState` => The store state *before* the update
+ */
+type StoreListener<CoreState> = (action: Action, newState: StoreState<CoreState>, oldState: StoreState<CoreState>) => void;
+/**
+ * The signature of a plugin-store listener. You now receive:
+ * - `action`         => The action that was dispatched
+ * - `newPluginState` => The plugin state *after* the update
+ * - `oldPluginState` => The plugin state *before* the update
+ */
+type PluginListener = (action: Action, newPluginState: any, oldPluginState: any) => void;
+
+/**
+ * A type-safe store handle for plugins, providing access to plugin-specific state and actions.
+ */
+declare class PluginStore<PluginState, PluginAction extends Action> {
+    private store;
+    private pluginId;
+    /**
+     * Initializes the PluginStore with the main store and plugin ID.
+     * @param store The main store instance.
+     * @param pluginId The unique identifier for the plugin.
+     */
+    constructor(store: Store<any, any>, pluginId: string);
+    /**
+     * Gets the current state of the plugin.
+     * @returns The plugin's state.
+     */
+    getState(): PluginState;
+    /**
+     * Dispatches an action for the plugin and returns the *new* global state.
+     * If you only need the plugin’s updated state, call `getState()` afterward.
+     * @param action The action to dispatch.
+     * @returns The updated global store state (after plugin reducer).
+     */
+    dispatch(action: PluginAction): PluginState;
+    /**
+     * Subscribes to state changes only for this specific plugin.
+     * You now receive (action, newPluginState, oldPluginState) in the callback.
+     *
+     * @param listener The callback to invoke when plugin state changes.
+     * @returns A function to unsubscribe the listener.
+     */
+    subscribeToState(listener: (action: PluginAction, newState: PluginState, oldState: PluginState) => void): () => void;
+    /**
+     * Subscribes to a specific action type for the plugin.
+     * This still uses the main store's `onAction`, so you get the *global*
+     * old/new store states there. If you specifically want old/new plugin state,
+     * use `subscribeToState` instead.
+     *
+     * @param type The action type to listen for.
+     * @param handler The callback to invoke when the action occurs.
+     * @returns A function to unsubscribe the handler.
+     */
+    onAction<T extends PluginAction['type']>(type: T, handler: (action: Extract<PluginAction, {
+        type: T;
+    }>, state: PluginState, oldState: PluginState) => void): () => void;
+}
+
+/**
+ * A generic, type-safe store class managing core and plugin states, reducers, and subscriptions.
+ * @template CoreState The type of the core state.
+ * @template CoreAction The type of actions handled by core reducers (extends Action).
+ */
+declare class Store<CoreState, CoreAction extends Action = Action> {
+    initialCoreState: CoreState;
+    private state;
+    private coreReducer;
+    private pluginReducers;
+    private listeners;
+    private pluginListeners;
+    /**
+     * Initializes the store with the provided core state.
+     * @param reducer          The core reducer function
+     * @param initialCoreState The initial core state
+     */
+    constructor(reducer: Reducer<CoreState, CoreAction>, initialCoreState: CoreState);
+    /**
+     * Adds a reducer for a plugin-specific state.
+     * @param pluginId The unique identifier for the plugin.
+     * @param reducer The reducer function for the plugin state.
+     * @param initialState The initial state for the plugin.
+     */
+    addPluginReducer<PluginState>(pluginId: string, reducer: Reducer<PluginState, Action>, initialState: PluginState): void;
+    /**
+     * Dispatches an action *only* to the core reducer.
+     * Notifies the global store listeners with (action, newState, oldState).
+     *
+     * @param action The action to dispatch, typed as CoreAction
+     * @returns The updated *global* store state
+     */
+    dispatchToCore(action: CoreAction): StoreState<CoreState>;
+    /**
+     * Dispatches an action *only* to a specific plugin.
+     * Optionally notifies global store listeners if `notifyGlobal` is true.
+     * Always notifies plugin-specific listeners with (action, newPluginState, oldPluginState).
+     *
+     * @param pluginId   The plugin identifier
+     * @param action     The plugin action to dispatch
+     * @param notifyGlobal Whether to also notify global store listeners
+     * @returns The updated *global* store state
+     */
+    dispatchToPlugin<PluginAction extends Action>(pluginId: string, action: PluginAction, notifyGlobal?: boolean): any;
+    /**
+     * Dispatches an action to update the state using:
+     * - the core reducer (if it's a CoreAction)
+     * - *all* plugin reducers (regardless of action type), with no global notify for each plugin
+     *
+     * Returns the new *global* store state after all reducers have processed the action.
+     *
+     * @param action The action to dispatch (can be CoreAction or any Action).
+     */
+    dispatch(action: CoreAction | Action): StoreState<CoreState>;
+    /**
+     * Returns a shallow copy of the current state.
+     * @returns The current store state.
+     */
+    getState(): StoreState<CoreState>;
+    /**
+     * Subscribes a listener to *global* state changes.
+     * The callback signature is now (action, newState, oldState).
+     *
+     * @param listener The callback to invoke on state changes
+     * @returns A function to unsubscribe the listener
+     */
+    subscribe(listener: StoreListener<CoreState>): () => void;
+    /**
+     * Subscribes a listener to *plugin-specific* state changes.
+     * The callback signature is now (action, newPluginState, oldPluginState).
+     *
+     * @param pluginId The unique identifier for the plugin.
+     * @param listener The callback to invoke on plugin state changes.
+     * @returns A function to unsubscribe the listener.
+     */
+    subscribeToPlugin(pluginId: string, listener: PluginListener): () => void;
+    /**
+     * Subscribes to a specific action type (only from the core's action union).
+     * The callback signature is (action, newState, oldState).
+     *
+     * @param type The action type to listen for.
+     * @param handler The callback to invoke when the action occurs.
+     * @returns A function to unsubscribe the handler.
+     */
+    onAction<T extends CoreAction['type']>(type: T, handler: (action: Extract<CoreAction, {
+        type: T;
+    }>, state: StoreState<CoreState>, oldState: StoreState<CoreState>) => void): () => void;
+    /**
+     * Gets a PluginStore handle for a specific plugin.
+     * @param pluginId The unique identifier for the plugin.
+     * @returns A PluginStore instance for the plugin.
+     */
+    getPluginStore<PluginState, PluginAction extends Action>(pluginId: string): PluginStore<PluginState, PluginAction>;
+    /**
+     * Helper method to check if an action is a CoreAction.
+     * Adjust if you have a more refined way to differentiate CoreAction vs. any other Action.
+     */
+    private isCoreAction;
+    /**
+     * Destroy the store: drop every listener and plugin reducer
+     */
+    destroy(): void;
+}
+
+interface CoreState {
+    scale: number;
+    rotation: Rotation;
+    document: PdfDocumentObject | null;
+    pages: PdfPageObject[][];
+    loading: boolean;
+    error: string | null;
+}
+declare const initialCoreState: (config?: PluginRegistryConfig) => CoreState;
+
+declare const LOAD_DOCUMENT = "LOAD_DOCUMENT";
+declare const SET_DOCUMENT = "SET_DOCUMENT";
+declare const SET_DOCUMENT_ERROR = "SET_DOCUMENT_ERROR";
+declare const SET_SCALE = "SET_SCALE";
+declare const SET_ROTATION = "SET_ROTATION";
+declare const SET_PAGES = "SET_PAGES";
+interface LoadDocumentAction {
+    type: typeof LOAD_DOCUMENT;
+}
+interface SetDocumentAction {
+    type: typeof SET_DOCUMENT;
+    payload: PdfDocumentObject;
+}
+interface SetDocumentErrorAction {
+    type: typeof SET_DOCUMENT_ERROR;
+    payload: string;
+}
+interface SetScaleAction {
+    type: typeof SET_SCALE;
+    payload: number;
+}
+interface SetRotationAction {
+    type: typeof SET_ROTATION;
+    payload: Rotation;
+}
+interface SetPagesAction {
+    type: typeof SET_PAGES;
+    payload: PdfPageObject[][];
+}
+type DocumentAction = LoadDocumentAction | SetDocumentAction | SetDocumentErrorAction | SetScaleAction | SetRotationAction | SetPagesAction;
+type CoreAction = DocumentAction;
+declare const loadDocument: () => CoreAction;
+declare const setDocument: (document: PdfDocumentObject) => CoreAction;
+declare const setDocumentError: (error: string) => CoreAction;
+declare const setScale: (scale: number) => CoreAction;
+declare const setRotation: (rotation: Rotation) => CoreAction;
+declare const setPages: (pages: PdfPageObject[][]) => CoreAction;
+
+declare const getPagesWithRotatedSize: (state: CoreState) => PdfPageObjectWithRotatedSize[][];
+
+interface IPlugin<TConfig = unknown> {
+    id: string;
+    initialize?(config: TConfig): Promise<void>;
+    destroy?(): Promise<void> | void;
+    provides?(): any;
+    postInitialize?(): Promise<void>;
+    ready?(): Promise<void>;
+}
+interface BasePluginConfig {
+    enabled?: boolean;
+}
+interface PluginRegistryConfig {
+    rotation?: Rotation;
+    scale?: number;
+}
+interface PluginManifest<TConfig = unknown> {
+    id: string;
+    name: string;
+    version: string;
+    provides: string[];
+    requires: string[];
+    optional: string[];
+    defaultConfig: TConfig;
+    metadata?: {
+        description?: string;
+        author?: string;
+        homepage?: string;
+        [key: string]: unknown;
+    };
+}
+interface PluginPackage<T extends IPlugin<TConfig>, TConfig = unknown, TState = unknown, TAction extends Action = Action> {
+    manifest: PluginManifest<TConfig>;
+    create(registry: PluginRegistry, engine: PdfEngine, config: TConfig): T;
+    reducer: Reducer<TState, TAction>;
+    initialState: TState | ((coreState: CoreState, config: TConfig) => TState);
+}
+type PluginStatus = 'registered' | 'active' | 'error' | 'disabled' | 'unregistered';
+interface PluginBatchRegistration<T extends IPlugin<TConfig>, TConfig = unknown, TState = unknown, TAction extends Action = Action> {
+    package: PluginPackage<T, TConfig, TState, TAction>;
+    config?: Partial<TConfig>;
+}
+interface GlobalStoreState<TPlugins extends Record<string, any> = {}> {
+    core: CoreState;
+    plugins: TPlugins;
+}
+
+declare class PluginRegistry {
+    private plugins;
+    private manifests;
+    private capabilities;
+    private status;
+    private resolver;
+    private configurations;
+    private engine;
+    private engineInitialized;
+    private store;
+    private initPromise;
+    private pendingRegistrations;
+    private processingRegistrations;
+    private initialized;
+    private isInitializing;
+    private initialCoreState;
+    private pluginsReadyPromise;
+    private destroyed;
+    constructor(engine: PdfEngine, config?: PluginRegistryConfig);
+    /**
+     * Ensure engine is initialized before proceeding
+     */
+    private ensureEngineInitialized;
+    /**
+     * Register a plugin without initializing it
+     */
+    registerPlugin<TPlugin extends IPlugin<TConfig>, TConfig = unknown, TState = unknown, TAction extends Action = Action>(pluginPackage: PluginPackage<TPlugin, TConfig, TState, TAction>, config?: Partial<TConfig>): void;
+    /**
+     * Get the central store instance
+     */
+    getStore(): Store<CoreState, CoreAction>;
+    /**
+     * Get the engine instance
+     */
+    getEngine(): PdfEngine;
+    /**
+     * Get a promise that resolves when all plugins are ready
+     */
+    pluginsReady(): Promise<void>;
+    /**
+     * INITIALISE THE REGISTRY – runs once no-matter-how-many calls   *
+     */
+    initialize(): Promise<void>;
+    /**
+     * Initialize a single plugin with all necessary checks
+     */
+    private initializePlugin;
+    getPluginConfig<TConfig>(pluginId: string): TConfig;
+    private validateConfig;
+    updatePluginConfig<TConfig>(pluginId: string, config: Partial<TConfig>): Promise<void>;
+    /**
+     * Register multiple plugins at once
+     */
+    registerPluginBatch(registrations: PluginBatchRegistration<IPlugin<any>, any, any, any>[]): void;
+    /**
+     * Unregister a plugin
+     */
+    unregisterPlugin(pluginId: string): Promise<void>;
+    /**
+     * Get a plugin instance
+     * @param pluginId The ID of the plugin to get
+     * @returns The plugin instance or null if not found
+     */
+    getPlugin<T extends IPlugin>(pluginId: string): T | null;
+    /**
+     * Get a plugin that provides a specific capability
+     * @param capability The capability to get a provider for
+     * @returns The plugin providing the capability or null if not found
+     */
+    getCapabilityProvider(capability: string): IPlugin | null;
+    /**
+     * Check if a capability is available
+     */
+    hasCapability(capability: string): boolean;
+    /**
+     * Get all registered plugins
+     */
+    getAllPlugins(): IPlugin[];
+    /**
+     * Get plugin status
+     */
+    getPluginStatus(pluginId: string): PluginStatus;
+    /**
+     * Validate plugin object
+     */
+    private validatePlugin;
+    /**
+     * Validate plugin manifest
+     */
+    private validateManifest;
+    isDestroyed(): boolean;
+    /**
+     * DESTROY EVERYTHING – waits for any ongoing initialise(), once  *
+     */
+    destroy(): Promise<void>;
+}
+
+declare class DependencyResolver {
+    private dependencyGraph;
+    addNode(id: string, dependencies?: string[]): void;
+    private hasCircularDependencies;
+    resolveLoadOrder(): string[];
+}
+
+/**
+ * Helper function to create a properly typed plugin registration
+ */
+declare function createPluginRegistration<T extends IPlugin<TConfig>, TConfig, TState, TAction extends Action>(pluginPackage: PluginPackage<T, TConfig, TState, TAction>, config?: Partial<TConfig>): PluginBatchRegistration<T, TConfig, any, any>;
+
+declare class PluginRegistrationError extends Error {
+    constructor(message: string);
+}
+declare class PluginNotFoundError extends Error {
+    constructor(message: string);
+}
+declare class CircularDependencyError extends Error {
+    constructor(message: string);
+}
+declare class CapabilityNotFoundError extends Error {
+    constructor(message: string);
+}
+declare class CapabilityConflictError extends Error {
+    constructor(message: string);
+}
+declare class PluginInitializationError extends Error {
+    constructor(message: string);
+}
+declare class PluginConfigurationError extends Error {
+    constructor(message: string);
+}
+
+interface StateChangeHandler<TState> {
+    (state: TState): void;
+}
+declare abstract class BasePlugin<TConfig = unknown, TCapability = unknown, TState = unknown, TAction extends Action = Action> implements IPlugin<TConfig> {
+    readonly id: string;
+    protected registry: PluginRegistry;
+    static readonly id: string;
+    protected pluginStore: PluginStore<TState, TAction>;
+    protected coreStore: Store<CoreState, CoreAction>;
+    private debouncedActions;
+    private unsubscribeFromState;
+    private unsubscribeFromCoreStore;
+    private _capability?;
+    private readyPromise;
+    private readyResolve;
+    constructor(id: string, registry: PluginRegistry);
+    /** Construct the public capability (called once & cached). */
+    protected abstract buildCapability(): TCapability;
+    provides(): Readonly<TCapability>;
+    /**
+     * Initialize plugin with config
+     */
+    abstract initialize(config: TConfig): Promise<void>;
+    /**
+     *  Get a copy of the current state
+     */
+    protected get state(): Readonly<TState>;
+    /**
+     *  Get a copy of the current core state
+     */
+    protected get coreState(): Readonly<StoreState<CoreState>>;
+    /**
+     * @deprecated  use `this.state` Get a copy of the current state
+     */
+    protected getState(): TState;
+    /**
+     * @deprecated  use `this.coreState` Get a copy of the current core state
+     */
+    protected getCoreState(): StoreState<CoreState>;
+    /**
+     * Core Dispatch
+     */
+    protected dispatchCoreAction(action: CoreAction): StoreState<CoreState>;
+    /**
+     * Dispatch an action
+     */
+    protected dispatch(action: TAction): TState;
+    /**
+     * Dispatch an action with debouncing to prevent rapid repeated calls
+     * @param action The action to dispatch
+     * @param debounceTime Time in ms to debounce (default: 100ms)
+     * @returns boolean indicating whether the action was dispatched or debounced
+     */
+    protected debouncedDispatch(action: TAction, debounceTime?: number): boolean;
+    /**
+     * Subscribe to state changes
+     */
+    protected subscribe(listener: (action: TAction, state: TState) => void): () => void;
+    /**
+     * Subscribe to core store changes
+     */
+    protected subscribeToCoreStore(listener: (action: Action, state: StoreState<CoreState>) => void): () => void;
+    /**
+     * Called when the plugin store state is updated
+     * @param oldState Previous state
+     * @param newState New state
+     */
+    protected onStoreUpdated(oldState: TState, newState: TState): void;
+    /**
+     * Called when the core store state is updated
+     * @param oldState Previous state
+     * @param newState New state
+     */
+    protected onCoreStoreUpdated(oldState: StoreState<CoreState>, newState: StoreState<CoreState>): void;
+    /**
+     * Cleanup method to be called when plugin is being destroyed
+     */
+    destroy(): void;
+    /**
+     * Returns a promise that resolves when the plugin is ready
+     */
+    ready(): Promise<void>;
+    /**
+     * Mark the plugin as ready
+     */
+    protected markReady(): void;
+    /**
+     * Reset the ready state (useful for plugins that need to reinitialize)
+     */
+    protected resetReady(): void;
+}
+
+type EventHandler<T> = (data: T) => void;
+interface BaseEventControlOptions {
+    wait: number;
+}
+interface DebounceOptions extends BaseEventControlOptions {
+    mode: 'debounce';
+}
+interface ThrottleOptions extends BaseEventControlOptions {
+    mode: 'throttle';
+    throttleMode?: 'leading-trailing' | 'trailing';
+}
+type EventControlOptions = DebounceOptions | ThrottleOptions;
+declare class EventControl<T> {
+    private handler;
+    private options;
+    private timeoutId?;
+    private lastRun;
+    constructor(handler: EventHandler<T>, options: EventControlOptions);
+    handle: (data: T) => void;
+    private debounce;
+    private throttle;
+    destroy(): void;
+}
+
+type Listener<T = any> = (value: T) => void;
+type Unsubscribe = () => void;
+type EventHook<T = any> = ((listener: Listener<T>) => Unsubscribe) | ((listener: Listener<T>, options?: EventControlOptions) => Unsubscribe);
+interface Emitter<T = any> {
+    emit(value?: T): void;
+    on(listener: Listener<T>): Unsubscribe;
+    off(listener: Listener<T>): void;
+    clear(): void;
+}
+declare function createEmitter<T = any>(): Emitter<T>;
+interface BehaviorEmitter<T = any> extends Omit<Emitter<T>, 'on' | 'off'> {
+    readonly value?: T;
+    on: EventHook<T>;
+    off(listener: Listener<T>): void;
+    select<U>(selector: (v: T) => U, equality?: (a: U, b: U) => boolean): EventHook<U>;
+}
+declare function createBehaviorEmitter<T = any>(initial?: T, equality?: (a: T, b: T) => boolean): BehaviorEmitter<T>;
+
+/**
+ * Restrict a numeric value to the inclusive range [min, max].
+ *
+ * @example
+ *   clamp( 5, 0, 10)  // 5
+ *   clamp(-3, 0, 10)  // 0
+ *   clamp(17, 0, 10)  // 10
+ */
+declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Deeply compares two values (objects, arrays, primitives)
+ * with the following rules:
+ *  - Objects are compared ignoring property order.
+ *  - Arrays are compared ignoring element order (multiset comparison).
+ *  - Primitives are compared by strict equality.
+ *  - null/undefined are treated as normal primitives.
+ *
+ * @param a First value
+ * @param b Second value
+ * @param visited Used internally to detect cycles
+ */
+declare function arePropsEqual(a: any, b: any, visited?: Set<any>): boolean;
+
+export { type Action, type BaseEventControlOptions, BasePlugin, type BasePluginConfig, type BehaviorEmitter, CapabilityConflictError, CapabilityNotFoundError, CircularDependencyError, type CoreAction, type CoreState, type DebounceOptions, DependencyResolver, type DocumentAction, type Emitter, EventControl, type EventControlOptions, type EventHandler, type EventHook, type GlobalStoreState, type IPlugin, LOAD_DOCUMENT, type Listener, type LoadDocumentAction, type PluginBatchRegistration, PluginConfigurationError, PluginInitializationError, type PluginListener, type PluginManifest, PluginNotFoundError, type PluginPackage, PluginRegistrationError, PluginRegistry, type PluginRegistryConfig, type PluginStatus, type Reducer, SET_DOCUMENT, SET_DOCUMENT_ERROR, SET_PAGES, SET_ROTATION, SET_SCALE, type SetDocumentAction, type SetDocumentErrorAction, type SetPagesAction, type SetRotationAction, type SetScaleAction, type StateChangeHandler, type StoreListener, type StoreState, type ThrottleOptions, type Unsubscribe, arePropsEqual, clamp, createBehaviorEmitter, createEmitter, createPluginRegistration, getPagesWithRotatedSize, initialCoreState, loadDocument, setDocument, setDocumentError, setPages, setRotation, setScale };