@routier/core 0.0.1-alpha.1

package/src/plugins/translators/JsonTranslator.ts

@@ -0,0 +1,211 @@
+import { DataTranslator } from "./DataTranslator";
+import { QueryOption } from "../query/types";
+import { assertIsArray } from "../../assertions";
+import { ParamsFilter } from "../../expressions";
+import { isDate } from "../../utilities";
+
+export class JsonTranslator<TRoot extends {}, TShape> extends DataTranslator<TRoot, TShape> {
+
+    override filter<TResult>(data: unknown, option: QueryOption<TShape, "filter">): TResult {
+
+        assertIsArray(data);
+
+        if (option.value.filter) {
+
+            if (option.value.params == null) {
+                // standard filtering
+                return data.filter(option.value.filter) as TResult;
+            }
+
+            // params filtering
+            const selector = option.value.filter as ParamsFilter<unknown, {}>
+            return data.filter(w => selector([w, option.value.params])) as TResult;
+        }
+
+        return data as TResult;
+    }
+
+    override map<T>(data: unknown, option: QueryOption<T, "map">): T {
+
+        if (Array.isArray(data) == false) {
+            throw new Error("Can only map an array of data");
+        }
+
+        const response = [];
+
+        // We want deserialization to flow through mappings
+        // TODO: Speed this up!
+        // Generate a function on the fly?
+        for (let i = 0, length = data.length; i < length; i++) {
+
+            for (let j = 0, l = option.value.fields.length; j < l; j++) {
+                const field = option.value.fields[j];
+
+                if (field.property != null) {
+                    const value = field.property.getValue(data[i]);
+
+                    if (value != null) {
+                        field.property.setValue(data[i], field.property.deserialize(value));
+                    }
+                }
+            }
+
+            response.push(option.value.selector(data[i]));
+        }
+
+        return response as T;
+    }
+
+    override count<TResult extends number>(data: unknown, _: QueryOption<TShape, "count">): TResult {
+
+        if (Array.isArray(data)) {
+            return data.length as TResult;
+        }
+
+        throw new Error("Cannot count resulting data, it must be an array.  Please return array of data for function: count()");
+    }
+
+    override min<TResult extends string | number | Date>(data: unknown, _: QueryOption<TShape, "min">): TResult {
+        return this._minMax(data, "min", (a: any, b: any) => a - b);
+    }
+
+    override max<TResult extends string | number | Date>(data: unknown, _: QueryOption<TShape, "max">): TResult {
+        return this._minMax(data, "max", (a: any, b: any) => b - a);
+    }
+
+    override sort<TResult>(data: unknown, option: QueryOption<TShape, "sort">): TResult {
+
+        if (Array.isArray(data)) {
+
+            data.sort((a, b) => {
+                if (option.value.direction === "asc") {
+                    return (option.value.selector(a) as any) - (option.value.selector(b) as any);
+                }
+
+                return (option.value.selector(b) as any) - (option.value.selector(a) as any);
+            });
+        }
+
+        return data as TResult;
+    }
+
+    override sum<TResult extends number>(data: unknown, _: QueryOption<TShape, "sum">): TResult {
+
+        assertIsArray(data, this._formatDataNotArrayError("sum"));
+
+        const map = this.query.options.getLast("map");
+
+        let sum = 0;
+        const field = this._getSelectionField("sum", map);
+
+        for (let i = 0, length = data.length; i < length; i++) {
+            const value = data[i];
+
+            if (typeof value !== "number") {
+                throw new Error(`Cannot sum, property is not a number.  Property: ${field.sourceName}`);
+            }
+
+            sum += value;
+        }
+
+        return sum as TResult;
+    }
+
+    override distinct<TResult>(data: unknown, _: QueryOption<TShape, "distinct">): TResult {
+
+        assertIsArray(data, this._formatDataNotArrayError("distinct"));
+
+        const result = new Set<string | number | Date>();
+
+        // would be nice to have property info here for type detection
+        let needsDateConversion = false;
+
+        for (let i = 0, length = data.length; i < length; i++) {
+            const value = data[i];
+
+            if (typeof value === "number" || typeof value === "string") {
+                result.add(value);
+                continue;
+            }
+
+            if (isDate(value)) {
+                needsDateConversion = true;
+                result.add(value.toISOString());
+                continue;
+            }
+
+        }
+
+        if (needsDateConversion) {
+            return [...result].map(w => new Date(w)) as TResult;
+        }
+
+        return [...result] as TResult
+    }
+
+    override skip<TResult>(data: unknown, option: QueryOption<TShape, "skip">): TResult {
+
+        if (Array.isArray(data)) {
+
+            if (option.value > 0) {
+
+                if (data.length < option.value) {
+                    // We don't have enough data to skip, return an empty array
+                    return [] as TResult;
+                }
+
+                return data.slice(option.value) as TResult;
+            }
+
+            return data as TResult;
+        }
+
+        return data as TResult;
+    }
+
+    override take<TResult>(data: unknown, option: QueryOption<TShape, "take">): TResult {
+        if (Array.isArray(data)) {
+
+            if (option.value > 0) {
+
+                if (data.length < option.value) {
+                    return data as TResult;
+                }
+
+                return data.slice(0, option.value) as TResult;
+            }
+
+            return data as TResult;
+        }
+
+        return data as TResult;
+    }
+
+    private _getSelectionField(name: string, mapOption: QueryOption<TShape, "map"> | null) {
+
+        if (mapOption == null ||
+            mapOption.value.fields.length === 0 ||
+            mapOption.value.fields.length > 1) {
+            throw new Error(`${name}() operation can only be performed when one field is mapped for a result.  Ex.  myset.map(x => x.someNumberOrDateOrString).${name}()`)
+        }
+
+        return mapOption.value.fields[0];
+    }
+
+    private _minMax<T extends string | number | Date>(data: unknown, name: string, sort: (a: any, b: any) => any): T {
+
+        assertIsArray(data, this._formatDataNotArrayError(name));
+
+        data.sort(sort);
+
+        if (data.length === 0) {
+            throw new Error("Cannot perform operation on empty array, result query contains no data")
+        }
+
+        return data[0] as T;
+    }
+
+    private _formatDataNotArrayError(functionName: string) {
+        return `Cannot sum resulting data, it must be an array.  Please return array of data for function: ${functionName}()`
+    }
+}

package/src/plugins/translators/SqlTranslator.ts

@@ -0,0 +1,45 @@
+import { QueryOption } from "../query/types";
+import { DataTranslator } from "./DataTranslator";
+
+export class SqlTranslator<TRoot extends {}, TShape> extends DataTranslator<TRoot, TShape> {
+
+    count<TResult extends number>(data: unknown, _: QueryOption<TShape, "count">): TResult {
+        return data as TResult;
+    }
+
+    min<TResult extends string | number | Date>(data: unknown, _: QueryOption<TShape, "min">): TResult {
+        return data as TResult;
+    }
+
+    max<TResult extends string | number | Date>(data: unknown, _: QueryOption<TShape, "max">): TResult {
+        return data as TResult;
+    }
+
+    sum<TResult extends number>(data: unknown, _: QueryOption<TShape, "sum">): TResult {
+        return data as TResult;
+    }
+
+    distinct<TResult>(data: unknown, _: QueryOption<TShape, "distinct">): TResult {
+        return data as TResult;
+    }
+
+    filter<TResult>(data: unknown, _: QueryOption<TShape, "filter">): TResult {
+        return data as TResult;
+    }
+
+    skip(data: unknown, _: QueryOption<TShape, "skip">): TShape {
+        return data as TShape;
+    }
+
+    take(data: unknown, _: QueryOption<TShape, "take">): TShape {
+        return data as TShape;
+    }
+
+    sort(data: unknown, _: QueryOption<TShape, "sort">): TShape {
+        return data as TShape;
+    }
+
+    map(data: unknown, _: QueryOption<TShape, "map">): TShape {
+        return data as TShape;
+    }
+}

package/src/plugins/translators/index.ts

@@ -0,0 +1,3 @@
+export * from './DataTranslator';
+export * from './JsonTranslator';
+export * from './SqlTranslator';

package/src/plugins/types.ts

@@ -0,0 +1,114 @@
+import { PluginEventCallbackPartialResult, PluginEventCallbackResult } from "../results";
+import { QueryOptionsCollection } from "./query/QueryOptionsCollection";
+import { CompiledSchema, InferType } from '../schema';
+import { BulkPersistChanges, BulkPersistResult, SchemaCollection } from "../collections";
+
+/**
+ * Interface for a database plugin, which provides query, destroy, and bulk operations.
+ */
+export interface IDbPlugin {
+    /**
+     * Executes a query operation on the database.
+     * @param event The query event containing schema, parent, and query operation.
+     * @param done Callback with the result or error.
+     */
+    query<TRoot extends {}, TShape extends any = TRoot>(event: DbPluginQueryEvent<TRoot, TShape>, done: PluginEventCallbackResult<TShape>): void;
+    /**
+     * Destroys or cleans up the plugin, closing connections or freeing resources.
+     * @param done Callback with an optional error.
+     */
+    destroy(event: DbPluginEvent, done: PluginEventCallbackResult<never>): void;
+    /**
+     * Executes bulk operations (add, update, remove) on the database.
+     * @param event The bulk operations event containing schema, parent, and changes.
+     * @param done Callback with the result or error.
+     */
+    bulkPersist(event: DbPluginBulkPersistEvent, done: PluginEventCallbackPartialResult<BulkPersistResult>): void;
+}
+
+/**
+ * Event for a query operation, including schema, parent, and the query operation.
+ */
+export type DbPluginQueryEvent<TRoot extends {}, TShape> = DbPluginOperationEvent<IQuery<TRoot, TShape>>;
+
+/**
+ * Event for bulk operations, including schema, parent, and the entity changes.
+ */
+export type DbPluginBulkPersistEvent = DbPluginOperationEvent<BulkPersistChanges>;
+
+/**
+ * Base event for all plugin operations, containing the schema and parent.
+ */
+export type DbPluginEvent = {
+    /** The compiled schema for the entity. */
+    schemas: SchemaCollection;
+
+    /** Unique id of the event. */
+    id: string;
+}
+
+/**
+ * Event for a specific plugin operation, extending the base event with an operation payload.
+ */
+export type DbPluginOperationEvent<TOperation> = DbPluginEvent & {
+    /** The operation payload (query, changes, etc.). */
+    operation: TOperation;
+}
+
+/**
+ * Represents a collection of database plugins with a primary source and optional replicas.
+ * Used for implementing read/write separation and high availability.
+ */
+export type ReplicationPluginOptions = {
+    /** The primary database plugin that handles all write operations, do not include in the list of replicas. */
+    source: IDbPlugin;
+    /** Array of replica database plugins that can be used for read operations. */
+    replicas: IDbPlugin[];
+    /**
+     * The primary database plugin that handles all read operations, do not include in the list of replicas.
+     * Used when the source plugin should generate the identity properties, but the read replica will only
+     * read data. Typically this is a MemoryPlugin. Should not be included in the list of replicas.
+     */
+    read?: IDbPlugin;
+}
+
+export type OptimisticReplicationPluginOptions = {
+    /** The primary database plugin that handles all write operations, do not include in the list of replicas. */
+    source: IDbPlugin;
+
+    /** Array of replica database plugins that can be used for read operations. */
+    replicas: IDbPlugin[];
+
+    /** Must be a MemoryPlugin */
+    read: IDbPlugin;
+}
+
+
+export type EntityUpdateInfo<T extends {}> = {
+    entity: InferType<T>,
+    changeType: EntityChangeType;
+    delta: { [key: string]: string | number | Date }
+}
+
+export type TaggedEntity<T> = {
+    entity: T;
+    tag?: unknown
+}
+
+/**
+ * Interface for a query operation, including expression, options, filters, and change tracking.
+ */
+export type IQuery<TRoot extends {}, TShape> = {
+
+    /** Query options (sort, skip, take, etc.). */
+    options: QueryOptionsCollection<TShape>;
+
+    schema: CompiledSchema<TRoot>;
+    /**
+     * Whether change tracking is enabled for the query result.
+     * Only enabled when the response is not reduced/aggregated/mapped.
+     */
+    get changeTracking(): boolean;
+};
+
+export type EntityChangeType = "propertiesChanged" | "markedDirty" | "notModified";

package/src/results/Result.ts

@@ -0,0 +1,91 @@
+import { PartialResultType, PluginEventPartialResultType, PluginEventResultType, ResultType } from "./types";
+
+abstract class BaseResult {
+    static ERROR = "error" as const;
+    static SUCCESS = "success" as const;
+    static PARTIAL = "partial" as const;
+
+    static resolve<T>(result: ResultType<T> | PartialResultType<T>, resolve: (data: T) => void, reject: (error?: any) => void) {
+        if (result.ok === BaseResult.SUCCESS) {
+            resolve(result.data);
+            return;
+        }
+
+        if (result.ok === BaseResult.PARTIAL) {
+            reject({
+                partial: result.data,
+                error: result.error
+            });
+            return;
+        }
+
+        reject(result.error);
+    }
+
+    static assertSuccess<T>(result: any): asserts result is { ok: "success"; data: T } {
+        if (result.ok !== BaseResult.SUCCESS) {
+            throw new Error(`Expected success result, but got ${result.ok}: ${result.error}`);
+        }
+    }
+}
+
+export class Result extends BaseResult {
+    static success<T>(data: T): ResultType<T>;
+    static success<T>(): ResultType<never>;
+    static success<T>(data?: T): ResultType<T> {
+        return {
+            ok: Result.SUCCESS,
+            data
+        }
+    }
+
+    static error<T>(error: any): ResultType<T> {
+        return {
+            ok: Result.ERROR,
+            error
+        }
+    }
+
+    static partial<T>(data: T, error: any): PartialResultType<T> {
+        return {
+            ok: Result.PARTIAL,
+            data,
+            error
+        }
+    }
+}
+
+export class PluginEventResult extends BaseResult {
+    static success<T>(id: string, data: T): PluginEventResultType<T>;
+    static success<T>(id: string): PluginEventResultType<never>;
+    static success<T>(id: string, data?: T): PluginEventResultType<T> {
+        return {
+            id,
+            ok: Result.SUCCESS,
+            data
+        }
+    }
+
+    static error<T>(id: string, error: any): PluginEventResultType<T> {
+        return {
+            id,
+            ok: Result.ERROR,
+            error
+        }
+    }
+
+    static partial<T>(id: string, data: T, error: any): PluginEventPartialResultType<T> {
+        return {
+            id,
+            ok: Result.PARTIAL,
+            data,
+            error
+        }
+    }
+
+    static assertSuccess<T>(result: PluginEventResultType<T>): asserts result is { ok: "success"; data: T; id: string } {
+        if (result.ok !== Result.SUCCESS) {
+            throw new Error(`Expected success result, but got ${result.ok}: ${result.error}`);
+        }
+    }
+}

package/src/results/index.ts

@@ -0,0 +1,3 @@
+export * from './Result';
+export * from './types';
+export * from './utils';

package/src/results/types.ts

@@ -0,0 +1,17 @@
+export type ErrorType<Extra extends {} = {}> = { error: any, ok: "error" } & Extra;
+export type SuccessType<T, Extra extends {} = {}> = { data: T, ok: "success" } & Extra;
+export type PartialType<T, Extra extends {} = {}> = { data: T, ok: "partial", error: any } & Extra;
+export type ResultType<T, Extra extends {} = {}> = ErrorType<Extra> | SuccessType<T, Extra>;
+export type PartialResultType<T, Extra extends {} = {}> = ErrorType<Extra> | SuccessType<T, Extra> | PartialType<T, Extra>;
+export type CallbackResult<TData, TCallbackResult = void> = (result: ResultType<TData>) => TCallbackResult;
+export type CallbackPartialResult<TData, TCallbackResult = void> = (result: PartialResultType<TData>) => TCallbackResult;
+
+
+type IdentifiedType = { id: string }
+export type PluginEventErrorType = ErrorType<IdentifiedType>;
+export type PluginEventSuccessType<T> = SuccessType<T, IdentifiedType>;
+export type PluginEventPartialType<T> = PartialType<T, IdentifiedType>;
+export type PluginEventResultType<T> = PluginEventErrorType | PluginEventSuccessType<T>;
+export type PluginEventPartialResultType<T> = PluginEventErrorType | PluginEventSuccessType<T> | PluginEventPartialType<T>;
+export type PluginEventCallbackResult<TData, TCallbackResult = void> = (result: PluginEventResultType<TData>) => TCallbackResult;
+export type PluginEventCallbackPartialResult<TData, TCallbackResult = void> = (result: PluginEventPartialResultType<TData>) => TCallbackResult;

package/src/results/utils.ts

@@ -0,0 +1,15 @@
+import { Result } from "./Result";
+import { CallbackResult } from "./types";
+
+export function toPromise<T>(fn: (callback: CallbackResult<T>) => void) {
+    return new Promise<T>((resolve, reject) => {
+        fn((r) => {
+            if (r.ok === Result.ERROR) {
+                reject(r.error);
+                return;
+            }
+
+            resolve(r.data);
+        });
+    });
+}