@routier/core 0.0.1-alpha.1

package/src/pipeline/TrampolinePipeline.ts

@@ -0,0 +1,437 @@
+import { CallbackResult, Result, ResultType } from "../results";
+
+/**
+ * Type definition for an asynchronous function that takes data and a callback.
+ * TIn: The input data type.
+ * TOut: The output data type (passed to the callback).
+ */
+export type Processor<TIn, TOut> = (data: TIn, callback: (result: TOut, error?: any) => void) => void;
+
+// Return type for a step execution: Either the next step function or null if waiting/done.
+type StepResult<TData> = TrampolineStep<TData> | null;
+type TrampolineStep<TData> = () => StepResult<TData>;
+
+export class TrampolinePipeline<TInitial, TCurrent = TInitial> {
+    private _list: Processor<any, any>[] = [];
+    private _hasErrored: boolean = false; // Flag to prevent calling done on error
+
+    filter<TFinal>(initialData: TInitial, done: (data: TFinal, error?: any) => void) {
+
+        this._hasErrored = false; // Reset error flag on new execution
+
+        if (this._list.length === 0) {
+            queueMicrotask(() => done(initialData as any as TFinal));
+            return;
+        }
+
+        let index = 0;
+        let currentData: any = initialData;
+        let isRunning = false; // Guard against overlapping trampoline calls
+
+        try {
+            // --- Revised Completion Logic --- (Moved up for clarity)
+            const finalStepSentinel = (): StepResult<any> => { // A special step function for the very end
+                // Only call done if no error has occurred
+                if (!this._hasErrored) {
+                    queueMicrotask(() => done(currentData as TFinal));
+                }
+                return null; // Stop the trampoline
+            };
+
+            const createStepRevised = (idx: number): TrampolineStep<any> => {
+                return () => {
+                    if (this._hasErrored) return null; // Stop if an error occurred elsewhere
+
+                    if (idx >= this._list.length) {
+                        return finalStepSentinel(); // Execute the dedicated final step
+                    }
+
+                    const processor = this._list[idx];
+                    // Initialize syncCallbackResult to null to satisfy StepResult type
+                    let syncCallbackResult: StepResult<any> = null;
+                    let calledSync = false;
+
+                    try {
+                        processor(currentData, (result, error) => {
+                            // --- Error Handling ---
+                            if (error) {
+                                console.error(`Error reported by processor at index ${idx}:`, error);
+                                this._hasErrored = true; // Set flag
+                                // Throw the error to be caught by outer try...catch blocks
+                                throw error;
+                            }
+                            // --- /Error Handling ---
+
+                            // If no error, proceed as before
+                            currentData = result;
+                            index = idx + 1; // Update index for the next step
+                            const nextStep = createStepRevised(index); // Use updated index
+
+                            if (isRunning) {
+                                // Callback was synchronous
+                                syncCallbackResult = nextStep; // Store next step function
+                                calledSync = true;
+                            } else {
+                                // Callback was asynchronous, restart trampoline
+                                trampoline(nextStep);
+                            }
+                        });
+                    } catch (error) {
+                        if (!this._hasErrored) { // Check flag to avoid double logging if error was from callback
+                            console.error(`Error thrown by processor at index ${idx} or its callback:`, error);
+                            this._hasErrored = true;
+                        }
+                        // Rethrow to be caught by the trampoline's catch block
+                        throw error;
+                    }
+
+                    if (calledSync) {
+                        // Return the next step function for the sync loop
+                        return syncCallbackResult;
+                    } else {
+                        // Pause trampoline for async, loop will stop as step returns null
+                        return null;
+                    }
+                };
+            };
+
+            // The trampoline loop
+            const trampoline = (step: TrampolineStep<any> | null) => {
+
+                if (isRunning) {
+                    return;
+                }
+
+                isRunning = true;
+                let currentStep = step;
+
+                while (typeof currentStep === 'function') {
+                    try {
+                        // Stop immediately if an error was flagged elsewhere
+                        if (this._hasErrored) {
+                            currentStep = null;
+                            break;
+                        }
+                        currentStep = currentStep(); // Execute step, get next step or null
+                    } catch (trampolineError) {
+                        // Catch errors propagated from step execution (processor or callback errors)
+                        if (!this._hasErrored) { // Avoid double logging
+                            console.error("Error during trampoline step execution:", trampolineError);
+                            this._hasErrored = true;
+                        }
+                        currentStep = null; // Stop the loop
+                        // We don't call `done` here because an error occurred.
+                        // The application should handle the uncaught exception if desired.
+                        break; // Explicitly break loop on error
+                    }
+                }
+                // Loop ends when currentStep is null or loop is broken by error
+                isRunning = false;
+
+                // Completion check is now handled by finalStepSentinel ensuring `done` isn't called on error.
+            };
+
+            // --- Start the process ---
+            index = 0; // Reset index
+            currentData = initialData; // Reset data
+            trampoline(createStepRevised(0)); // Start with the revised step creator
+        } catch (error: any) {
+            done(currentData, error);
+        }
+    }
+
+    pipe<TNext>(processor: Processor<TCurrent, TNext>) {
+        this._list.push(processor);
+        return this as unknown as TrampolinePipeline<TInitial, TNext>;
+    }
+
+    pipeEach(items: TCurrent[], fn: (payload: ResultType<TCurrent>, done: CallbackResult<TCurrent>) => void, map: (previous: ResultType<TCurrent>, current: ResultType<TCurrent>) => ResultType<TCurrent>) {
+        for (let i = 0, length = items.length; i < length; i++) {
+
+            this.pipe<ResultType<TCurrent>>((previous, done) => {
+
+                fn(map(previous as ResultType<TCurrent>, Result.success(items[i])), done);
+            });
+        }
+    }
+}
+
+export type AsyncUnitOfWork<TData, TResult> = (payload: TData, done: CallbackResult<TResult>) => void;
+export class AsyncPipeline<TData, TResult> {
+    private _list: [TData, AsyncUnitOfWork<TData, TResult>][] = [];
+    private _hasErrored: boolean = false; // Flag to prevent calling done on error
+
+    filter(done: CallbackResult<TResult[]>) {
+
+        this._hasErrored = false; // Reset error flag on new execution
+        let currentData: TResult[] = [];
+
+        if (this._list.length === 0) {
+            queueMicrotask(() => done(Result.success()));
+            return;
+        }
+
+        let index = 0;
+        let isRunning = false; // Guard against overlapping trampoline calls
+
+        try {
+            // --- Revised Completion Logic --- (Moved up for clarity)
+            const finalStepSentinel = (): StepResult<any> => { // A special step function for the very end
+                // Only call done if no error has occurred
+                if (!this._hasErrored) {
+                    queueMicrotask(() => done(Result.success(currentData)));
+                }
+                return null; // Stop the trampoline
+            };
+
+            const createStepRevised = (idx: number): TrampolineStep<any> => {
+                return () => {
+                    if (this._hasErrored) return null; // Stop if an error occurred elsewhere
+
+                    if (idx >= this._list.length) {
+                        return finalStepSentinel(); // Execute the dedicated final step
+                    }
+
+                    const [payload, processor] = this._list[idx];
+                    // Initialize syncCallbackResult to null to satisfy StepResult type
+                    let syncCallbackResult: StepResult<any> = null;
+                    let calledSync = false;
+
+                    try {
+                        processor(payload, (result) => {
+                            // --- Error Handling ---
+                            if (result.ok === Result.ERROR) {
+                                console.error(`Error reported by AsyncPipeline at index ${idx}:`, result.error);
+                                this._hasErrored = true; // Set flag
+                                // Throw the error to be caught by outer try...catch blocks
+                                throw result.error;
+                            }
+                            // --- /Error Handling ---
+
+                            // If no error, proceed as before
+                            currentData.push(result.data);
+                            index = idx + 1; // Update index for the next step
+                            const nextStep = createStepRevised(index); // Use updated index
+
+                            if (isRunning) {
+                                // Callback was synchronous
+                                syncCallbackResult = nextStep; // Store next step function
+                                calledSync = true;
+                            } else {
+                                // Callback was asynchronous, restart trampoline
+                                trampoline(nextStep);
+                            }
+                        });
+                    } catch (error) {
+                        if (!this._hasErrored) { // Check flag to avoid double logging if error was from callback
+                            console.error(`Error thrown by processor at index ${idx} or its callback:`, error);
+                            this._hasErrored = true;
+                        }
+                        // Rethrow to be caught by the trampoline's catch block
+                        throw error;
+                    }
+
+                    if (calledSync) {
+                        // Return the next step function for the sync loop
+                        return syncCallbackResult;
+                    } else {
+                        // Pause trampoline for async, loop will stop as step returns null
+                        return null;
+                    }
+                };
+            };
+
+            // The trampoline loop
+            const trampoline = (step: TrampolineStep<any> | null) => {
+
+                if (isRunning) {
+                    return;
+                }
+
+                isRunning = true;
+                let currentStep = step;
+
+                while (typeof currentStep === 'function') {
+                    try {
+                        // Stop immediately if an error was flagged elsewhere
+                        if (this._hasErrored) {
+                            currentStep = null;
+                            break;
+                        }
+                        currentStep = currentStep(); // Execute step, get next step or null
+                    } catch (trampolineError) {
+                        // Catch errors propagated from step execution (processor or callback errors)
+                        if (!this._hasErrored) { // Avoid double logging
+                            console.error("Error during trampoline step execution:", trampolineError);
+                            this._hasErrored = true;
+                        }
+                        currentStep = null; // Stop the loop
+                        // We don't call `done` here because an error occurred.
+                        // The application should handle the uncaught exception if desired.
+                        break; // Explicitly break loop on error
+                    }
+                }
+                // Loop ends when currentStep is null or loop is broken by error
+                isRunning = false;
+
+                // Completion check is now handled by finalStepSentinel ensuring `done` isn't called on error.
+            };
+
+            // --- Start the process ---
+            index = 0; // Reset index
+            trampoline(createStepRevised(0)); // Start with the revised step creator
+        } catch (error: any) {
+            done(Result.error(error));
+        }
+    }
+
+    pipe(data: TData, processor: AsyncUnitOfWork<TData, TResult>) {
+        this._list.push([data, processor]);
+    }
+
+    pipeEach(items: TData[], processor: AsyncUnitOfWork<TData, TResult>) {
+        for (let i = 0, length = items.length; i < length; i++) {
+            this.pipe(items[i], processor);
+        }
+    }
+}
+
+export type UnitOfWork = (done: CallbackResult<never>) => void;
+
+/**
+ * Processes functions with callbacks asynchronously.
+ * 
+ * This pipeline handles work items that contain callback functions,
+ * executing them in an asynchronous manner while maintaining proper
+ * flow control and error handling.
+ */
+export class WorkPipeline {
+    private unitsOfWork: UnitOfWork[] = [];
+    private _hasErrored: boolean = false; // Flag to prevent calling done on error
+
+    filter(done: CallbackResult<never>) {
+
+        this._hasErrored = false; // Reset error flag on new execution
+
+        if (this.unitsOfWork.length === 0) {
+            queueMicrotask(() => done(Result.success()));
+            return;
+        }
+
+        let index = 0;
+        let isRunning = false; // Guard against overlapping trampoline calls
+
+        try {
+            // --- Revised Completion Logic --- (Moved up for clarity)
+            const finalStepSentinel = (): StepResult<never> => { // A special step function for the very end
+                // Only call done if no error has occurred
+                if (!this._hasErrored) {
+                    queueMicrotask(() => done(Result.success()));
+                }
+                return null; // Stop the trampoline
+            };
+
+            const createStepRevised = (idx: number): TrampolineStep<any> => {
+                return () => {
+                    if (this._hasErrored) return null; // Stop if an error occurred elsewhere
+
+                    if (idx >= this.unitsOfWork.length) {
+                        return finalStepSentinel(); // Execute the dedicated final step
+                    }
+
+                    const processor = this.unitsOfWork[idx];
+                    // Initialize syncCallbackResult to null to satisfy StepResult type
+                    let syncCallbackResult: StepResult<any> = null;
+                    let calledSync = false;
+
+                    try {
+                        processor((result) => {
+                            // --- Error Handling ---
+                            if (result.ok === Result.ERROR) {
+                                console.error(`Error reported by AsyncPipeline at index ${idx}:`, result.error);
+                                this._hasErrored = true; // Set flag
+                                // Throw the error to be caught by outer try...catch blocks
+                                throw result.error;
+                            }
+                            // --- /Error Handling ---
+
+                            // If no error, proceed as before
+                            index = idx + 1; // Update index for the next step
+                            const nextStep = createStepRevised(index); // Use updated index
+
+                            if (isRunning) {
+                                // Callback was synchronous
+                                syncCallbackResult = nextStep; // Store next step function
+                                calledSync = true;
+                            } else {
+                                // Callback was asynchronous, restart trampoline
+                                trampoline(nextStep);
+                            }
+                        });
+                    } catch (error) {
+                        if (!this._hasErrored) { // Check flag to avoid double logging if error was from callback
+                            console.error(`Error thrown by processor at index ${idx} or its callback:`, error);
+                            this._hasErrored = true;
+                        }
+                        // Rethrow to be caught by the trampoline's catch block
+                        throw error;
+                    }
+
+                    if (calledSync) {
+                        // Return the next step function for the sync loop
+                        return syncCallbackResult;
+                    } else {
+                        // Pause trampoline for async, loop will stop as step returns null
+                        return null;
+                    }
+                };
+            };
+
+            // The trampoline loop
+            const trampoline = (step: TrampolineStep<any> | null) => {
+
+                if (isRunning) {
+                    return;
+                }
+
+                isRunning = true;
+                let currentStep = step;
+
+                while (typeof currentStep === 'function') {
+                    try {
+                        // Stop immediately if an error was flagged elsewhere
+                        if (this._hasErrored) {
+                            currentStep = null;
+                            break;
+                        }
+                        currentStep = currentStep(); // Execute step, get next step or null
+                    } catch (trampolineError) {
+                        // Catch errors propagated from step execution (processor or callback errors)
+                        if (!this._hasErrored) { // Avoid double logging
+                            console.error("Error during trampoline step execution:", trampolineError);
+                            this._hasErrored = true;
+                        }
+                        currentStep = null; // Stop the loop
+                        // We don't call `done` here because an error occurred.
+                        // The application should handle the uncaught exception if desired.
+                        break; // Explicitly break loop on error
+                    }
+                }
+                // Loop ends when currentStep is null or loop is broken by error
+                isRunning = false;
+
+                // Completion check is now handled by finalStepSentinel ensuring `done` isn't called on error.
+            };
+
+            // --- Start the process ---
+            index = 0; // Reset index
+            trampoline(createStepRevised(0)); // Start with the revised step creator
+        } catch (error: any) {
+            done(Result.error(error));
+        }
+    }
+
+    pipe(work: UnitOfWork) {
+        this.unitsOfWork.push(work);
+    }
+}

package/src/pipeline/index.ts

@@ -0,0 +1,2 @@
+export * from './SyncronousQueue';
+export * from './TrampolinePipeline';

package/src/plugins/EphemeralDataPlugin.ts

@@ -0,0 +1,132 @@
+import { assertIsNotNull } from '../assertions';
+import { BulkPersistResult } from '../collections';
+import { WorkPipeline } from '../pipeline';
+import { DbPluginBulkPersistEvent, DbPluginEvent, DbPluginQueryEvent, IDbPlugin, JsonTranslator } from '.';
+import { PluginEventCallbackPartialResult, PluginEventCallbackResult, PluginEventResult, Result } from '../results';
+import { CompiledSchema, InferCreateType } from '../schema';
+import { DeepPartial } from '../types';
+import { MemoryDataCollection } from '../collections/MemoryDataCollection';
+import { UnknownRecord } from '../utilities';
+
+export abstract class EphemeralDataPlugin implements IDbPlugin {
+
+    protected databaseName: string;
+
+    constructor(databaseName: string) {
+        this.databaseName = databaseName;
+    }
+
+    protected abstract resolveCollection<TEntity extends {}>(schema: CompiledSchema<TEntity>): MemoryDataCollection;
+
+    bulkPersist(event: DbPluginBulkPersistEvent, done: PluginEventCallbackPartialResult<BulkPersistResult>) {
+        try {
+            const pipeline = new WorkPipeline();
+            const bulkPersistResult = event.operation.toResult();
+
+            for (const [schemaId, changes] of event.operation) {
+
+                pipeline.pipe((d) => {
+                    try {
+
+                        const { adds, hasItems, removes, updates } = changes;
+
+                        if (hasItems === false) {
+                            d(Result.success());
+                            return;
+                        }
+
+                        const result = bulkPersistResult.get(schemaId);
+                        const schema = event.schemas.get(schemaId);
+
+                        assertIsNotNull(schema);
+
+                        const collection = this.resolveCollection(schema);
+                        collection.load(readResult => {
+
+                            if (readResult.ok === Result.ERROR) {
+                                d(readResult);
+                                return;
+                            }
+
+                            for (let i = 0, length = adds.length; i < length; i++) {
+                                collection.add(adds[i]);
+                                result.adds.push(adds[i] as DeepPartial<InferCreateType<UnknownRecord>>);
+                            }
+
+                            for (let i = 0, length = updates.length; i < length; i++) {
+                                collection.update(updates[i].entity);
+                                result.updates.push(updates[i].entity);
+                            }
+
+                            for (let i = 0, length = removes.length; i < length; i++) {
+                                collection.remove(removes[i]);
+                                result.removes.push(removes[i]);
+                            }
+
+                            collection.save(saveResult => {
+
+                                if (saveResult.ok === Result.ERROR) {
+                                    d(saveResult);
+                                    return;
+                                }
+
+                                d(Result.success());
+                            });
+                        })
+
+                    } catch (e) {
+                        d(Result.error(e));
+                    }
+                });
+            }
+
+            let successCount = 0;
+
+            pipeline.filter((asyncResult) => {
+
+                if (asyncResult.ok !== PluginEventResult.SUCCESS) {
+
+                    if (successCount === 0) {
+                        done(PluginEventResult.error(event.id, asyncResult.error))
+                        return;
+                    }
+
+                    done(PluginEventResult.partial(event.id, bulkPersistResult, asyncResult.error))
+                    return;
+                }
+
+                successCount++;
+
+                done(PluginEventResult.success(event.id, bulkPersistResult));
+            });
+        } catch (e: any) {
+            done(PluginEventResult.error(event.id, e))
+        }
+    }
+
+    query<TEntity extends {}, TShape extends any = TEntity>(event: DbPluginQueryEvent<TEntity, TShape>, done: PluginEventCallbackResult<TShape>): void {
+
+        try {
+            const { operation } = event;
+            const translator = new JsonTranslator<TEntity, TShape>(operation);
+            const collection = this.resolveCollection(operation.schema);
+
+            // translate if we are doing any operations like count/sum/min/max/skip/take
+            collection.load(r => {
+
+                if (r.ok === Result.ERROR) {
+                    done(PluginEventResult.error(event.id, r.error));
+                    return;
+                }
+
+                const translated = translator.translate(collection.records);
+
+                done(PluginEventResult.success(event.id, translated));
+            })
+        } catch (e) {
+            done(PluginEventResult.error(event.id, e));
+        }
+    }
+
+    abstract destroy(event: DbPluginEvent, done: PluginEventCallbackResult<never>): void;
+}

package/src/plugins/capabilities/DbPluginCapability.ts

@@ -0,0 +1,111 @@
+import { BulkPersistResult } from "../../collections";
+import { PluginEventPartialResultType, PluginEventResultType } from "../../results";
+import { DbPluginBulkPersistEvent, DbPluginEvent, DbPluginQueryEvent, IDbPlugin } from "../types";
+
+export type DbPluginCapabilityEvent = "queryStart" | "queryComplete" | "destroyStart" | "destroyComplete" | "bulkPersistStart" | "bulkPersistComplete";
+
+export interface IDbPluginCapability {
+    apply<T extends IDbPlugin>(plugin: T): void;
+}
+
+/**
+ * Extends plugin functionality through hooks and event handlers without
+ * changing the plugin's type (mixin). Essential for maintaining type safety
+ * in routier's core systems.
+ */
+export class DbPluginCapability {
+
+    private events: Record<string, { before?: Function, after?: Function }> = {};
+
+    add<TRoot extends {}, TShape extends any = TRoot>(name: "queryStart", callback: (event: DbPluginQueryEvent<TRoot, TShape>) => void): DbPluginCapability;
+    add<TRoot extends {}, TShape extends any = TRoot>(name: "queryComplete", callback: (event: PluginEventResultType<TShape>) => void): DbPluginCapability;
+    add<TRoot extends {}, TShape extends any = TRoot>(name: "destroyStart", callback: (event: DbPluginEvent) => void): DbPluginCapability;
+    add<TRoot extends {}, TShape extends any = TRoot>(name: "destroyComplete", callback: (event: PluginEventResultType<never>) => void): DbPluginCapability;
+    add<TRoot extends {}, TShape extends any = TRoot>(name: "bulkPersistStart", callback: (event: DbPluginBulkPersistEvent) => void): DbPluginCapability;
+    add<TRoot extends {}, TShape extends any = TRoot>(name: "bulkPersistComplete", callback: (event: PluginEventPartialResultType<BulkPersistResult>) => void): DbPluginCapability;
+    add<TRoot extends {}, TShape extends any = TRoot>(name: DbPluginCapabilityEvent, callback: Function): DbPluginCapability {
+
+        this.resolve(name);
+
+        switch (name) {
+            case "queryStart":
+                this.events["query"].before = callback;
+                break;
+            case "queryComplete":
+                this.events["query"].after = callback;
+                break;
+            case "destroyStart":
+                this.events["destroy"].before = callback;
+                break;
+            case "destroyComplete":
+                this.events["destroy"].after = callback;
+                break;
+            case "bulkPersistStart":
+                this.events["bulkPersist"].before = callback;
+                break;
+            case "bulkPersistComplete":
+                this.events["bulkPersist"].after = callback;
+                break;
+        }
+
+        return this;
+    }
+
+    private resolve(name: DbPluginCapabilityEvent) {
+
+        switch (name) {
+            case "queryStart":
+            case "queryComplete":
+                if (!this.events["query"]) {
+                    this.events["query"] = {};
+                }
+                return;
+            case "destroyStart":
+            case "destroyComplete":
+                if (!this.events["destroy"]) {
+                    this.events["destroy"] = {};
+                }
+                return;
+            case "bulkPersistStart":
+            case "bulkPersistComplete":
+                if (!this.events["bulkPersist"]) {
+                    this.events["bulkPersist"] = {};
+                }
+                return;
+
+            default:
+                throw new Error("Exhaustive check")
+        }
+    }
+
+    apply<T extends IDbPlugin>(plugin: T) {
+
+        const methodWrappers: { method: keyof IDbPlugin, events: { before?: Function, after?: Function } }[] = [
+            { method: 'query', events: this.events.query },
+            { method: 'destroy', events: this.events.destroy },
+            { method: 'bulkPersist', events: this.events.bulkPersist }
+        ];
+
+        // apply the mixins
+        for (let i = 0, length = methodWrappers.length; i < length; i++) {
+
+            const { events, method } = methodWrappers[i];
+
+            if (events?.before || events?.after) {
+                const original = plugin[method].bind(plugin);
+                plugin[method] = ((event: unknown, done: Function) => {
+                    events.before?.(event, done);
+
+                    if (events.after) {
+                        return original(event, (result: unknown) => {
+                            events.after(result);
+                            done(result);
+                        });
+                    }
+
+                    return original(event, done);
+                });
+            }
+        }
+    }
+}

package/src/plugins/capabilities/index.ts

@@ -0,0 +1,2 @@
+export * from './DbPluginCapability';
+export * from './logging';