@nu-art/thunderstorm-frontend 0.400.5

package/modules/db-api-gen/ModuleFE_BaseApi.d.ts

@@ -0,0 +1,45 @@
+import { DBDef_V3, DBProto } from '@nu-art/ts-common';
+import { ModuleFE_BaseDB } from './ModuleFE_BaseDB.js';
+import { ApiDefCaller, ApiStruct_DBApiGenIDBV3 } from '../../shared.js';
+import { DBApiFEConfig } from '../../core/db-api-gen/db-def.js';
+import { ThunderDispatcher } from '../../core/thunder-dispatcher.js';
+import { CustomMemCreators } from './types.js';
+/**
+ * Base API module for frontend database operations
+ *
+ * Provides core functionality for database CRUD operations through API endpoints
+ * including support for operation queueing and request management.
+ *
+ * @template Proto - Database protocol type extending DBProto
+ * @template _Config - Base configuration type
+ * @template Config - Extended configuration type with DBApiFEConfig
+ */
+export declare abstract class ModuleFE_BaseApi<Proto extends DBProto<any>, _Config extends object = object, Config extends _Config & DBApiFEConfig<Proto> = _Config & DBApiFEConfig<Proto>> extends ModuleFE_BaseDB<Proto, Config> implements ApiDefCaller<ApiStruct_DBApiGenIDBV3<Proto>> {
+    readonly v1: ApiDefCaller<ApiStruct_DBApiGenIDBV3<Proto>>['v1'];
+    private operations;
+    /**
+     * Creates an instance of ModuleFE_BaseApi
+     *
+     * @param dbDef - Database definition
+     * @param defaultDispatcher - Default dispatcher for events
+     * @param version - Optional API version string
+     * @param customMemCreators - Optional custom memory creators for the database
+     */
+    protected constructor(dbDef: DBDef_V3<Proto>, defaultDispatcher: ThunderDispatcher<any, string>, version?: string, customMemCreators?: CustomMemCreators<Proto>);
+    /**
+     * Resolves the API definition for the database
+     *
+     * @param dbDef - Database definition
+     * @param version - Optional API version
+     * @returns Generated API definition for the database
+     */
+    protected resolveApiDef(dbDef: DBDef_V3<Proto>, version: string | undefined): import("@nu-art/thunderstorm-shared/types").ApiDefRouter<ApiStruct_DBApiGenIDBV3<Proto>>;
+    /**
+     * Cleans up data before upserting to database
+     *
+     * @param toUpsert - Data to be upserted
+     * @returns Cleaned up data
+     */
+    protected cleanUp: (toUpsert: Proto["uiType"]) => Proto["uiType"];
+    private updatePending;
+}

package/modules/db-api-gen/ModuleFE_BaseApi.js

@@ -0,0 +1,152 @@
+/*
+ * Database API Generator is a utility library for Thunderstorm.
+ *
+ * Given proper configurations it will dynamically generate APIs to your Firestore
+ * collections, will assert uniqueness and restrict deletion... and more
+ *
+ * Copyright (C) 2020 Adam van der Kruk aka TacB0sS
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { _EmptyQuery } from '@nu-art/firebase-shared';
+import { BadImplementationException } from '@nu-art/ts-common';
+import { ModuleFE_BaseDB } from './ModuleFE_BaseDB.js';
+import { DBApiDefGeneratorIDBV3 } from '../../shared.js';
+import { apiWithBody, apiWithQuery } from '../../core/typed-api.js';
+import { ModuleSyncType } from './types.js';
+/**
+ * Base API module for frontend database operations
+ *
+ * Provides core functionality for database CRUD operations through API endpoints
+ * including support for operation queueing and request management.
+ *
+ * @template Proto - Database protocol type extending DBProto
+ * @template _Config - Base configuration type
+ * @template Config - Extended configuration type with DBApiFEConfig
+ */
+export class ModuleFE_BaseApi extends ModuleFE_BaseDB {
+    // @ts-ignore
+    v1;
+    operations = {};
+    /**
+     * Creates an instance of ModuleFE_BaseApi
+     *
+     * @param dbDef - Database definition
+     * @param defaultDispatcher - Default dispatcher for events
+     * @param version - Optional API version string
+     * @param customMemCreators - Optional custom memory creators for the database
+     */
+    constructor(dbDef, defaultDispatcher, version, customMemCreators) {
+        super(dbDef, defaultDispatcher, ModuleSyncType.APISync, customMemCreators);
+        const apiDef = this.resolveApiDef(dbDef, version);
+        const _query = apiWithBody(apiDef.v1.query, (response) => this.onQueryReturned(response));
+        const queryUnique = apiWithQuery(apiDef.v1.queryUnique, this.onGotUnique);
+        const upsert = apiWithBody(apiDef.v1.upsert, async (item, original) => {
+            const toRet = await this.onEntryUpdated(item, JSON.parse(original));
+            this.IDB.setLastUpdated(item.__updated);
+            return toRet;
+        });
+        const patch = apiWithBody(apiDef.v1.patch, (items) => this.onEntryPatched(items));
+        const _delete = apiWithQuery(apiDef.v1.delete, this.onEntryDeleted);
+        // @ts-ignore
+        this.v1 = {
+            query: (query) => _query(query || _EmptyQuery),
+            // @ts-ignore
+            queryUnique: (_id) => {
+                return queryUnique({ _id });
+            },
+            // @ts-ignore
+            upsert: (toUpsert) => {
+                toUpsert = this.cleanUp(toUpsert);
+                this.validateInternal(toUpsert);
+                return this.updatePending(toUpsert, upsert(toUpsert), 'upsert');
+            },
+            upsertAll: apiWithBody(apiDef.v1.upsertAll, async (items) => {
+                const toRet = await this.onEntriesUpdated(items);
+                const lastUpdated = items.reduce((toRet, current) => Math.max(toRet, current.__updated), -1);
+                this.IDB.setLastUpdated(lastUpdated);
+                return toRet;
+            }),
+            // @ts-ignore
+            patch: (toPatch) => {
+                return this.updatePending(toPatch, patch(toPatch), 'patch');
+            },
+            delete: (item) => {
+                return this.updatePending(item, _delete(item), 'delete');
+            },
+            deleteQuery: apiWithBody(apiDef.v1.deleteQuery, this.onEntriesDeleted),
+            deleteAll: apiWithQuery(apiDef.v1.deleteAll),
+        };
+    }
+    /**
+     * Resolves the API definition for the database
+     *
+     * @param dbDef - Database definition
+     * @param version - Optional API version
+     * @returns Generated API definition for the database
+     */
+    resolveApiDef(dbDef, version) {
+        return DBApiDefGeneratorIDBV3(dbDef, version);
+    }
+    /**
+     * Cleans up data before upserting to database
+     *
+     * @param toUpsert - Data to be upserted
+     * @returns Cleaned up data
+     */
+    cleanUp = (toUpsert) => {
+        return toUpsert;
+    };
+    updatePending(item, request, requestType) {
+        const id = item._id;
+        if (id === undefined)
+            return request;
+        const _execute = request.execute.bind(request);
+        request.execute = (onSuccess, onError) => {
+            const operation = this.operations[id];
+            if (!operation) {
+                this.operations[id] = { running: { request, requestType } };
+                // @ts-ignore
+                // this.logInfo(`pre-executing operation(${requestType}) for ${id}: ${item.label}`);
+                return _execute((r) => {
+                    // @ts-ignore
+                    // this.logInfo(`executing operation(${requestType}) for ${id}: ${item.label}`);
+                    const pending = this.operations[id].pending;
+                    delete this.operations[id];
+                    if (!pending)
+                        return onSuccess?.(r);
+                    pending.request.execute(pending.onSuccess, pending.onError);
+                }, (e) => {
+                    delete this.operations[id];
+                    onError?.(e);
+                });
+            }
+            const runningRequestType = operation.running.requestType;
+            const pendingRequestType = operation.pending?.requestType;
+            if (runningRequestType === 'delete' || pendingRequestType === 'delete') {
+                throw new BadImplementationException(`Item with id: ${id} is marked for deletion`);
+            }
+            if (runningRequestType === 'upsert' || runningRequestType === 'patch') {
+                if (operation.pending) { // @ts-ignore
+                    // this.logInfo(`canceling pending operation(${operation.pending.requestType}) for ${id}`);
+                }
+                // @ts-ignore
+                // this.logInfo(`scheduling pending operation(${requestType}) for ${id}: ${item.label}`);
+                operation.pending = { request, requestType, onSuccess, onError };
+                operation.running.request.clearOnCompleted();
+            }
+            return request;
+        };
+        return request;
+    }
+}

package/modules/db-api-gen/ModuleFE_BaseDB.d.ts

@@ -0,0 +1,146 @@
+import { DB_Object, DBDef_V3, DBProto, IndexKeys, InvalidResult, Logger, Module, TypedMap } from '@nu-art/ts-common';
+import { OnClearWebsiteData } from '../clearWebsiteDataDispatcher.js';
+import { DBApiFEConfig } from '../../core/db-api-gen/db-def.js';
+import { DataStatus } from '../../core/db-api-gen/consts.js';
+import { StorageKey } from '../ModuleFE_LocalStorage.js';
+import { ThunderDispatcher } from '../../core/thunder-dispatcher.js';
+import { IndexDb_Query, ReduceFunction } from '../../core/IndexedDB.js';
+import { IndexedDB_Store } from '../../core/IndexedDBV4/IndexedDB_Store.js';
+import { DBConfigV3 } from '../../core/IndexedDBV4/types.js';
+import { CustomMemCreators, ModuleSyncType } from './types.js';
+import { MultiApiEvent } from '../../core/db-api-gen/types.js';
+export declare abstract class ModuleFE_BaseDB<Proto extends DBProto<any>, Config extends DBApiFEConfig<Proto> = DBApiFEConfig<Proto>> extends Module<Config> implements OnClearWebsiteData {
+    readonly validator: Proto['modifiablePropsValidator'];
+    readonly cache: MemCache<Proto>;
+    readonly IDB: IDBCache<Proto>;
+    readonly dbDef: DBDef_V3<Proto>;
+    private dataStatus;
+    readonly defaultDispatcher: ThunderDispatcher<any, string>;
+    readonly syncType: ModuleSyncType;
+    private readonly ModuleFE_BaseDB;
+    protected constructor(dbDef: DBDef_V3<Proto>, defaultDispatcher: ThunderDispatcher<any, string>, syncType: ModuleSyncType, customMemCreators?: CustomMemCreators<Proto>);
+    protected init(): void;
+    /**
+     * Upgrade processor functionality in the FE module will allow us to validate the items we cache in memory or
+     * idb is up-to-date in case the data source is not coming directly from Storm managed backend (like the csv sync manager)
+     */
+    private versionUpgrades;
+    /**
+     * Upgrades the entity from the given version to the next one (to the same version if the given version is the latest)
+     * @param version - The version we start from
+     * @param processor
+     */
+    registerVersionUpgradeProcessor<K extends Proto['versions']['versions'][number]>(version: K, processor: (items: Proto['versions']['types'][K][]) => Promise<void>): void;
+    upgradeInstances(instances: Proto['dbType'][], force?: boolean): Promise<Proto["dbType"][]>;
+    attachOnLastSyncUpdatedListener: () => void;
+    detachOnLastSyncUpdatedListener: () => void;
+    private onLastSyncUpdatedListener;
+    setDataStatus(status: DataStatus): void;
+    protected OnDataStatusChanged(): void;
+    getDataStatus(): DataStatus;
+    __onClearWebsiteData(): Promise<void>;
+    getCollectionName: () => string;
+    getCollectionKey: () => Proto["dbKey"];
+    private dispatchSingle;
+    dispatchMulti: (event: MultiApiEvent, items: Proto["dbType"][]) => void;
+    onEntriesDeleted: (items: Proto["dbType"][]) => Promise<void>;
+    protected onEntryDeleted: (item: Proto["dbType"]) => Promise<void>;
+    onEntriesUpdated: (items: Proto["dbType"][], updateIDBLastSynced?: boolean) => Promise<void>;
+    onEntryUpdated: (item: Proto["dbType"], original: Proto["uiType"], updateIDBLastSynced?: boolean) => Promise<void>;
+    protected onEntryPatched: (item: Proto["dbType"], updateIDBLastSynced?: boolean) => Promise<void>;
+    validateImpl(_instance: Partial<Proto['uiType']>): void;
+    protected validateInternal(_instance: Partial<Proto['uiType']>): void;
+    protected onValidationError(instance: Proto['uiType'], results: InvalidResult<Proto['dbType']>): void;
+    private onEntryUpdatedImpl;
+    protected onGotUnique: (item: Proto["dbType"]) => Promise<void>;
+    protected onQueryReturned: (toUpdate: Proto["dbType"][], toDelete?: DB_Object[]) => Promise<void>;
+    protected setCacheFilter: (filter: (item: Readonly<Proto["dbType"]>) => boolean) => void;
+}
+export declare class IDBCache<Proto extends DBProto<any>> extends Logger {
+    readonly storeWrapper: IndexedDB_Store<Proto>;
+    protected lastSync: StorageKey<number>;
+    protected readonly lastVersion: StorageKey<string>;
+    private dbConfig;
+    constructor(dbConfig: DBConfigV3<Proto>, dbKey: string);
+    init(): void;
+    protected setLastSyncTimestampStorageKey(newLastSyncStorageKey: StorageKey<number>): void;
+    onLastUpdateListener(onChangeListener: (after?: number, before?: number) => Promise<void>): void;
+    forEach: (processor: (item: Proto["dbType"]) => void) => Promise<Proto["dbType"][]>;
+    clear: () => Promise<void>;
+    delete: () => Promise<void>;
+    query: (query?: string | number | string[] | number[], indexKey?: string) => Promise<Proto["dbType"][]>;
+    /**
+     * Iterates over all DB objects in the related collection, and returns all the items that pass the filter
+     *
+     * @param {function} filter - Boolean returning function, to determine which objects to return.
+     * @param {Object} [query] - A query object
+     *
+     * @return Array of items or empty array
+     */
+    filter: (filter: (item: Proto["dbType"]) => boolean, query?: IndexDb_Query) => Promise<Proto["dbType"][]>;
+    /**
+     * Iterates over all DB objects in the related collection, and returns the first item that passes the filter
+     *
+     * @param {function} filter - Boolean returning function, to determine which object to return.
+     *
+     * @return a single item or undefined
+     */
+    find: (filter: (item: Proto["dbType"]) => boolean) => Promise<Proto["dbType"] | undefined>;
+    /**
+     * Iterates over all DB objects in the related collection, and returns an array of items based on the mapper.
+     *
+     * @param {function} mapper - Function that returns data to map for the object
+     * @param {function} [filter] - Boolean returning function, to determine which item to map.
+     * @param {Object} [query] - A query object
+     *
+     * @return An array of mapped items
+     */
+    map: <MapType>(mapper: (item: Proto["dbType"]) => MapType, filter?: (item: Proto["dbType"]) => boolean, query?: IndexDb_Query) => Promise<MapType[]>;
+    /**
+     * iterates over all DB objects in the related collection, and reduces them to a single value based on the reducer.
+     * @param {function} reducer - Function that determines who to reduce the array.
+     * @param {*} initialValue - An initial value for the reducer
+     * @param {function} [filter] - Function that determines which DB objects to reduce.
+     * @param {Object} [query] - A query Object.
+     *
+     * @return a single reduced value.
+     */
+    reduce: <ReturnType>(reducer: ReduceFunction<Proto["dbType"], ReturnType>, initialValue: ReturnType, filter?: (item: Proto["dbType"]) => boolean, query?: IndexDb_Query) => Promise<ReturnType>;
+    unique: (_key?: string | IndexKeys<Proto["dbType"], keyof Proto["dbType"]>) => Promise<Proto["dbType"] | undefined>;
+    getLastSync(): number;
+    setLastUpdated(lastUpdated: number): void;
+    syncIndexDb(toUpdate: Proto['dbType'][], toDelete?: DB_Object[]): Promise<void>;
+    count(): Promise<number>;
+}
+export declare class MemCache<Proto extends DBProto<any>> {
+    protected readonly module: ModuleFE_BaseDB<Proto>;
+    private readonly keys;
+    loaded: boolean;
+    _map: Readonly<TypedMap<Readonly<Proto['dbType']>>>;
+    _array: Readonly<Readonly<Proto['dbType']>[]>;
+    protected cacheFilter?: (item: Readonly<Proto['dbType']>) => boolean;
+    constructor(module: ModuleFE_BaseDB<Proto, any>, keys: (keyof Proto['dbType'])[]);
+    setCacheFilter: (filter: (item: Readonly<Proto["dbType"]>) => boolean) => void;
+    forEach: (processor: (item: Readonly<Proto["dbType"]>) => void) => void;
+    clear: () => void;
+    load(cacheFilter?: (item: Readonly<Proto['dbType']>) => boolean): Promise<void>;
+    uniqueAssert: (_key?: Proto["uniqueParam"]) => Readonly<Proto["dbType"]>;
+    unique: (_key?: Proto["uniqueParam"]) => Readonly<Proto["dbType"]> | undefined;
+    all: () => Readonly<Readonly<Proto["dbType"]>[]>;
+    allMutable: () => Readonly<Proto["dbType"]>[];
+    filter: (filter: (item: Readonly<Proto["dbType"]>, index: number, array: Readonly<Proto["dbType"][]>) => boolean) => Readonly<Proto["dbType"]>[];
+    byIds: (ids: Proto["uniqueParam"][]) => Readonly<Proto["dbType"][]>;
+    find: (filter: (item: Readonly<Proto["dbType"]>, index: number, array: Readonly<Proto["dbType"][]>) => boolean) => Readonly<Proto["dbType"]> | undefined;
+    map: <MapType>(mapper: (item: Readonly<Proto["dbType"]>, index: number, array: Readonly<Proto["dbType"][]>) => MapType) => MapType[];
+    sort: (map?: keyof Proto["dbType"] | (keyof Proto["dbType"])[] | ((item: Readonly<Proto["dbType"]>) => any), invert?: boolean) => Readonly<Proto["dbType"]>[];
+    arrayToMap: (getKey: (item: Readonly<Proto["dbType"]>, index: number, map: {
+        [k: string]: Readonly<Proto["dbType"]>;
+    }) => string | number, map?: {
+        [k: string]: Readonly<Proto["dbType"]>;
+    }) => {
+        [k: string]: Readonly<Proto["dbType"]>;
+    };
+    private onEntriesDeleted;
+    private onEntriesUpdated;
+    protected setCache(cacheArray: Readonly<Proto['dbType']>[]): void;
+}