oak-backend-base 4.1.29 → 5.0.0

package/lib/AppLoader.d.ts

@@ -1,6 +1,6 @@
 import { EntityDict as BaseEntityDict } from 'oak-domain/lib/base-app-domain';
 import { AppLoader as GeneralAppLoader, Trigger, EntityDict, Watcher, OpRecord, FreeTimer, OperationResult, BaseTimer } from "oak-domain/lib/types";
-import { BackendRuntimeContext } from 'oak-frontend-base/lib/context/BackendRuntimeContext';
+import { BackendRuntimeContext } from 'oak-domain/lib/context/BackendRuntimeContext';
 import { IncomingHttpHeaders, IncomingMessage } from 'http';
 import { Namespace } from 'socket.io';
 import DataSubscriber from './cluster/DataSubscriber';
@@ -8,6 +8,7 @@ import Synchronizer from './Synchronizer';
 import { AsyncContext } from 'oak-domain/lib/store/AsyncRowStore';
 import { InternalErrorHandler } from './types';
 import { AppDbStore } from './DbStore';
+import { AppLoaderUpgradeOptions, AppLoaderUpgradeResult } from './upgrade';
 export declare class AppLoader<ED extends EntityDict & BaseEntityDict, Cxt extends BackendRuntimeContext<ED>> extends GeneralAppLoader<ED, Cxt> {
     protected dbStore: AppDbStore<ED, Cxt>;
     private aspectDict;
@@ -54,6 +55,7 @@ export declare class AppLoader<ED extends EntityDict & BaseEntityDict, Cxt exten
         message?: string;
     }>;
     initialize(ifExists?: 'drop' | 'omit' | 'dropIfNotStatic'): Promise<void>;
+    upgrade(options?: AppLoaderUpgradeOptions): Promise<AppLoaderUpgradeResult>;
     getStore(): AppDbStore<ED, Cxt>;
     getEndpoints(prefix: string): [string, "post" | "get" | "put" | "delete", string, (params: Record<string, string>, headers: IncomingHttpHeaders, req: IncomingMessage, body?: any) => Promise<{
         headers?: Record<string, string | string[]>;
@@ -87,7 +89,9 @@ export declare class AppLoader<ED extends EntityDict & BaseEntityDict, Cxt exten
      */
     private selectForWBWatcher;
     protected execWatcher(watcher: Watcher<ED, keyof ED, Cxt>): Promise<OperationResult<ED> | undefined>;
+    private lastCheckpointTs;
     protected getCheckpointTs(): number;
+    protected setCheckpointTs(ts: number): void;
     protected checkpoint(): Promise<number>;
     startWatchers(): void;
     protected execBaseTimer(timer: BaseTimer<ED, Cxt>, context: Cxt): Promise<OperationResult<ED>> | undefined;

package/lib/AppLoader.js

@@ -15,10 +15,11 @@ const dependencyBuilder_1 = require("oak-domain/lib/compiler/dependencyBuilder")
 const DataSubscriber_1 = tslib_1.__importDefault(require("./cluster/DataSubscriber"));
 const env_1 = require("./cluster/env");
 const Synchronizer_1 = tslib_1.__importDefault(require("./Synchronizer"));
-const i18n_1 = tslib_1.__importDefault(require("oak-domain/lib/data/i18n"));
 const requirePrj_1 = tslib_1.__importDefault(require("./utils/requirePrj"));
 const dbPriority_1 = require("./utils/dbPriority");
 const DbStore_1 = require("./DbStore");
+const upgrade_1 = require("./upgrade");
+const initializeData_1 = require("./utils/initializeData");
 class AppLoader extends types_1.AppLoader {
     dbStore;
     aspectDict;
@@ -241,13 +242,11 @@ class AppLoader extends types_1.AppLoader {
     async initialize(ifExists) {
         await this.dbStore.initialize({ ifExists });
         const data = this.requireSth('lib/data/index');
-        // oak-domain中只有i18n
-        (0, assert_1.default)(data.i18n);
-        data.i18n.push(...i18n_1.default);
         const context = this.contextBuilder(this.dbStore);
         context.openRootMode();
-        for (const entity in data) {
-            let rows = data[entity];
+        const entities = (0, initializeData_1.getInitializationOrder)(data, this.dbStore.getSchema());
+        for (const entity of entities) {
+            const rows = data[entity];
             if (rows.length > 0) {
                 await context.begin();
                 // 如果是static的对象，只要表中有数据就pass
@@ -267,23 +266,16 @@ class AppLoader extends types_1.AppLoader {
                 }
                 // 再插入所有的行
                 try {
-                    const insertRows = async (idx) => {
-                        const rows2 = rows.slice(idx, 1000);
-                        if (rows2.length > 0) {
-                            await this.dbStore.operate(entity, {
-                                data: rows,
-                                action: 'create',
-                            }, context, {
-                                dontCollect: true,
-                                dontCreateOper: true,
-                                blockTrigger: true,
-                            });
-                            if (rows2.length === 1000) {
-                                await insertRows(idx + 1000);
-                            }
-                        }
-                    };
-                    await insertRows(0);
+                    for (const rows2 of (0, initializeData_1.chunkRows)(rows)) {
+                        await this.dbStore.operate(entity, {
+                            data: rows2,
+                            action: 'create',
+                        }, context, {
+                            dontCollect: true,
+                            dontCreateOper: true,
+                            blockTrigger: true,
+                        });
+                    }
                     await context.commit();
                     console.log(`data in ${entity} initialized, ${rows.length} rows inserted`);
                 }
@@ -296,6 +288,30 @@ class AppLoader extends types_1.AppLoader {
         }
         // await this.dbStore.disconnect(); // 不需要马上断开连接，在initialize后可能还会有操作，unmount时会断开
     }
+    async upgrade(options = {}) {
+        const plan = await this.dbStore.makeUpgradePlan({
+            largeTableRowThreshold: options.largeTableRowThreshold,
+        });
+        let outputDir;
+        let files;
+        if (options.outputDir) {
+            outputDir = (0, path_1.resolve)(this.path, options.outputDir);
+            files = await (0, upgrade_1.writeUpgradeArtifacts)(plan, outputDir, this.dbStore.supportsTransactionalDdl());
+        }
+        const executed = await (0, upgrade_1.applyUpgradePlan)(this.dbStore, plan, options);
+        const remainingPlan = executed.total > 0
+            ? await this.dbStore.makeUpgradePlan({
+                largeTableRowThreshold: options.largeTableRowThreshold,
+            })
+            : undefined;
+        return {
+            plan,
+            remainingPlan,
+            outputDir,
+            files,
+            executed,
+        };
+    }
     getStore() {
         return this.dbStore;
     }
@@ -540,12 +556,18 @@ class AppLoader extends types_1.AppLoader {
             // 这里只需要清理被执行的行，因为被跳过的行本来就不是这一次执行被占用的。
         }
     }
+    lastCheckpointTs = 0;
     getCheckpointTs() {
-        const now = Date.now();
-        return process.env.NODE_ENV === 'development' ? now - 30 * 1000 : now - 120 * 1000;
+        return this.lastCheckpointTs;
     }
-    checkpoint() {
-        return this.dbStore.checkpoint(this.getCheckpointTs());
+    setCheckpointTs(ts) {
+        this.lastCheckpointTs = ts;
+    }
+    async checkpoint() {
+        const now = Date.now();
+        const count = await this.dbStore.checkpoint(this.getCheckpointTs());
+        this.setCheckpointTs(now);
+        return count;
     }
     startWatchers() {
         const watchers = this.requireSth('lib/watchers/index');

package/lib/ClusterAppLoader.d.ts

@@ -1,6 +1,6 @@
 import { EntityDict as BaseEntityDict } from 'oak-domain/lib/base-app-domain';
 import { EntityDict, OperationResult, Trigger, Watcher, FreeTimer, BaseTimer } from 'oak-domain/lib/types';
-import { BackendRuntimeContext } from 'oak-frontend-base/lib/context/BackendRuntimeContext';
+import { BackendRuntimeContext } from 'oak-domain/lib/context/BackendRuntimeContext';
 import { AppLoader } from './AppLoader';
 import { Namespace } from 'socket.io';
 import { Socket } from 'socket.io-client';

package/lib/ClusterAppLoader.js

@@ -183,6 +183,7 @@ class ClusterAppLoader extends AppLoader_1.AppLoader {
     async checkpoint() {
         const { instanceCount, instanceId } = (0, env_1.getClusterInfo)();
         let count = 0;
+        const now = Date.now();
         for (const name in this.commitTriggers) {
             if (this.commitTriggers[name]) {
                 count += await this.dbStore.independentCheckPoint(name, this.getCheckpointTs(), instanceCount, instanceId);
@@ -191,6 +192,7 @@ class ClusterAppLoader extends AppLoader_1.AppLoader {
                 count += await this.dbStore.independentCheckPoint(name, this.getCheckpointTs());
             }
         }
+        this.setCheckpointTs(now);
         return count;
     }
 }

package/lib/DbStore.d.ts

@@ -1,7 +1,7 @@
 import { DbConfiguration } from 'oak-db/src/types/configuration';
 import { EntityDict, StorageSchema, Trigger, Checker, SelectFreeEntities, UpdateFreeDict, AuthDeduceRelationMap, VolatileTrigger, OperateOption } from 'oak-domain/lib/types';
 import { EntityDict as BaseEntityDict } from 'oak-domain/lib/base-app-domain';
-import { BackendRuntimeContext } from 'oak-frontend-base/lib/context/BackendRuntimeContext';
+import { BackendRuntimeContext } from 'oak-domain/lib/context/BackendRuntimeContext';
 import { DbTypeSymbol } from './utils/dbPriority';
 import { CascadeStore } from 'oak-domain/lib/store/CascadeStore';
 import { DbStore } from 'oak-db/lib/types/dbStore';

package/lib/Synchronizer.d.ts

@@ -1,7 +1,7 @@
 import { EntityDict, StorageSchema, EndpointItem, SyncConfig } from 'oak-domain/lib/types';
 import { VolatileTrigger } from 'oak-domain/lib/types/Trigger';
 import { EntityDict as BaseEntityDict } from 'oak-domain/lib/base-app-domain';
-import { BackendRuntimeContext } from 'oak-frontend-base/lib/context/BackendRuntimeContext';
+import { BackendRuntimeContext } from 'oak-domain/lib/context/BackendRuntimeContext';
 export type FetchFn = (url: string, options: {
     method: string;
     headers: Record<string, string>;

package/lib/Synchronizer.js

@@ -406,7 +406,7 @@ class Synchronizer {
     makeCreateOperTrigger() {
         const { config } = this;
         const { remotes, self } = config;
-        const entityActionMap = new Map();
+        const checkActionsMap = {};
         // 根据remotes定义，建立从entity到需要同步的远端结点信息的Map
         remotes.forEach((remote) => {
             const { getPushInfo, pushEntities: pushEntityDefs, endpoint, pathToUser, relationName: rnRemote, onFailed, timeout } = remote;
@@ -416,34 +416,19 @@ class Synchronizer {
                 for (const def of pushEntityDefs) {
                     const { pathToRemoteEntity, pathToSelfEntity, relationName, recursive, entity, actions, onSynchronized } = def;
                     pushEntities.push(entity);
-                    if (!entityActionMap.has(entity)) {
-                        entityActionMap.set(entity, {
-                            actions: new Set(),
-                            matchAllActions: false,
-                        });
-                    }
-                    const tracker = entityActionMap.get(entity);
-                    //如果当前定义是 wildcard（所有 action）
-                    if (!actions || actions.length === 0) {
-                        if (tracker.matchAllActions) {
-                            throw new Error(`PushEntityDef 配置错误：entity「${entity}」的所有 action 被定义了多次`);
-                        }
-                        if (tracker.actions.size > 0) {
-                            throw new Error(`PushEntityDef 配置错误：entity「${entity}」已定义特定 action「${Array.from(tracker.actions).join(', ')}」，不能再定义所有 action`);
-                        }
-                        tracker.matchAllActions = true;
+                    (0, assert_1.default)(pathToRemoteEntity, 'pushEntityDef必须定义pathToRemoteEntity');
+                    (0, assert_1.default)(pathToSelfEntity, 'pushEntityDef必须定义pathToSelfEntity');
+                    (0, assert_1.default)(actions && actions.length > 0, 'pushEntityDef必须定义actions，并且长度必须大于0');
+                    const checkKey = `${String(entity)}-${pathToRemoteEntity}-${pathToSelfEntity}`;
+                    if (!checkActionsMap[checkKey]) {
+                        checkActionsMap[checkKey] = new Set();
                     }
-                    else {
-                        // 如果当前定义是特定 action
-                        if (tracker.matchAllActions) {
-                            throw new Error(`PushEntityDef 配置错误：entity「${entity}」已定义所有 action，不能再定义特定 action「${actions.join(', ')}」`);
-                        }
-                        for (const action of actions) {
-                            if (tracker.actions.has(action)) {
-                                throw new Error(`PushEntityDef 配置错误：entity「${entity}」的action「${action}」被定义了多次`);
-                            }
-                            tracker.actions.add(action);
+                    const checkActions = checkActionsMap[checkKey];
+                    for (const action of actions) {
+                        if (checkActions.has(action)) {
+                            throw new Error(`pushEntityDef中发现重复的entity/pathToRemoteEntity/pathToSelfEntity/action组合，重复的action是「${action}」，entity是「${String(entity)}」，pathToRemoteEntity是「${pathToRemoteEntity}」，pathToSelfEntity是「${pathToSelfEntity}」`);
                         }
+                        checkActions.add(action);
                     }
                     const relationName2 = relationName || rnRemote;
                     const path2 = pathToUser ? `${pathToRemoteEntity}.${pathToUser}` : pathToRemoteEntity;

package/lib/cluster/DataSubscriber.d.ts

@@ -1,6 +1,6 @@
 import { EntityDict, OpRecord } from 'oak-domain/lib/types';
 import { EntityDict as BaseEntityDict } from 'oak-domain/lib/base-app-domain';
-import { BackendRuntimeContext } from 'oak-frontend-base/lib/context/BackendRuntimeContext';
+import { BackendRuntimeContext } from 'oak-domain/lib/context/BackendRuntimeContext';
 import { Namespace } from 'socket.io';
 /**
  * 集群行为备忘：

package/lib/index.d.ts

@@ -1,3 +1,4 @@
 export { AppLoader } from './AppLoader';
 export { ClusterAppLoader } from './ClusterAppLoader';
 export * from './cluster/env';
+export * from './upgrade';

package/lib/index.js

@@ -7,3 +7,4 @@ Object.defineProperty(exports, "AppLoader", { enumerable: true, get: function ()
 var ClusterAppLoader_1 = require("./ClusterAppLoader");
 Object.defineProperty(exports, "ClusterAppLoader", { enumerable: true, get: function () { return ClusterAppLoader_1.ClusterAppLoader; } });
 tslib_1.__exportStar(require("./cluster/env"), exports);
+tslib_1.__exportStar(require("./upgrade"), exports);

package/lib/routines/update.d.ts

@@ -1,6 +1,6 @@
 import { EntityDict as TypeEntityDict, StorageSchema } from 'oak-domain/lib/types';
 import { AsyncContext } from 'oak-domain/lib/store/AsyncRowStore';
-import BackendRuntimeContext from 'oak-frontend-base/lib/context/BackendRuntimeContext';
+import BackendRuntimeContext from 'oak-domain/lib/context/BackendRuntimeContext';
 import { EntityDict as BaseEntityDict } from 'oak-domain/lib/base-app-domain';
 type EntityDict = TypeEntityDict & BaseEntityDict;
 /**

package/lib/types/Sync.d.ts

@@ -1,16 +1,16 @@
-import { EntityDict } from 'oak-domain/lib/types';
-import { EntityDict as BaseEntityDict } from 'oak-domain/lib/base-app-domain';
-import { BackendRuntimeContext } from 'oak-frontend-base/lib/context/BackendRuntimeContext';
-import { RemotePushInfo, RemotePullInfo, SelfEncryptInfo, SyncRemoteConfigBase, SyncSelfConfigBase, SyncConfig } from 'oak-domain/lib/types/Sync';
-interface SyncRemoteConfigWrapper<ED extends EntityDict & BaseEntityDict, Cxt extends BackendRuntimeContext<ED>> extends SyncRemoteConfigBase<ED, Cxt> {
-    getRemotePushInfo: (userId: string) => Promise<RemotePushInfo>;
-    getRemotePullInfo: (id: string) => Promise<RemotePullInfo>;
-}
-interface SyncSelfConfigWrapper<ED extends EntityDict & BaseEntityDict> extends SyncSelfConfigBase<ED> {
-    getSelfEncryptInfo: () => Promise<SelfEncryptInfo>;
-}
-export interface SyncConfigWrapper<ED extends EntityDict & BaseEntityDict, Cxt extends BackendRuntimeContext<ED>> {
-    self: SyncSelfConfigWrapper<ED>;
-    remotes: Array<SyncRemoteConfigWrapper<ED, Cxt>>;
-}
-export { RemotePushInfo, RemotePullInfo, SelfEncryptInfo, SyncConfig, };
+import { EntityDict } from 'oak-domain/lib/types';
+import { EntityDict as BaseEntityDict } from 'oak-domain/lib/base-app-domain';
+import { BackendRuntimeContext } from 'oak-domain/lib/context/BackendRuntimeContext';
+import { RemotePushInfo, RemotePullInfo, SelfEncryptInfo, SyncRemoteConfigBase, SyncSelfConfigBase, SyncConfig } from 'oak-domain/lib/types/Sync';
+interface SyncRemoteConfigWrapper<ED extends EntityDict & BaseEntityDict, Cxt extends BackendRuntimeContext<ED>> extends SyncRemoteConfigBase<ED, Cxt> {
+    getRemotePushInfo: (userId: string) => Promise<RemotePushInfo>;
+    getRemotePullInfo: (id: string) => Promise<RemotePullInfo>;
+}
+interface SyncSelfConfigWrapper<ED extends EntityDict & BaseEntityDict> extends SyncSelfConfigBase<ED> {
+    getSelfEncryptInfo: () => Promise<SelfEncryptInfo>;
+}
+export interface SyncConfigWrapper<ED extends EntityDict & BaseEntityDict, Cxt extends BackendRuntimeContext<ED>> {
+    self: SyncSelfConfigWrapper<ED>;
+    remotes: Array<SyncRemoteConfigWrapper<ED, Cxt>>;
+}
+export { RemotePushInfo, RemotePullInfo, SelfEncryptInfo, SyncConfig, };

package/lib/upgrade.d.ts

@@ -0,0 +1,50 @@
+import { MigrationPlanningOptions, Plan } from 'oak-db';
+export interface UpgradeExecutionOptions {
+    execute?: boolean;
+}
+export interface AppLoaderUpgradeOptions extends UpgradeExecutionOptions, MigrationPlanningOptions {
+    outputDir?: string;
+}
+export interface UpgradeOutputFiles {
+    migrationSql: string;
+    rollbackSql: string;
+    summary: string;
+    tableChanges: string;
+    warnings: string;
+    renameCandidates: string;
+}
+export interface UpgradeExecutionSummary {
+    prepareSql: number;
+    forwardSql: number;
+    onlineSql: number;
+    manualSql: number;
+    backwardSql: number;
+    total: number;
+}
+export interface AppLoaderUpgradeResult {
+    plan: Plan;
+    remainingPlan?: Plan;
+    outputDir?: string;
+    files?: UpgradeOutputFiles;
+    executed: UpgradeExecutionSummary;
+}
+type SqlExecutor = {
+    exec(sql: string, txnId?: string): Promise<void>;
+    begin(): Promise<string>;
+    commit(txnId: string): Promise<void>;
+    rollback(txnId: string): Promise<void>;
+    supportsTransactionalDdl(): boolean;
+};
+type SqlCategory = keyof Omit<UpgradeExecutionSummary, 'total'>;
+type OrderedSqlStep = {
+    sql: string;
+    category: SqlCategory;
+    group: number;
+    table?: string;
+    order: number;
+};
+export declare function buildOrderedUpgradeSteps(plan: Plan): OrderedSqlStep[];
+export declare function buildOrderedRollbackSteps(plan: Plan): OrderedSqlStep[];
+export declare function writeUpgradeArtifacts(plan: Plan, outputDir: string, supportsTransactionalDdl?: boolean): Promise<UpgradeOutputFiles>;
+export declare function applyUpgradePlan(executor: SqlExecutor, plan: Plan, options?: UpgradeExecutionOptions): Promise<UpgradeExecutionSummary>;
+export {};

package/lib/upgrade.js

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOrderedUpgradeSteps = buildOrderedUpgradeSteps;
+exports.buildOrderedRollbackSteps = buildOrderedRollbackSteps;
+exports.writeUpgradeArtifacts = writeUpgradeArtifacts;
+exports.applyUpgradePlan = applyUpgradePlan;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const categoryOrder = [
+    'prepareSql',
+    'forwardSql',
+    'onlineSql',
+    'manualSql',
+    'backwardSql',
+];
+const executableCategoryOrder = [
+    'prepareSql',
+    'forwardSql',
+    'onlineSql',
+    'manualSql',
+];
+function makeExecutionSummary() {
+    return {
+        prepareSql: 0,
+        forwardSql: 0,
+        onlineSql: 0,
+        manualSql: 0,
+        backwardSql: 0,
+        total: 0,
+    };
+}
+function extractTableName(sql) {
+    const patterns = [
+        /alter\s+table\s+[`"]([^`"]+)[`"]/i,
+        /create\s+table(?:\s+if\s+not\s+exists)?\s+[`"]([^`"]+)[`"]/i,
+        /drop\s+table(?:\s+if\s+exists)?\s+[`"]([^`"]+)[`"]/i,
+        /create\s+(?:unique\s+)?index(?:\s+concurrently)?(?:\s+if\s+not\s+exists)?\s+[`"][^`"]+[`"]\s+on\s+[`"]([^`"]+)[`"]/i,
+    ];
+    for (const pattern of patterns) {
+        const match = sql.match(pattern);
+        if (match) {
+            return match[1];
+        }
+    }
+    return undefined;
+}
+function isCreateTableSql(sql) {
+    return /create\s+table/i.test(sql);
+}
+function isDropTableSql(sql) {
+    return /drop\s+table/i.test(sql);
+}
+function isForeignKeyDropSql(sql) {
+    return /drop\s+(?:foreign\s+key|constraint)/i.test(sql);
+}
+function isForeignKeyAddSql(sql) {
+    return /add\s+constraint\s+.*foreign\s+key|add\s+foreign\s+key/i.test(sql);
+}
+function isColumnSql(sql) {
+    return /add\s+column|modify\s+column|alter\s+column|rename\s+column/i.test(sql);
+}
+function isIndexSql(sql) {
+    return /rename\s+index|create\s+(?:unique\s+)?index|add\s+(?:unique\s+|fulltext\s+|spatial\s+)?index|drop\s+index|alter\s+index/i.test(sql);
+}
+function getCategoryPriority(category) {
+    switch (category) {
+        case 'prepareSql':
+            return 0;
+        case 'manualSql':
+            return 1;
+        case 'forwardSql':
+            return 2;
+        case 'onlineSql':
+            return 3;
+        case 'backwardSql':
+            return 4;
+    }
+}
+function classifySqlGroup(sql, category) {
+    if (category === 'prepareSql') {
+        return 0;
+    }
+    if (category === 'manualSql') {
+        // manualSql 往往已经带着 planner 计算好的执行顺序，
+        // 例如 PostgreSQL enum 重建需要 rename/create/alter/drop 保持原样串行。
+        return 0;
+    }
+    if (category === 'backwardSql') {
+        if (isForeignKeyDropSql(sql)) {
+            return 60;
+        }
+        if (isIndexSql(sql)) {
+            return 70;
+        }
+        if (/drop\s+column/i.test(sql)) {
+            return 80;
+        }
+        if (isDropTableSql(sql)) {
+            return 90;
+        }
+        return 85;
+    }
+    if (isCreateTableSql(sql)) {
+        return 10;
+    }
+    if (isForeignKeyDropSql(sql)) {
+        return 15;
+    }
+    if (isColumnSql(sql)) {
+        return 20;
+    }
+    if (isIndexSql(sql) || category === 'onlineSql') {
+        return 30;
+    }
+    if (isForeignKeyAddSql(sql)) {
+        return 40;
+    }
+    return 50;
+}
+function buildOrderedSteps(plan, categories) {
+    let order = 0;
+    const steps = [];
+    for (const category of categories) {
+        for (const sql of plan[category]) {
+            steps.push({
+                sql,
+                category,
+                group: classifySqlGroup(sql, category),
+                table: extractTableName(sql),
+                order: order++,
+            });
+        }
+    }
+    return steps.sort((left, right) => getCategoryPriority(left.category) - getCategoryPriority(right.category)
+        || left.group - right.group
+        || left.order - right.order);
+}
+function buildOrderedUpgradeSteps(plan) {
+    return buildOrderedSteps(plan, executableCategoryOrder);
+}
+function buildOrderedRollbackSteps(plan) {
+    return buildOrderedSteps(plan, ['backwardSql']);
+}
+function toSqlFileContent(sqls) {
+    return sqls.length > 0 ? `${sqls.join('\n')}\n` : '';
+}
+function buildArtifactSqlStatements(steps, supportsTransactionalDdl = false) {
+    const sqls = [];
+    let openedTransaction = false;
+    const flushTransaction = () => {
+        if (!openedTransaction) {
+            return;
+        }
+        sqls.push('COMMIT;');
+        openedTransaction = false;
+    };
+    for (const step of steps) {
+        const transactional = supportsTransactionalDdl
+            && step.category !== 'prepareSql'
+            && step.category !== 'onlineSql';
+        if (transactional) {
+            if (!openedTransaction) {
+                sqls.push('BEGIN;');
+                openedTransaction = true;
+            }
+        }
+        else {
+            flushTransaction();
+        }
+        sqls.push(step.sql);
+    }
+    flushTransaction();
+    return sqls;
+}
+function getTableChanges(plan) {
+    return plan.tableChanges || [];
+}
+function buildTableChangeSummary(plan) {
+    const tableChanges = getTableChanges(plan);
+    return {
+        total: tableChanges.length,
+        create: tableChanges.filter((item) => item.lifecycle === 'create').length,
+        alter: tableChanges.filter((item) => item.lifecycle === 'alter').length,
+        drop: tableChanges.filter((item) => item.lifecycle === 'drop').length,
+    };
+}
+async function writeUpgradeArtifacts(plan, outputDir, supportsTransactionalDdl = false) {
+    await (0, promises_1.mkdir)(outputDir, {
+        recursive: true,
+    });
+    const files = {
+        migrationSql: (0, path_1.join)(outputDir, 'migration.sql'),
+        rollbackSql: (0, path_1.join)(outputDir, 'rollback.sql'),
+        summary: (0, path_1.join)(outputDir, 'summary.json'),
+        tableChanges: (0, path_1.join)(outputDir, 'table-changes.json'),
+        warnings: (0, path_1.join)(outputDir, 'warnings.json'),
+        renameCandidates: (0, path_1.join)(outputDir, 'rename-candidates.json'),
+    };
+    const orderedSql = buildArtifactSqlStatements(buildOrderedUpgradeSteps(plan), supportsTransactionalDdl);
+    const rollbackSql = buildArtifactSqlStatements(buildOrderedRollbackSteps(plan), supportsTransactionalDdl);
+    await Promise.all([
+        (0, promises_1.writeFile)(files.migrationSql, toSqlFileContent(orderedSql), 'utf8'),
+        (0, promises_1.writeFile)(files.rollbackSql, toSqlFileContent(rollbackSql), 'utf8'),
+        (0, promises_1.writeFile)(files.summary, `${JSON.stringify({
+            summary: plan.summary,
+            tables: buildTableChangeSummary(plan),
+            generatedAt: new Date().toISOString(),
+        }, null, 2)}\n`, 'utf8'),
+        (0, promises_1.writeFile)(files.tableChanges, `${JSON.stringify(getTableChanges(plan), null, 2)}\n`, 'utf8'),
+        (0, promises_1.writeFile)(files.warnings, `${JSON.stringify(plan.warnings, null, 2)}\n`, 'utf8'),
+        (0, promises_1.writeFile)(files.renameCandidates, `${JSON.stringify(plan.renameCandidates, null, 2)}\n`, 'utf8'),
+    ]);
+    return files;
+}
+async function executeOrderedSqlSteps(executor, steps, summary) {
+    if (steps.length === 0) {
+        return;
+    }
+    let txnId;
+    const supportsTransactionalDdl = executor.supportsTransactionalDdl();
+    const flushTransaction = async () => {
+        if (!txnId) {
+            return;
+        }
+        await executor.commit(txnId);
+        txnId = undefined;
+    };
+    try {
+        for (const step of steps) {
+            const transactional = supportsTransactionalDdl
+                && step.category !== 'prepareSql'
+                && step.category !== 'onlineSql';
+            if (!transactional) {
+                await flushTransaction();
+                await executor.exec(step.sql);
+            }
+            else {
+                if (!txnId) {
+                    txnId = await executor.begin();
+                }
+                await executor.exec(step.sql, txnId);
+            }
+            summary[step.category] += 1;
+            summary.total += 1;
+        }
+        await flushTransaction();
+    }
+    catch (err) {
+        if (txnId) {
+            await executor.rollback(txnId);
+        }
+        throw err;
+    }
+}
+async function applyUpgradePlan(executor, plan, options = {}) {
+    const summary = makeExecutionSummary();
+    if (!options.execute) {
+        return summary;
+    }
+    await executeOrderedSqlSteps(executor, buildOrderedUpgradeSteps(plan), summary);
+    return summary;
+}

package/lib/utils/dbPriority.d.ts

@@ -2,7 +2,7 @@ import { MysqlStore, PostgreSQLStore } from "oak-db";
 import { DbConfiguration } from "oak-db/src/types/configuration";
 import { EntityDict, StorageSchema } from 'oak-domain/lib/types';
 import { EntityDict as BaseEntityDict } from 'oak-domain/lib/base-app-domain';
-import { BackendRuntimeContext } from 'oak-frontend-base/lib/context/BackendRuntimeContext';
+import { BackendRuntimeContext } from 'oak-domain/lib/context/BackendRuntimeContext';
 import { CascadeStore } from "oak-domain/lib/store/CascadeStore";
 import { DbStore } from "oak-db/lib/types/dbStore";
 /**

package/lib/utils/initializeData.d.ts

@@ -0,0 +1,5 @@
+import { EntityDict, StorageSchema } from 'oak-domain/lib/types';
+type SerializedData = Record<string, unknown[]>;
+export declare function getInitializationOrder<ED extends EntityDict>(data: SerializedData, schema: StorageSchema<ED>): string[];
+export declare function chunkRows<T>(rows: T[], size?: number): Generator<T[], void, unknown>;
+export {};

package/lib/utils/initializeData.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInitializationOrder = getInitializationOrder;
+exports.chunkRows = chunkRows;
+function collectEntityDependencies(entity, schema, entitySet) {
+    const desc = schema[entity];
+    if (!desc) {
+        return new Set();
+    }
+    const dependencies = new Set();
+    for (const attr of Object.values(desc.attributes || {})) {
+        if (attr.type !== 'ref' || !attr.ref) {
+            continue;
+        }
+        const refs = Array.isArray(attr.ref) ? attr.ref : [attr.ref];
+        for (const ref of refs) {
+            if (ref !== entity && entitySet.has(ref)) {
+                dependencies.add(ref);
+            }
+        }
+    }
+    return dependencies;
+}
+function getInitializationOrder(data, schema) {
+    const entities = Object.keys(data).filter((entity) => Array.isArray(data[entity]));
+    const entitySet = new Set(entities);
+    const dependencies = Object.fromEntries(entities.map((entity) => [
+        entity,
+        collectEntityDependencies(entity, schema, entitySet),
+    ]));
+    const ordered = [];
+    const initialized = new Set();
+    const pending = new Set(entities);
+    while (pending.size > 0) {
+        let progressed = false;
+        for (const entity of entities) {
+            if (!pending.has(entity)) {
+                continue;
+            }
+            const deps = dependencies[entity];
+            if ([...deps].every((dep) => initialized.has(dep))) {
+                ordered.push(entity);
+                initialized.add(entity);
+                pending.delete(entity);
+                progressed = true;
+            }
+        }
+        if (!progressed) {
+            const rest = entities.filter((entity) => pending.has(entity));
+            console.warn(`data initialization order has circular or unresolved dependencies, fallback to original order: ${rest.join(', ')}`);
+            ordered.push(...rest);
+            break;
+        }
+    }
+    return ordered;
+}
+function* chunkRows(rows, size = 1000) {
+    for (let idx = 0; idx < rows.length; idx += size) {
+        yield rows.slice(idx, idx + size);
+    }
+}

package/package.json

@@ -1,7 +1,10 @@
 {
     "name": "oak-backend-base",
-    "version": "4.1.29",
+    "version": "5.0.0",
     "description": "oak-backend-base",
+    "oak": {
+        "package": true
+    },
     "main": "lib/index",
     "author": {
         "name": "XuChang"
@@ -24,10 +27,9 @@
         "mysql": "^2.18.1",
         "mysql2": "^2.3.3",
         "node-schedule": "^2.1.0",
-        "oak-common-aspect": "^3.0.6",
-        "oak-db": "^3.3.14",
-        "oak-domain": "^5.1.36",
-        "oak-frontend-base": "^5.3.46",
+        "oak-common-aspect": "^4.0.0",
+        "oak-db": "^4.0.1",
+        "oak-domain": "^6.0.0",
         "socket.io": "^4.8.1",
         "socket.io-client": "^4.7.2",
         "uuid": "^8.3.2"