@routier/core 0.0.1-alpha.1

package/src/plugins/capabilities/logging/DbPluginLoggingCapability.ts

@@ -0,0 +1,261 @@
+import { IDbPlugin, DbPluginQueryEvent, DbPluginBulkPersistEvent, DbPluginEvent } from "../../../plugins/types";
+import { DbPluginCapability, IDbPluginCapability } from "../DbPluginCapability";
+import { PluginEventResultType, PluginEventPartialResultType } from "../../../results";
+import { now } from "../../../performance";
+import { BulkPersistChanges, BulkPersistResult } from "../../../collections";
+
+export class DbPluginLoggingCapability implements IDbPluginCapability {
+    private logStyle: 'minimal' | 'detailed' | 'redux' = 'redux';
+    private maxLogEntries: number = 100;
+    private logHistory: Array<{ type: string; timestamp: number; data: any }> = [];
+    private queryPerformance: Map<string, number> = new Map<string, number>();
+
+    constructor(options?: { logStyle?: 'minimal' | 'detailed' | 'redux'; maxLogEntries?: number }) {
+        this.logStyle = options?.logStyle ?? 'redux';
+        this.maxLogEntries = options?.maxLogEntries ?? 100;
+    }
+
+    apply<T extends IDbPlugin>(plugin: T) {
+        const baseCapability = new DbPluginCapability();
+
+        const pluginName = plugin.constructor.name;
+
+        // Query logging
+        baseCapability
+            .add("queryStart", (event: DbPluginQueryEvent<any, any>) => {
+                this.logReduxAction('QUERY_REQUEST', event.id, {
+                    plugin: pluginName,
+                    collection: event.operation.schema.collectionName,
+                    schemaId: event.operation.schema.id,
+                    changeTracking: event.operation.changeTracking
+                }, {
+                    timestamp: new Date().toISOString(),
+                    options: this.extractQueryOptions(event.operation)
+                });
+                this.addToHistory('QUERY_REQUEST', event);
+                this.queryPerformance.set(event.id, now());
+            })
+            .add("queryComplete", (result: PluginEventResultType<any>) => {
+                const start = this.queryPerformance.get(result.id);
+                this.queryPerformance.delete(result.id)
+                const end = now();
+                const duration = start == null ? -1 : end - start;
+                const performance = this.getPerformanceIndicator(duration);
+
+                if (result.ok === 'success') {
+                    this.logReduxAction('QUERY_SUCCESS', result.id, {
+                        plugin: pluginName,
+                        resultCount: this.getResultCount(result.data),
+                        resultType: this.getResultType(result.data)
+                    }, {
+                        duration: `${duration.toFixed(4)}ms`,
+                        performance: performance.label,
+                        timestamp: new Date().toISOString()
+                    });
+                } else {
+                    this.logReduxAction('QUERY_ERROR', result.id, {
+                        plugin: pluginName,
+                        error: result.error?.message || result.error,
+                        isCritical: false
+                    }, {
+                        duration: `${duration.toFixed(4)}ms`,
+                        performance: performance.label,
+                        timestamp: new Date().toISOString()
+                    });
+                }
+                this.addToHistory('QUERY_RESULT', { result, duration });
+            });
+
+        // Bulk operations logging
+        baseCapability
+            .add("bulkPersistStart", (event: DbPluginBulkPersistEvent) => {
+                const totalOperations = event.operation.aggregate.size;
+                this.logReduxAction('BULK_OPERATIONS_REQUEST', event.id, {
+                    plugin: pluginName,
+                    totalOperations,
+                    schemaCount: event.schemas.size,
+                    operations: this.extractBulkOperations(event.operation)
+                }, {
+                    timestamp: new Date().toISOString()
+                });
+                this.addToHistory('BULK_OPERATIONS_REQUEST', event);
+                this.queryPerformance.set(event.id, now());
+            })
+            .add("bulkPersistComplete", (result: PluginEventPartialResultType<BulkPersistResult>) => {
+                const start = this.queryPerformance.get(result.id);
+                this.queryPerformance.delete(result.id)
+                const end = now();
+                const duration = start == null ? -1 : end - start;
+                const performance = this.getPerformanceIndicator(duration);
+
+                if (result.ok === 'success') {
+                    this.logReduxAction('BULK_OPERATIONS_SUCCESS', result.id, {
+                        plugin: pluginName,
+                        completedOperations: this.countCompletedOperations(result.data),
+                        schemaCount: result.data.size
+                    }, {
+                        duration: `${duration.toFixed(4)}ms`,
+                        performance: performance.label,
+                        timestamp: new Date().toISOString()
+                    });
+                } else {
+                    this.logReduxAction('BULK_OPERATIONS_ERROR', result.id, {
+                        plugin: pluginName,
+                        error: result.error?.message || result.error,
+                        isCritical: false
+                    }, {
+                        duration: `${duration.toFixed(4)}ms`,
+                        performance: performance.label,
+                        timestamp: new Date().toISOString()
+                    });
+                }
+                this.addToHistory('BULK_OPERATIONS_RESULT', { result, duration });
+            });
+
+        // Destroy logging
+        baseCapability
+            .add("destroyStart", (event: DbPluginEvent) => {
+                this.logReduxAction('DESTROY_REQUEST', event.id, {
+                    plugin: pluginName,
+                    schemaCount: event.schemas.size
+                }, {
+                    timestamp: new Date().toISOString()
+                });
+                this.addToHistory('DESTROY_REQUEST', event);
+                this.queryPerformance.set(event.id, now());
+            })
+            .add("destroyComplete", (result: PluginEventResultType<never>) => {
+                const start = this.queryPerformance.get(result.id);
+                this.queryPerformance.delete(result.id)
+                const end = now();
+                const duration = start == null ? -1 : end - start;
+                const performance = this.getPerformanceIndicator(duration);
+
+                if (result.ok === 'success') {
+                    this.logReduxAction('DESTROY_SUCCESS', result.id, {
+                        plugin: pluginName
+                    }, {
+                        duration: `${duration.toFixed(4)}ms`,
+                        performance: performance.label,
+                        timestamp: new Date().toISOString()
+                    });
+                } else {
+                    this.logReduxAction('DESTROY_ERROR', result.id, {
+                        plugin: pluginName,
+                        error: result.error?.message || result.error
+                    }, {
+                        duration: `${duration.toFixed(4)}ms`,
+                        performance: performance.label,
+                        timestamp: new Date().toISOString()
+                    });
+                }
+                this.addToHistory('DESTROY_RESULT', { result, duration });
+            });
+
+        baseCapability.apply(plugin);
+    }
+
+    private getPerformanceIndicator(duration: number) {
+        if (duration > 1000) return { emoji: '🐌', color: '#ef4444', label: 'SLOW', level: 'error' };
+        if (duration > 500) return { emoji: '🐢', color: '#f97316', label: 'MEDIUM', level: 'warning' };
+        if (duration > 100) return { emoji: '⚡', color: '#eab308', label: 'FAST', level: 'info' };
+        return { emoji: '🚀', color: '#22c55e', label: 'INSTANT', level: 'success' };
+    }
+
+    private logReduxAction(action: string, eventId: string, payload: any, meta?: any) {
+        if (this.logStyle !== 'redux') return;
+
+        const timestamp = new Date().toISOString();
+
+        console.groupCollapsed(
+            `%c${action} %c@ ${timestamp}`,
+            'color: #3b82f6; font-weight: bold; font-size: 14px;',
+            'color: #6b7280; font-size: 12px;'
+        );
+
+        console.group('Action');
+        console.log('Type:', action);
+        console.log('Event ID:', eventId);
+        console.log('Timestamp:', timestamp);
+        console.groupEnd();
+
+        if (payload) {
+            console.group('Payload');
+            console.log(payload);
+            console.groupEnd();
+        }
+
+        if (meta) {
+            console.group('Meta');
+            console.log(meta);
+            console.groupEnd();
+        }
+
+        console.groupEnd();
+    }
+
+    private extractQueryOptions(query: any) {
+        const options: Record<string, any> = {};
+        if (query.options) {
+            ['skip', 'take', 'sort', 'filter', 'map', 'distinct'].forEach(type => {
+                try {
+                    const values = query.options.getValues(type);
+                    if (values.length > 0) options[type] = values;
+                } catch (e) {
+                    // Skip if option type not supported
+                }
+            });
+        }
+        return options;
+    }
+
+    private getResultCount(result: any): string {
+        if (Array.isArray(result)) return `${result.length} items`;
+        if (result !== null && typeof result === 'object') return '1 object';
+        return '1 primitive';
+    }
+
+    private getResultType(result: any): string {
+        if (Array.isArray(result)) return 'array';
+        if (result !== null && typeof result === 'object') return 'object';
+        return typeof result;
+    }
+
+    private extractBulkOperations(operations: BulkPersistChanges) {
+        const aggregate = operations.aggregate;
+        return {
+            adds: aggregate.adds,
+            updates: aggregate.updates,
+            removes: aggregate.removes
+        };
+    }
+
+    private countCompletedOperations(result: BulkPersistResult | undefined): number {
+        return result?.aggregate.size || 0;
+    }
+
+    private addToHistory(type: string, data: any) {
+        this.logHistory.push({
+            type,
+            timestamp: Date.now(),
+            data
+        });
+
+        if (this.logHistory.length > this.maxLogEntries) {
+            this.logHistory = this.logHistory.slice(-this.maxLogEntries);
+        }
+    }
+
+    private generateId(): string {
+        return Math.random().toString(36).substr(2, 9);
+    }
+
+    // Public methods for debugging
+    getLogHistory() {
+        return [...this.logHistory];
+    }
+
+    clearLogHistory() {
+        this.logHistory = [];
+    }
+}

package/src/plugins/capabilities/logging/index.ts

@@ -0,0 +1 @@
+export * from './DbPluginLoggingCapability';

package/src/plugins/index.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './translators';
+export * from './capabilities';
+export * from './replication';
+export * from './query';
+export * from './EphemeralDataPlugin';

package/src/plugins/query/Query.ts

@@ -0,0 +1,67 @@
+
+import { CompiledSchema } from '../../schema';
+import { IQuery } from '../types';
+import { QueryOptionsCollection } from './QueryOptionsCollection';
+
+export class Query<TRoot extends {}, TShape> implements IQuery<TRoot, TShape> {
+
+    readonly options: QueryOptionsCollection<TShape>;
+    readonly schema: CompiledSchema<TRoot>;
+    private enableChangeTrackingOverride?: boolean
+
+    constructor(
+        options: QueryOptionsCollection<TShape>,
+        schema: CompiledSchema<TRoot>,
+        enableChangeTrackingOverride?: boolean,
+    ) {
+        this.schema = schema;
+        this.options = options;
+        this.enableChangeTrackingOverride = enableChangeTrackingOverride;
+    }
+
+    // boolean value whether or not change tracking can be enabled on the query result
+    get changeTracking(): boolean {
+
+        if (this.enableChangeTrackingOverride != null) {
+            return this.enableChangeTrackingOverride;
+        }
+
+        const map = this.options.getValues("map");
+        const count = this.options.has("count");
+        const max = this.options.has("max");
+        const min = this.options.has("min");
+        const sum = this.options.has("sum");
+
+        if (map.some(x => x.fields.length > 0)) {
+            return false
+        }
+
+        if (count === true ||
+            max === true ||
+            min === true ||
+            sum === true) {
+            return false
+        }
+
+        return true;
+    }
+
+    static EMPTY<T extends {}, S>(schema: CompiledSchema<T>) {
+        return new Query<T, S>(QueryOptionsCollection.EMPTY<S>(), schema);
+    }
+
+    static isEmpty<T extends {}, S>(query: IQuery<T, S>) {
+        return QueryOptionsCollection.isEmpty(query.options);
+    }
+
+    static toString<TRoot extends {}, TShape>(query: IQuery<TRoot, TShape>) {
+        return JSON.stringify({
+            options: query.options.items,
+            schema: {
+                id: query.schema.id,
+                collectionName: query.schema.collectionName
+            },
+            changeTracking: query.changeTracking
+        })
+    }
+}

package/src/plugins/query/QueryOptionsCollection.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest';
+import { QueryOptionsCollection } from './QueryOptionsCollection';
+import { QueryOrdering } from './types';
+
+describe('QueryOptionsCollection', () => {
+    it('should create an empty collection', () => {
+        const collection = QueryOptionsCollection.EMPTY();
+        expect(collection).toBeInstanceOf(QueryOptionsCollection);
+        expect(QueryOptionsCollection.isEmpty(collection)).toBe(true);
+    });
+
+    it('should add a skip option', () => {
+        const collection = QueryOptionsCollection.EMPTY();
+        collection.add('skip', 5);
+        expect(collection.has('skip')).toBe(true);
+        expect(collection.get('skip')).toHaveLength(1);
+        expect(collection.get('skip')[0].option.value).toBe(5);
+    });
+
+    it('should add a take option', () => {
+        const collection = QueryOptionsCollection.EMPTY();
+        collection.add('take', 10);
+        expect(collection.has('take')).toBe(true);
+        expect(collection.get('take')).toHaveLength(1);
+        expect(collection.get('take')[0].option.value).toBe(10);
+    });
+
+    it('should add a sort option', () => {
+        const collection = QueryOptionsCollection.EMPTY<any>();
+        const selector = (item: any) => item.id;
+        collection.add('sort', { selector, direction: QueryOrdering.Ascending, propertyName: 'id' });
+        expect(collection.has('sort')).toBe(true);
+        expect(collection.get('sort')).toHaveLength(1);
+        expect(collection.get('sort')[0].option.value.direction).toBe(QueryOrdering.Ascending);
+    });
+
+    it('should add a map option', () => {
+        const collection = QueryOptionsCollection.EMPTY();
+        const selector = (item: any) => ({ id: item.id });
+        collection.add('map', { selector, fields: [] });
+        expect(collection.has('map')).toBe(true);
+        expect(collection.get('map')).toHaveLength(1);
+        expect(collection.get('map')[0].option.value.selector).toBe(selector);
+    });
+
+    it('should add multiple options of the same type', () => {
+        const collection = QueryOptionsCollection.EMPTY();
+        collection.add('skip', 5);
+        collection.add('skip', 10);
+        expect(collection.get('skip')).toHaveLength(2);
+        expect(collection.get('skip')[0].option.value).toBe(5);
+        expect(collection.get('skip')[1].option.value).toBe(10);
+    });
+
+    it('should assign sequential indices to options', () => {
+        const collection = QueryOptionsCollection.EMPTY<any>();
+        collection.add('skip', 5);
+        collection.add('take', 10);
+        collection.add('sort', { selector: (item: any) => item.id, direction: QueryOrdering.Ascending, propertyName: 'id' });
+        expect(collection.get('skip')[0].index).toBe(0);
+        expect(collection.get('take')[0].index).toBe(1);
+        expect(collection.get('sort')[0].index).toBe(2);
+    });
+
+    it('forEach iterates options in index order across types', () => {
+        const collection = QueryOptionsCollection.EMPTY<any>();
+
+        collection.add('skip', 1);
+        collection.add('take', 2);
+        collection.add('sort', { selector: (i: any) => i.id, direction: QueryOrdering.Descending, propertyName: 'id' });
+        collection.add('skip', 3);
+        collection.add('take', 4);
+
+        const namesInOrder: string[] = [];
+        collection.forEach((opt) => {
+            namesInOrder.push(opt.name);
+        });
+
+        const expectedByIndex = [...collection.items.values()]
+            .flat()
+            .sort((a, b) => a.index - b.index)
+            .map(i => i.option.name);
+
+        expect(namesInOrder).toEqual(expectedByIndex);
+    });
+}); 

package/src/plugins/query/QueryOptionsCollection.ts

@@ -0,0 +1,154 @@
+import { forEach, isPropertyExpression } from "../../expressions/utils";
+import { QueryOption, QueryOptionName, QueryOptionExecutionTarget, QueryOptionValueMap } from "./types";
+
+export type QueryCollectionItem<T, K extends QueryOptionName> = { index: number, option: QueryOption<T, K> };
+
+export class QueryOptionsCollection<T> {
+
+    private options: Map<QueryOptionName, QueryCollectionItem<any, any>[]> = new Map<QueryOptionName, QueryCollectionItem<any, any>[]>();
+    private nextExecutionTarget: QueryOptionExecutionTarget = "database";
+    private nextIndex: number = 0;
+    private enumeratedItems: QueryCollectionItem<any, any>[] = [];
+
+    get items() {
+        return this.options;
+    }
+
+    get isEmpty() {
+        return this.items.size === 0;
+    }
+
+    static EMPTY<R>() {
+        return new QueryOptionsCollection<R>();
+    }
+
+    static isEmpty<T>(options: QueryOptionsCollection<T>) {
+        return options.isEmpty;
+    }
+
+    add<K extends QueryOptionName>(name: K, value: QueryOption<T, K>["value"]) {
+
+        if (name === "map") {
+            const mapValue = value as QueryOptionValueMap<T>["map"];
+
+            // Evaluate the map value to see if we are renaming properties, 
+            // if we are we need to perform everything after in memory
+            if (mapValue.fields.some(x => x.isRename === true) || mapValue.fields.some(x => x.property?.isUnmapped === true)) {
+                // Cut over to memory execution since we are renaming a property with .map
+                // We do not want to figure out how the new name flows through the entire query
+                this.nextExecutionTarget = "memory";
+            }
+        }
+
+        if (name === "filter") {
+            // Need to check for unmapped properties
+            const filterValue = value as QueryOptionValueMap<T>["filter"];
+
+            if (filterValue.expression.type === "not-parsable") {
+                this.nextExecutionTarget = "memory";
+            } else {
+                forEach(filterValue.expression, (expression) => {
+
+                    if (isPropertyExpression(expression) && expression.property.isUnmapped) {
+                        // Cut over to memory execution, unmapped properties are not in the database and
+                        // cannot be queried
+                        this.nextExecutionTarget = "memory";
+                        return false;
+                    }
+
+                    return true;
+                });
+            }
+        }
+
+        const item: QueryCollectionItem<T, K> = {
+            index: this.nextIndex,
+            option: {
+                name,
+                target: this.nextExecutionTarget,
+                value
+            }
+        }
+
+        this.nextIndex++;
+
+        const found = this.options.get(name);
+
+        this.options.set(name, [...found ?? [], item]);
+    }
+
+    split(): { memory: QueryOptionsCollection<T>, database: QueryOptionsCollection<T> } {
+        this.resolveEnumeration();
+
+        const sortedItems = this.enumeratedItems.toSorted((a, b) => a.index - b.index);
+        const memoryQueryOptionsCollection = new QueryOptionsCollection<T>();
+        const databaseQueryOptionsCollection = new QueryOptionsCollection<T>();
+
+        for (let i = 0, length = sortedItems.length; i < length; i++) {
+            const sortedItem = sortedItems[i];
+
+            if (sortedItem.option.target === "database") {
+                databaseQueryOptionsCollection.add(sortedItem.option.name, sortedItem.option.value);
+                continue;
+            }
+
+            memoryQueryOptionsCollection.add(sortedItem.option.name, sortedItem.option.value);
+        }
+
+        return {
+            memory: memoryQueryOptionsCollection,
+            database: databaseQueryOptionsCollection
+        }
+    }
+
+    has<K extends QueryOptionName>(name: K): boolean {
+        return this.options.has(name);
+    }
+
+    get<K extends QueryOptionName>(name: K): QueryCollectionItem<T, K>[] {
+        return this.options.get(name) ?? [] as QueryCollectionItem<T, K>[];
+    }
+
+    getLast<K extends QueryOptionName>(name: K): QueryOption<T, K> | null {
+        this.resolveEnumeration();
+
+        for (let i = this.enumeratedItems.length - 1; i >= 0; i--) {
+            const item = this.enumeratedItems[i];
+
+            if (item.option.name === name) {
+                return item.option;
+            }
+        }
+
+        return null
+    }
+
+    getValues<K extends QueryOptionName>(name: K): QueryCollectionItem<T, K>["option"]["value"][] | undefined {
+
+        const found = this.options.get(name);
+
+        if (found == null) {
+            return [];
+        }
+
+        return found.map(w => w.option.value) as QueryCollectionItem<T, K>["option"]["value"][];
+    }
+
+    private getEnumeration() {
+        return [...this.options.values()].flat().toSorted((a, b) => a.index - b.index);
+    }
+
+    private resolveEnumeration() {
+        if (this.enumeratedItems.length != this.nextIndex) {
+            this.enumeratedItems = this.getEnumeration();
+        }
+    }
+
+    forEach(iterator: (item: QueryCollectionItem<T, any>["option"]) => void) {
+        this.resolveEnumeration();
+
+        for (let i = 0, length = this.enumeratedItems.length; i < length; i++) {
+            iterator(this.enumeratedItems[i].option);
+        }
+    }
+}

package/src/plugins/query/index.ts

@@ -0,0 +1,3 @@
+export * from './Query';
+export * from './QueryOptionsCollection';
+export * from './types';

package/src/plugins/query/types.ts

@@ -0,0 +1,46 @@
+import { Expression, Filter, ParamsFilter } from "../../expressions";
+import { PropertyInfo } from "../../schema";
+import { GenericFunction } from "../../types";
+
+export enum QueryOrdering {
+    Descending = "desc",
+    Ascending = "asc"
+}
+
+/**
+ * Field mapping for a query result, including source and destination names and a getter function.
+ */
+export type QueryField = {
+    sourceName: string,
+    destinationName: string,
+    isRename: boolean;
+    property?: PropertyInfo<unknown>;
+    getter: <T>(data: Record<string, unknown>) => T;
+};
+
+export type QueryOptionExecutionTarget = "database" | "memory";
+export type QueryOptionName = keyof QueryOptionValueMap<unknown>;
+
+export type QueryOption<T, K extends QueryOptionName> = {
+    name: QueryOptionName;
+    value: QueryOptionValueMap<T>[K],
+    target: QueryOptionExecutionTarget;
+}
+
+export type QueryOptionValueMap<T extends {}> = {
+    skip: number;
+    take: number;
+    sort: { selector: GenericFunction<T, T[keyof T]>, direction: QueryOrdering, propertyName: string };
+    map: { selector: GenericFunction<T, any>, fields: QueryField[] };
+    filter: { params?: {}, filter: ParamsFilter<T, {}> | Filter<T>, expression: Expression };
+    min: true; // True or not set
+    max: true; // True or not set
+    count: true; // True or not set
+    sum: true; // True or not set
+    distinct: true; // True or not set
+};
+
+/**
+ * Sort specification for a query.
+ */
+export type QuerySort = { key: string, selector: (item: unknown) => unknown, direction: "asc" | "desc" };