@naturalcycles/db-lib 10.42.0 → 10.42.2

package/dist/adapter/file/file.db.d.ts

@@ -1,4 +1,4 @@
-import { type ObjectWithId } from '@naturalcycles/js-lib/types';
+import type { ObjectWithId } from '@naturalcycles/js-lib/types';
 import type { JsonSchema } from '@naturalcycles/nodejs-lib/ajv';
 import { Pipeline } from '@naturalcycles/nodejs-lib/stream';
 import { BaseCommonDB } from '../../commondb/base.common.db.js';

package/dist/adapter/file/file.db.js

@@ -3,7 +3,7 @@ import { _by, _sortBy } from '@naturalcycles/js-lib/array';
 import { _since, localTime } from '@naturalcycles/js-lib/datetime';
 import { _assert } from '@naturalcycles/js-lib/error/assert.js';
 import { _deepEquals, _filterUndefinedValues, _sortObjectDeep } from '@naturalcycles/js-lib/object';
-import { _stringMapValues, } from '@naturalcycles/js-lib/types';
+import { _stringMapValues } from '@naturalcycles/js-lib/types';
 import { generateJsonSchemaFromData } from '@naturalcycles/nodejs-lib/ajv';
 import { dimGrey } from '@naturalcycles/nodejs-lib/colors';
 import { Pipeline } from '@naturalcycles/nodejs-lib/stream';

package/dist/adapter/file/localFile.persistence.plugin.js

@@ -28,7 +28,7 @@ export class LocalFilePersistencePlugin {
         return await Pipeline.fromNDJsonFile(filePath).toArray();
     }
     async saveFiles(ops) {
-        await pMap(ops, async (op) => await this.saveFile(op.table, op.rows), { concurrency: 32 });
+        await pMap(ops, async op => await this.saveFile(op.table, op.rows), { concurrency: 32 });
     }
     async saveFile(table, rows) {
         await fs2.ensureDirAsync(this.cfg.storagePath);

package/dist/cnst.js

@@ -1,4 +1,5 @@
-export var DBLibError;
+export { DBLibError };
+var DBLibError;
 (function (DBLibError) {
     DBLibError["DB_ROW_REQUIRED"] = "DB_ROW_REQUIRED";
     DBLibError["DAO_IS_READ_ONLY"] = "DAO_IS_READ_ONLY";

package/dist/commondao/common.dao.d.ts

@@ -1,4 +1,4 @@
-import { type BaseDBEntity, type NonNegativeInteger, type StringMap, type Unsaved } from '@naturalcycles/js-lib/types';
+import type { BaseDBEntity, NonNegativeInteger, ObjectWithId, StringMap, Unsaved } from '@naturalcycles/js-lib/types';
 import type { JsonSchema } from '@naturalcycles/nodejs-lib/ajv';
 import type { Pipeline } from '@naturalcycles/nodejs-lib/stream';
 import type { CommonDBTransactionOptions, RunQueryResult } from '../db.model.js';
@@ -9,9 +9,12 @@ import { CommonDaoTransaction } from './commonDaoTransaction.js';
 /**
  * Lowest common denominator API between supported Databases.
  *
- * DBM = Database model (how it's stored in DB)
  * BM = Backend model (optimized for API access)
+ * DBM = Database model (logical representation, before compression)
  * TM = Transport model (optimized to be sent over the wire)
+ *
+ * Note: When auto-compression is enabled, the physical storage format differs from DBM.
+ * Compression/decompression is handled transparently at the storage boundary.
  */
 export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, ID extends string = BM['id']> {
     cfg: CommonDaoCfg<BM, DBM, ID>;
@@ -46,7 +49,6 @@ export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity
     runQueryCount(q: DBQuery<DBM>, opt?: CommonDaoReadOptions): Promise<number>;
     streamQueryAsDBM(q: DBQuery<DBM>, opt?: CommonDaoStreamOptions<DBM>): Pipeline<DBM>;
     streamQuery(q: DBQuery<DBM>, opt?: CommonDaoStreamOptions<BM>): Pipeline<BM>;
-    private streamQueryRaw;
     queryIds(q: DBQuery<DBM>, opt?: CommonDaoReadOptions): Promise<ID[]>;
     streamQueryIds(q: DBQuery<DBM>, opt?: CommonDaoStreamOptions<ID>): Pipeline<ID>;
     /**
@@ -132,13 +134,36 @@ export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity
     bmToDBM(bm?: BM, opt?: CommonDaoOptions): Promise<DBM>;
     bmsToDBM(bms: BM[], opt?: CommonDaoOptions): Promise<DBM[]>;
     /**
-     * Mutates `dbm`.
+     * Converts a DBM to storage format, applying compression if configured.
+     *
+     * Use this when you need to write directly to the database, bypassing the DAO save methods.
+     * The returned value is opaque and should only be passed to db.saveBatch() or similar.
+     *
+     * @example
+     * const storageRow = await dao.dbmToStorageRow(dbm)
+     * await db.saveBatch(table, [storageRow])
+     */
+    dbmToStorageRow(dbm: DBM): Promise<ObjectWithId>;
+    /**
+     * Converts multiple DBMs to storage rows.
+     */
+    dbmsToStorageRows(dbms: DBM[]): Promise<ObjectWithId[]>;
+    /**
+     * Converts a storage row back to a DBM, applying decompression if needed.
+     *
+     * Use this when you need to read directly from the database, bypassing the DAO load methods.
+     *
+     * @example
+     * const rows = await db.getByIds(table, ids)
+     * const dbms = await Promise.all(rows.map(row => dao.storageRowToDBM(row)))
      */
-    compress(dbm: DBM): Promise<void>;
+    storageRowToDBM(row: ObjectWithId): Promise<DBM>;
     /**
-     * Mutates `dbm`.
+     * Converts multiple storage rows to DBMs.
      */
-    decompress(dbm: DBM): Promise<void>;
+    storageRowsToDBMs(rows: ObjectWithId[]): Promise<DBM[]>;
+    private compress;
+    private decompress;
     anyToDBM(dbm: undefined, opt?: CommonDaoOptions): Promise<null>;
     anyToDBM(dbm?: any, opt?: CommonDaoOptions): Promise<DBM>;
     anyToDBMs(rows: DBM[], opt?: CommonDaoOptions): Promise<DBM[]>;
@@ -158,6 +183,43 @@ export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity
     withIds(ids: ID[]): DaoWithIds<CommonDao<BM, DBM, ID>>;
     withRowsToSave(rows: Unsaved<BM>[]): DaoWithRows<CommonDao<BM, DBM, ID>>;
     withRowToSave(row: Unsaved<BM>, opt?: DaoWithRowOptions<BM>): DaoWithRow<CommonDao<BM, DBM, ID>>;
+    /**
+     * Helper to decompress legacy compressed data when migrating away from auto-compression.
+     * Use as your `beforeDBMToBM` hook to decompress legacy rows on read.
+     *
+     * @example
+     * const dao = new CommonDao({
+     *   hooks: {
+     *     beforeDBMToBM: CommonDao.decompressLegacyRow,
+     *   }
+     * })
+     *
+     * // Or within an existing hook:
+     * beforeDBMToBM: async (dbm) => {
+     *   await CommonDao.decompressLegacyRow(dbm)
+     *   // ... other transformations
+     *   return dbm
+     * }
+     */
+    static decompressLegacyRow<T extends ObjectWithId>(row: T): Promise<T>;
+    /**
+     * Temporary helper to migrate from the old `data` compressed property to the new `__compressed` property.
+     * Use as your `beforeDBMToBM` hook during the migration period.
+     *
+     * Migration steps:
+     * 1. Add `beforeDBMToBM: CommonDao.migrateCompressedDataProperty` to your hooks
+     * 2. Deploy - old data (with `data` property) will be decompressed on read and recompressed to `__compressed` on write
+     * 3. Once all data has been naturally rewritten, remove the hook
+     *
+     * @example
+     * const dao = new CommonDao({
+     *   compress: { keys: ['field1', 'field2'] },
+     *   hooks: {
+     *     beforeDBMToBM: CommonDao.migrateCompressedDataProperty,
+     *   }
+     * })
+     */
+    static migrateCompressedDataProperty<T extends ObjectWithId>(row: T): Promise<T>;
     /**
      * Load rows (by their ids) from Multiple tables at once.
      * An optimized way to load data, minimizing DB round-trips.

package/dist/commondao/common.dao.js

@@ -14,9 +14,12 @@ import { CommonDaoTransaction } from './commonDaoTransaction.js';
 /**
  * Lowest common denominator API between supported Databases.
  *
- * DBM = Database model (how it's stored in DB)
  * BM = Backend model (optimized for API access)
+ * DBM = Database model (logical representation, before compression)
  * TM = Transport model (optimized to be sent over the wire)
+ *
+ * Note: When auto-compression is enabled, the physical storage format differs from DBM.
+ * Compression/decompression is handled transparently at the storage boundary.
  */
 export class CommonDao {
     cfg;
@@ -44,6 +47,15 @@ export class CommonDao {
         else {
             delete this.cfg.hooks.createRandomId;
         }
+        // If the auto-compression is enabled,
+        // then we need to ensure that the '__compressed' property is part of the index exclusion list.
+        if (this.cfg.compress?.keys) {
+            const current = this.cfg.excludeFromIndexes;
+            this.cfg.excludeFromIndexes = current ? [...current] : [];
+            if (!this.cfg.excludeFromIndexes.includes('__compressed')) {
+                this.cfg.excludeFromIndexes.push('__compressed');
+            }
+        }
     }
     // CREATE
     create(part = {}, opt = {}) {
@@ -92,7 +104,8 @@ export class CommonDao {
         if (!ids.length)
             return [];
         const table = opt.table || this.cfg.table;
-        return await (opt.tx || this.cfg.db).getByIds(table, ids, opt);
+        const rows = await (opt.tx || this.cfg.db).getByIds(table, ids, opt);
+        return await this.storageRowsToDBMs(rows);
     }
     async getBy(by, value, limit = 0, opt) {
         return await this.query().filterEq(by, value).limit(limit).runQuery(opt);
@@ -127,14 +140,15 @@ export class CommonDao {
      * Order is not guaranteed, as queries run in parallel.
      */
     async runUnionQueries(queries, opt) {
-        const results = (await pMap(queries, async (q) => (await this.runQueryExtended(q, opt)).rows)).flat();
+        const results = (await pMap(queries, async q => (await this.runQueryExtended(q, opt)).rows)).flat();
         return _uniqBy(results, r => r.id);
     }
     async runQueryExtended(q, opt = {}) {
         this.validateQueryIndexes(q); // throws if query uses `excludeFromIndexes` property
         q.table = opt.table || q.table;
-        const { rows, ...queryResult } = await this.cfg.db.runQuery(q, opt);
+        const { rows: rawRows, ...queryResult } = await this.cfg.db.runQuery(q, opt);
         const isPartialQuery = !!q._selectedFieldNames;
+        const rows = isPartialQuery ? rawRows : await this.storageRowsToDBMs(rawRows);
         const bms = isPartialQuery ? rows : await this.dbmsToBM(rows, opt);
         return {
             rows: bms,
@@ -148,8 +162,9 @@ export class CommonDao {
     async runQueryExtendedAsDBM(q, opt = {}) {
         this.validateQueryIndexes(q); // throws if query uses `excludeFromIndexes` property
         q.table = opt.table || q.table;
-        const { rows, ...queryResult } = await this.cfg.db.runQuery(q, opt);
+        const { rows: rawRows, ...queryResult } = await this.cfg.db.runQuery(q, opt);
         const isPartialQuery = !!q._selectedFieldNames;
+        const rows = isPartialQuery ? rawRows : await this.storageRowsToDBMs(rawRows);
         const dbms = isPartialQuery ? rows : await this.anyToDBMs(rows, opt);
         return { rows: dbms, ...queryResult };
     }
@@ -159,27 +174,32 @@ export class CommonDao {
         return await this.cfg.db.runQueryCount(q, opt);
     }
     streamQueryAsDBM(q, opt = {}) {
-        const pipeline = this.streamQueryRaw(q, opt);
+        this.validateQueryIndexes(q); // throws if query uses `excludeFromIndexes` property
+        q.table = opt.table || q.table;
+        let pipeline = this.cfg.db.streamQuery(q, opt);
+        if (this.cfg.compress?.keys.length) {
+            pipeline = pipeline.map(async row => await this.storageRowToDBM(row));
+        }
         const isPartialQuery = !!q._selectedFieldNames;
         if (isPartialQuery)
             return pipeline;
         opt.skipValidation ??= true;
         opt.errorMode ||= ErrorMode.SUPPRESS;
-        return pipeline.map(async (dbm) => await this.anyToDBM(dbm, opt), { errorMode: opt.errorMode });
+        return pipeline.map(async dbm => await this.anyToDBM(dbm, opt), { errorMode: opt.errorMode });
     }
     streamQuery(q, opt = {}) {
-        const pipeline = this.streamQueryRaw(q, opt);
+        this.validateQueryIndexes(q); // throws if query uses `excludeFromIndexes` property
+        q.table = opt.table || q.table;
+        let pipeline = this.cfg.db.streamQuery(q, opt);
+        if (this.cfg.compress?.keys.length) {
+            pipeline = pipeline.map(async row => await this.storageRowToDBM(row));
+        }
         const isPartialQuery = !!q._selectedFieldNames;
         if (isPartialQuery)
             return pipeline;
         opt.skipValidation ??= true;
         opt.errorMode ||= ErrorMode.SUPPRESS;
-        return pipeline.map(async (dbm) => await this.dbmToBM(dbm, opt), { errorMode: opt.errorMode });
-    }
-    streamQueryRaw(q, opt = {}) {
-        this.validateQueryIndexes(q); // throws if query uses `excludeFromIndexes` property
-        q.table = opt.table || q.table;
-        return this.cfg.db.streamQuery(q, opt);
+        return pipeline.map(async dbm => await this.dbmToBM(dbm, opt), { errorMode: opt.errorMode });
     }
     async queryIds(q, opt = {}) {
         this.validateQueryIndexes(q); // throws if query uses `excludeFromIndexes` property
@@ -254,7 +274,7 @@ export class CommonDao {
      * Like patchById, but runs all operations within a Transaction.
      */
     async patchByIdInTransaction(id, patch, opt) {
-        return await this.runInTransaction(async (daoTx) => {
+        return await this.runInTransaction(async daoTx => {
             return await this.patchById(id, patch, { ...opt, tx: daoTx.tx });
         });
     }
@@ -306,7 +326,7 @@ export class CommonDao {
      * Like patch, but runs all operations within a Transaction.
      */
     async patchInTransaction(bm, patch, opt) {
-        return await this.runInTransaction(async (daoTx) => {
+        return await this.runInTransaction(async daoTx => {
             return await this.patch(bm, patch, { ...opt, tx: daoTx.tx });
         });
     }
@@ -331,7 +351,8 @@ export class CommonDao {
         this.cfg.hooks.beforeSave?.(dbm);
         const table = opt.table || this.cfg.table;
         const saveOptions = this.prepareSaveOptions(opt);
-        await (opt.tx || this.cfg.db).saveBatch(table, [dbm], saveOptions);
+        const row = await this.dbmToStorageRow(dbm);
+        await (opt.tx || this.cfg.db).saveBatch(table, [row], saveOptions);
         if (saveOptions.assignGeneratedIds) {
             bm.id = dbm.id;
         }
@@ -340,15 +361,16 @@ export class CommonDao {
     async saveAsDBM(dbm, opt = {}) {
         this.requireWriteAccess();
         this.assignIdCreatedUpdated(dbm, opt); // mutates
-        const row = await this.anyToDBM(dbm, opt);
-        this.cfg.hooks.beforeSave?.(row);
+        const validDbm = await this.anyToDBM(dbm, opt);
+        this.cfg.hooks.beforeSave?.(validDbm);
         const table = opt.table || this.cfg.table;
         const saveOptions = this.prepareSaveOptions(opt);
+        const row = await this.dbmToStorageRow(validDbm);
         await (opt.tx || this.cfg.db).saveBatch(table, [row], saveOptions);
         if (saveOptions.assignGeneratedIds) {
-            dbm.id = row.id;
+            dbm.id = validDbm.id;
         }
-        return row;
+        return validDbm;
     }
     async saveBatch(bms, opt = {}) {
         if (!bms.length)
@@ -361,7 +383,8 @@ export class CommonDao {
         }
         const table = opt.table || this.cfg.table;
         const saveOptions = this.prepareSaveOptions(opt);
-        await (opt.tx || this.cfg.db).saveBatch(table, dbms, saveOptions);
+        const rows = await this.dbmsToStorageRows(dbms);
+        await (opt.tx || this.cfg.db).saveBatch(table, rows, saveOptions);
         if (saveOptions.assignGeneratedIds) {
             dbms.forEach((dbm, i) => (bms[i].id = dbm.id));
         }
@@ -372,24 +395,28 @@ export class CommonDao {
             return [];
         this.requireWriteAccess();
         dbms.forEach(dbm => this.assignIdCreatedUpdated(dbm, opt));
-        const rows = await this.anyToDBMs(dbms, opt);
+        const validDbms = await this.anyToDBMs(dbms, opt);
         if (this.cfg.hooks.beforeSave) {
-            rows.forEach(row => this.cfg.hooks.beforeSave(row));
+            validDbms.forEach(dbm => this.cfg.hooks.beforeSave(dbm));
         }
         const table = opt.table || this.cfg.table;
         const saveOptions = this.prepareSaveOptions(opt);
+        const rows = await this.dbmsToStorageRows(validDbms);
         await (opt.tx || this.cfg.db).saveBatch(table, rows, saveOptions);
         if (saveOptions.assignGeneratedIds) {
-            rows.forEach((row, i) => (dbms[i].id = row.id));
+            validDbms.forEach((dbm, i) => (dbms[i].id = dbm.id));
         }
-        return rows;
+        return validDbms;
     }
     prepareSaveOptions(opt) {
         let { saveMethod, assignGeneratedIds = this.cfg.assignGeneratedIds, excludeFromIndexes = this.cfg.excludeFromIndexes, } = opt;
+        // If the user passed in custom `excludeFromIndexes` with the save() call,
+        // and the auto-compression is enabled,
+        // then we need to ensure that the '__compressed' property is part of the list.
         if (this.cfg.compress?.keys) {
             excludeFromIndexes ??= [];
-            if (!excludeFromIndexes.includes('data')) {
-                excludeFromIndexes.push('data');
+            if (!excludeFromIndexes.includes('__compressed')) {
+                excludeFromIndexes.push('__compressed');
             }
         }
         if (this.cfg.immutable && !opt.allowMutability && !opt.saveMethod) {
@@ -397,7 +424,7 @@ export class CommonDao {
         }
         return {
             ...opt,
-            excludeFromIndexes,
+            excludeFromIndexes: excludeFromIndexes,
             saveMethod,
             assignGeneratedIds,
         };
@@ -416,25 +443,19 @@ export class CommonDao {
         const table = opt.table || this.cfg.table;
         opt.skipValidation ??= true;
         opt.errorMode ||= ErrorMode.SUPPRESS;
-        if (this.cfg.immutable && !opt.allowMutability && !opt.saveMethod) {
-            opt = { ...opt, saveMethod: 'insert' };
-        }
-        const excludeFromIndexes = opt.excludeFromIndexes || this.cfg.excludeFromIndexes;
+        const saveOptions = this.prepareSaveOptions(opt);
         const { beforeSave } = this.cfg.hooks;
         const { chunkSize = 500, chunkConcurrency = 32, errorMode } = opt;
         await p
-            .map(async (bm) => {
+            .map(async bm => {
             this.assignIdCreatedUpdated(bm, opt);
             const dbm = await this.bmToDBM(bm, opt);
             beforeSave?.(dbm);
-            return dbm;
+            return await this.dbmToStorageRow(dbm);
         }, { errorMode })
             .chunk(chunkSize)
-            .map(async (batch) => {
-            await this.cfg.db.saveBatch(table, batch, {
-                ...opt,
-                excludeFromIndexes,
-            });
+            .map(async batch => {
+            await this.cfg.db.saveBatch(table, batch, saveOptions);
             return batch;
         }, {
             concurrency: chunkConcurrency,
@@ -480,7 +501,7 @@ export class CommonDao {
                 .streamQuery(q.select(['id']), opt)
                 .mapSync(r => r.id)
                 .chunk(chunkSize)
-                .map(async (ids) => {
+                .map(async ids => {
                 await this.cfg.db.deleteByIds(q.table, ids, opt);
                 deleted += ids.length;
             }, {
@@ -545,15 +566,13 @@ export class CommonDao {
         // optimization: no need to run full joi DBM validation, cause BM validation will be run
         // const dbm = this.anyToDBM(_dbm, opt)
         const dbm = { ..._dbm, ...this.cfg.hooks.parseNaturalId(_dbm.id) };
-        // Decompress
-        await this.decompress(dbm);
         // DBM > BM
         const bm = ((await this.cfg.hooks.beforeDBMToBM?.(dbm)) || dbm);
         // Validate/convert BM
         return this.validateAndConvert(bm, 'load', opt);
     }
     async dbmsToBM(dbms, opt = {}) {
-        return await pMap(dbms, async (dbm) => await this.dbmToBM(dbm, opt));
+        return await pMap(dbms, async dbm => await this.dbmToBM(dbm, opt));
     }
     async bmToDBM(bm, opt) {
         if (bm === undefined)
@@ -562,14 +581,64 @@ export class CommonDao {
         bm = this.validateAndConvert(bm, 'save', opt);
         // BM > DBM
         const dbm = ((await this.cfg.hooks.beforeBMToDBM?.(bm)) || bm);
-        // Compress
-        if (this.cfg.compress)
-            await this.compress(dbm);
         return dbm;
     }
     async bmsToDBM(bms, opt = {}) {
         // try/catch?
-        return await pMap(bms, async (bm) => await this.bmToDBM(bm, opt));
+        return await pMap(bms, async bm => await this.bmToDBM(bm, opt));
+    }
+    // STORAGE LAYER (compression/decompression at DB boundary)
+    // These methods convert between DBM (logical model) and storage format (physical, possibly compressed).
+    // Public methods allow external code to bypass the DAO layer for direct DB access
+    // (e.g., cross-environment data copy).
+    /**
+     * Converts a DBM to storage format, applying compression if configured.
+     *
+     * Use this when you need to write directly to the database, bypassing the DAO save methods.
+     * The returned value is opaque and should only be passed to db.saveBatch() or similar.
+     *
+     * @example
+     * const storageRow = await dao.dbmToStorageRow(dbm)
+     * await db.saveBatch(table, [storageRow])
+     */
+    async dbmToStorageRow(dbm) {
+        if (!this.cfg.compress?.keys.length)
+            return dbm;
+        const row = { ...dbm };
+        await this.compress(row);
+        return row;
+    }
+    /**
+     * Converts multiple DBMs to storage rows.
+     */
+    async dbmsToStorageRows(dbms) {
+        if (!this.cfg.compress?.keys.length)
+            return dbms;
+        return await pMap(dbms, async dbm => await this.dbmToStorageRow(dbm));
+    }
+    /**
+     * Converts a storage row back to a DBM, applying decompression if needed.
+     *
+     * Use this when you need to read directly from the database, bypassing the DAO load methods.
+     *
+     * @example
+     * const rows = await db.getByIds(table, ids)
+     * const dbms = await Promise.all(rows.map(row => dao.storageRowToDBM(row)))
+     */
+    async storageRowToDBM(row) {
+        if (!this.cfg.compress?.keys.length)
+            return row;
+        const dbm = { ...row };
+        await this.decompress(dbm);
+        return dbm;
+    }
+    /**
+     * Converts multiple storage rows to DBMs.
+     */
+    async storageRowsToDBMs(rows) {
+        if (!this.cfg.compress?.keys.length)
+            return rows;
+        return await pMap(rows, async row => await this.storageRowToDBM(row));
     }
     /**
      * Mutates `dbm`.
@@ -579,26 +648,22 @@ export class CommonDao {
             return; // No compression requested
         const { keys } = this.cfg.compress;
         const properties = _pick(dbm, keys);
-        _assert(!('data' in dbm) || 'data' in properties, `Data (${dbm.id}) already has a "data" property. When using compression, this property must be included in the compression keys list.`);
         const bufferString = JSON.stringify(properties);
-        const data = await zstdCompress(bufferString);
+        const __compressed = await zstdCompress(bufferString);
         _omitWithUndefined(dbm, _objectKeys(properties), { mutate: true });
-        Object.assign(dbm, { data });
+        Object.assign(dbm, { __compressed });
     }
     /**
      * Mutates `dbm`.
      */
     async decompress(dbm) {
         _typeCast(dbm);
-        if (!this.cfg.compress)
-            return; // Auto-compression not turned on
-        if (!Buffer.isBuffer(dbm.data))
+        if (!Buffer.isBuffer(dbm.__compressed))
             return; // No compressed data
-        // try-catch to avoid a `data` with Buffer which is not compressed, but legit data
         try {
-            const bufferString = await decompressZstdOrInflateToString(dbm.data);
+            const bufferString = await decompressZstdOrInflateToString(dbm.__compressed);
             const properties = JSON.parse(bufferString);
-            dbm.data = undefined;
+            dbm.__compressed = undefined;
             Object.assign(dbm, properties);
         }
         catch { }
@@ -609,14 +674,12 @@ export class CommonDao {
         // this shouldn't be happening on load! but should on save!
         // this.assignIdCreatedUpdated(dbm, opt)
         dbm = { ...dbm, ...this.cfg.hooks.parseNaturalId(dbm.id) };
-        // Decompress
-        await this.decompress(dbm);
         // Validate/convert DBM
         // return this.validateAndConvert(dbm, this.cfg.dbmSchema, DBModelType.DBM, opt)
         return dbm;
     }
     async anyToDBMs(rows, opt = {}) {
-        return await pMap(rows, async (entity) => await this.anyToDBM(entity, opt));
+        return await pMap(rows, async entity => await this.anyToDBM(entity, opt));
     }
     /**
      * Returns *converted value* (NOT the same reference).
@@ -688,6 +751,73 @@ export class CommonDao {
             opt: opt,
         };
     }
+    /**
+     * Helper to decompress legacy compressed data when migrating away from auto-compression.
+     * Use as your `beforeDBMToBM` hook to decompress legacy rows on read.
+     *
+     * @example
+     * const dao = new CommonDao({
+     *   hooks: {
+     *     beforeDBMToBM: CommonDao.decompressLegacyRow,
+     *   }
+     * })
+     *
+     * // Or within an existing hook:
+     * beforeDBMToBM: async (dbm) => {
+     *   await CommonDao.decompressLegacyRow(dbm)
+     *   // ... other transformations
+     *   return dbm
+     * }
+     */
+    static async decompressLegacyRow(row) {
+        // Check both __compressed (current) and data (legacy) for backward compatibility
+        const compressed = row.__compressed ?? row.data;
+        if (!Buffer.isBuffer(compressed))
+            return row;
+        try {
+            const bufferString = await decompressZstdOrInflateToString(compressed);
+            const properties = JSON.parse(bufferString);
+            row.__compressed = undefined;
+            row.data = undefined;
+            Object.assign(row, properties);
+        }
+        catch {
+            // Decompression failed - field is not compressed, leave as-is
+        }
+        return row;
+    }
+    /**
+     * Temporary helper to migrate from the old `data` compressed property to the new `__compressed` property.
+     * Use as your `beforeDBMToBM` hook during the migration period.
+     *
+     * Migration steps:
+     * 1. Add `beforeDBMToBM: CommonDao.migrateCompressedDataProperty` to your hooks
+     * 2. Deploy - old data (with `data` property) will be decompressed on read and recompressed to `__compressed` on write
+     * 3. Once all data has been naturally rewritten, remove the hook
+     *
+     * @example
+     * const dao = new CommonDao({
+     *   compress: { keys: ['field1', 'field2'] },
+     *   hooks: {
+     *     beforeDBMToBM: CommonDao.migrateCompressedDataProperty,
+     *   }
+     * })
+     */
+    static async migrateCompressedDataProperty(row) {
+        const data = row.data;
+        if (!Buffer.isBuffer(data))
+            return row;
+        try {
+            const bufferString = await decompressZstdOrInflateToString(data);
+            const properties = JSON.parse(bufferString);
+            row.data = undefined;
+            Object.assign(row, properties);
+        }
+        catch {
+            // Decompression failed - data field is not compressed, leave as-is
+        }
+        return row;
+    }
     /**
      * Load rows (by their ids) from Multiple tables at once.
      * An optimized way to load data, minimizing DB round-trips.
@@ -748,14 +878,18 @@ export class CommonDao {
             const { table } = dao.cfg;
             if ('id' in input) {
                 // Singular
-                const dbm = dbmByTableById[table][input.id];
+                const row = dbmByTableById[table][input.id];
+                // Decompress before converting to BM
+                const dbm = row ? await dao.storageRowToDBM(row) : undefined;
                 bmsByProp[prop] = (await dao.dbmToBM(dbm, opt)) || null;
             }
             else {
                 // Plural
                 // We apply filtering, to be able to support multiple input props fetching from the same table.
                 // Without filtering - every prop will get ALL rows from that table.
-                const dbms = input.ids.map(id => dbmByTableById[table][id]).filter(_isTruthy);
+                const rows = input.ids.map(id => dbmByTableById[table][id]).filter(_isTruthy);
+                // Decompress before converting to BM
+                const dbms = await dao.storageRowsToDBMs(rows);
                 bmsByProp[prop] = await dao.dbmsToBM(dbms, opt);
             }
         });
@@ -789,7 +923,7 @@ export class CommonDao {
             return;
         const { db } = inputs[0].dao.cfg;
         const dbmsByTable = {};
-        await pMap(inputs, async (input) => {
+        await pMap(inputs, async input => {
             const { dao } = input;
             const { table } = dao.cfg;
             dbmsByTable[table] ||= [];
@@ -809,7 +943,8 @@ export class CommonDao {
                 dao.assignIdCreatedUpdated(row, opt);
                 const dbm = await dao.bmToDBM(row, opt);
                 dao.cfg.hooks.beforeSave?.(dbm);
-                dbmsByTable[table].push(dbm);
+                const storageRow = await dao.dbmToStorageRow(dbm);
+                dbmsByTable[table].push(storageRow);
             }
             else {
                 // Plural
@@ -818,7 +953,8 @@ export class CommonDao {
                 if (dao.cfg.hooks.beforeSave) {
                     dbms.forEach(dbm => dao.cfg.hooks.beforeSave(dbm));
                 }
-                dbmsByTable[table].push(...dbms);
+                const storageRows = await dao.dbmsToStorageRows(dbms);
+                dbmsByTable[table].push(...storageRows);
             }
         });
         await db.multiSave(dbmsByTable);
@@ -829,7 +965,7 @@ export class CommonDao {
     }
     async runInTransaction(fn, opt) {
         let r;
-        await this.cfg.db.runInTransaction(async (tx) => {
+        await this.cfg.db.runInTransaction(async tx => {
             const daoTx = new CommonDaoTransaction(tx, this.cfg.logger);
             try {
                 r = await fn(daoTx);