nesoi 3.3.17 → 3.3.19

package/lib/elements/entities/bucket/adapters/browserdb.service.js

@@ -68,8 +68,9 @@ class BrowserDBService extends service_1.Service {
         return async (trx, fn, services) => {
             const module = trx.engine.getModule();
             const db = await BrowserDBService.db(services[service], module);
-            const refNames = Object.keys(module.buckets)
-                .map(key => key.includes('::')
+            const refNames = Object.entries(module.buckets)
+                .filter(([_, val]) => val.adapter instanceof browserdb_bucket_adapter_1.BrowserDBBucketAdapter)
+                .map(([key]) => key.includes('::')
                 ? key
                 : `${module.name}::${key}`);
             const trxData = {};

package/lib/elements/entities/bucket/adapters/bucket_adapter.d.ts

@@ -17,11 +17,11 @@ export type BucketAdapterConfig = {
  * @category Adapters
  * @subcategory Entity
  * */
-export declare abstract class BucketAdapter<Obj extends NesoiObj> {
+export declare abstract class BucketAdapter<Obj extends NesoiObj, Config extends BucketAdapterConfig = BucketAdapterConfig> {
     protected schema: $Bucket;
     nql: NQLRunner;
-    config: BucketAdapterConfig;
-    constructor(schema: $Bucket, nql: NQLRunner, config?: Partial<BucketAdapterConfig>);
+    config: Config;
+    constructor(schema: $Bucket, nql: NQLRunner, config?: Partial<Config>);
     /**
      * **DANGEROUS!**
      * This should only be used on inner adapters of bucket caches.
@@ -158,4 +158,4 @@ export declare abstract class BucketAdapter<Obj extends NesoiObj> {
      */
     getUpdateEpoch(obj: Obj): number;
 }
-export type AnyBucketAdapter = BucketAdapter<any>;
+export type AnyBucketAdapter = BucketAdapter<any, any>;

package/lib/elements/entities/bucket/adapters/bucket_adapter.js

@@ -16,6 +16,7 @@ class BucketAdapter {
         this.schema = schema;
         this.nql = nql;
         this.config = {
+            ...config,
             meta: {
                 created_at: config?.meta?.created_at || 'created_at',
                 created_by: config?.meta?.created_by || 'created_by',

package/lib/elements/entities/bucket/adapters/memory.nql.js

@@ -33,10 +33,23 @@ class MemoryNQLRunner extends nql_engine_1.NQLRunner {
         if (part.union.sort?.length) {
             const sort = part.union.sort;
             output.sort((a, b) => {
+                let fallback = 0;
                 for (let i = 0; i < sort.length; i++) {
                     const s = sort[i];
                     const a_val = tree_1.Tree.get(a, s.key);
                     const b_val = tree_1.Tree.get(b, s.key);
+                    if (a_val == null) {
+                        if (b_val == null)
+                            return 0;
+                        fallback = -1;
+                        continue;
+                    }
+                    else if (b_val == null) {
+                        if (a_val == null)
+                            return 0;
+                        fallback = 1;
+                        continue;
+                    }
                     if (a_val instanceof datetime_1.NesoiDatetime) {
                         let d = 0;
                         if (b_val instanceof datetime_1.NesoiDatetime)
@@ -90,7 +103,7 @@ class MemoryNQLRunner extends nql_engine_1.NQLRunner {
                         }
                     }
                 }
-                return 0;
+                return fallback;
             });
         }
         let totalItems = undefined;

package/lib/elements/entities/bucket/adapters/rest.bucket_adapter.d.ts

@@ -0,0 +1,46 @@
+import { BucketAdapter, BucketAdapterConfig } from './bucket_adapter';
+import { ObjWithOptionalId } from "../../../../engine/data/obj";
+import { AnyTrxNode } from "../../../../engine/transaction/trx_node";
+import { $Bucket } from "../../..";
+import { BucketCacheSync } from '../cache/bucket_cache';
+export type RESTBucketAdapterConfig = {
+    base_url: string;
+    auth?: string;
+};
+/**
+ * @category Adapters
+ * @subcategory Entity
+ * */
+export declare class RESTBucketAdapter<B extends $Bucket, Obj extends B['#data']> extends BucketAdapter<Obj, RESTBucketAdapterConfig & BucketAdapterConfig> {
+    schema: B;
+    constructor(schema: B, config?: RESTBucketAdapterConfig);
+    getQueryMeta(): {
+        scope: string;
+        avgTime: number;
+    };
+    fetch(trx: AnyTrxNode, url: string, options?: RequestInit): Promise<{
+        data: Obj | Obj[];
+    }>;
+    protected deleteEverything(trx: AnyTrxNode): Promise<void>;
+    index(trx: AnyTrxNode): Promise<Obj[]>;
+    get(trx: AnyTrxNode, id: Obj['id']): Promise<Obj | undefined>;
+    create(trx: AnyTrxNode, obj: ObjWithOptionalId<Obj>): Promise<Obj>;
+    createMany(trx: AnyTrxNode, objs: ObjWithOptionalId<Obj>[]): Promise<Obj[]>;
+    replace(trx: AnyTrxNode, obj: ObjWithOptionalId<Obj>): Promise<Obj>;
+    replaceMany(trx: AnyTrxNode, objs: ObjWithOptionalId<Obj>[]): Promise<Obj[]>;
+    patch(trx: AnyTrxNode, obj: ObjWithOptionalId<Obj>): Promise<Obj>;
+    patchMany(trx: AnyTrxNode, objs: ObjWithOptionalId<Obj>[]): Promise<Obj[]>;
+    put(trx: AnyTrxNode, obj: ObjWithOptionalId<Obj>): Promise<Obj>;
+    putMany(trx: AnyTrxNode, objs: ObjWithOptionalId<Obj>[]): Promise<Obj[]>;
+    delete(trx: AnyTrxNode, id: Obj['id']): Promise<void>;
+    deleteMany(trx: AnyTrxNode, ids: Obj['id'][]): Promise<void>;
+    syncOne(trx: AnyTrxNode, id: Obj['id'], lastObjUpdateEpoch: number): Promise<null | 'deleted' | BucketCacheSync<Obj>>;
+    syncOneAndPast(trx: AnyTrxNode, id: Obj['id'], lastUpdateEpoch: number): Promise<null | 'deleted' | BucketCacheSync<Obj>[]>;
+    syncAll(trx: AnyTrxNode, lastHash?: string, lastUpdateEpoch?: number): Promise<null | {
+        sync: BucketCacheSync<Obj>[];
+        hash: string;
+        updateEpoch: number;
+        reset: boolean;
+    }>;
+}
+export type AnyRESTBucketAdapter = RESTBucketAdapter<any, any>;

package/lib/elements/entities/bucket/adapters/rest.bucket_adapter.js

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESTBucketAdapter = void 0;
+const bucket_adapter_1 = require("./bucket_adapter");
+const rest_nql_1 = require("./rest.nql");
+const log_1 = require("../../../../engine/util/log");
+/**
+ * @category Adapters
+ * @subcategory Entity
+ * */
+class RESTBucketAdapter extends bucket_adapter_1.BucketAdapter {
+    schema;
+    constructor(schema, config) {
+        const nql = new rest_nql_1.RESTNQLRunner();
+        super(schema, nql, config);
+        this.schema = schema;
+        nql.bind(this);
+    }
+    getQueryMeta() {
+        return {
+            scope: `rest.${this.schema.name}`,
+            avgTime: 10
+        };
+    }
+    /*
+        Fetch
+    */
+    async fetch(trx, url, options) {
+        const token = this.config.auth
+            ? await trx.token(this.config.auth)
+            : undefined;
+        const input = this.config.base_url + url;
+        return fetch(input, {
+            ...options,
+            headers: {
+                ...options?.headers,
+                Authorization: token ? `Bearer ${token}` : undefined,
+            }
+        })
+            .then(async (response) => ({
+            status: response.status,
+            headers: response.headers,
+            body: await response.json().catch(() => null)
+        }))
+            .then((response) => {
+            // if (response.status === 401) {
+            //     // ...
+            // }
+            return response.body;
+        })
+            .catch((e) => {
+            log_1.Log.error('rest', '', e, e);
+            // ...
+            throw e;
+        });
+    }
+    /* Dangerous, used on cache only */
+    async deleteEverything(trx) {
+        throw new Error('Not implemented');
+    }
+    /* Read operations */
+    async index(trx) {
+        const res = await this.fetch(trx, '/', {
+            method: 'GET'
+        });
+        return res.data;
+    }
+    async get(trx, id) {
+        const res = await this.fetch(trx, '/' + id, {
+            method: 'GET'
+        });
+        return res.data;
+    }
+    /* Write Operations */
+    async create(trx, obj) {
+        const res = await this.fetch(trx, '/', {
+            method: 'POST',
+            body: JSON.stringify(obj)
+        });
+        return res.data;
+    }
+    async createMany(trx, objs) {
+        const out = [];
+        for (const obj of objs) {
+            out.push(await this.create(trx, obj));
+        }
+        return out;
+    }
+    async replace(trx, obj) {
+        if (!obj.id) {
+            throw new Error(`Object with id ${obj.id} not found for replace`);
+        }
+        const host_obj = await this.get(trx, obj.id);
+        if (!host_obj) {
+            throw new Error(`Object with id ${obj.id} not found for replace`);
+        }
+        const res = await this.fetch(trx, '/' + obj.id, {
+            method: 'PUT',
+            body: JSON.stringify(obj)
+        });
+        return res.data;
+    }
+    async replaceMany(trx, objs) {
+        const out = [];
+        for (const obj of objs) {
+            const output = await this.replace(trx, obj);
+            out.push(output);
+        }
+        return Promise.resolve(out);
+    }
+    async patch(trx, obj) {
+        const res = await this.fetch(trx, '/' + obj.id, {
+            method: 'PATCH',
+            body: JSON.stringify(obj)
+        });
+        return res.data;
+    }
+    async patchMany(trx, objs) {
+        const out = [];
+        for (const obj of objs) {
+            const output = await this.patch(trx, obj);
+            out.push(output);
+        }
+        return Promise.resolve(out);
+    }
+    async put(trx, obj) {
+        const res = await this.fetch(trx, '/' + obj.id, {
+            method: 'PUT',
+            body: JSON.stringify(obj)
+        });
+        return res.data;
+    }
+    async putMany(trx, objs) {
+        const out = [];
+        for (const obj of objs) {
+            const output = await this.put(trx, obj);
+            out.push(output);
+        }
+        return Promise.resolve(out);
+    }
+    async delete(trx, id) {
+        await this.fetch(trx, '/' + id, {
+            method: 'DELETE'
+        });
+    }
+    async deleteMany(trx, ids) {
+        for (const id of ids) {
+            await this.delete(trx, id);
+        }
+    }
+    /* Cache Operations */
+    async syncOne(trx, id, lastObjUpdateEpoch) {
+        // TODO
+        return null;
+        // // 1. Check if object was deleted
+        // const obj = await this.get(trx, id);
+        // if (!obj) {
+        //     return 'deleted' as const;
+        // }
+        // // 2. Check if object was updated
+        // const updateEpoch = this.getUpdateEpoch(obj);
+        // const hasObjUpdated = updateEpoch > lastObjUpdateEpoch;
+        // if (!hasObjUpdated) {
+        //     return null;
+        // }
+        // // 3. Return updated object and epoch
+        // return {
+        //     obj,
+        //     updateEpoch
+        // };
+    }
+    async syncOneAndPast(trx, id, lastUpdateEpoch) {
+        // TODO
+        return null;
+        // // 1. Check if object was deleted
+        // const obj = await this.get(trx, id);
+        // if (!obj) {
+        //     return 'deleted' as const;
+        // }
+        // // 2. Check if object was updated
+        // const objUpdateEpoch = this.getUpdateEpoch(obj);
+        // const hasObjUpdated = objUpdateEpoch > lastUpdateEpoch;       
+        // if (!hasObjUpdated) {
+        //     return null;
+        // }
+        // // 3. Return all objects updated and the max epoch
+        // let updateEpoch = 0;
+        // const changed = (Object.values(this.data) as Obj[])
+        //     .map(obj => {
+        //         const epoch = this.getUpdateEpoch(obj);
+        //         if (epoch > updateEpoch) {
+        //             updateEpoch = epoch;
+        //         }
+        //         return { obj, updateEpoch: epoch };
+        //     })
+        //     .filter(obj => obj.updateEpoch > lastUpdateEpoch);
+        // if (!changed.length) {
+        //     return null;
+        // }
+        // return changed;
+    }
+    async syncAll(trx, lastHash, lastUpdateEpoch = 0) {
+        // TODO
+        return null;
+        // // 1. Hash the current ids
+        // const idStr = Object.keys(this.data).sort().join('');
+        // const hash = Hash.string(idStr);
+        // // 2. If hash changed, return a reset sync with all objects
+        // if (hash !== lastHash) {
+        //     let updateEpoch = 0;
+        //     const sync = (Object.values(this.data) as Obj[])
+        //         .map(obj => {
+        //             const epoch = this.getUpdateEpoch(obj);
+        //             if (epoch > updateEpoch) {
+        //                 updateEpoch = epoch;
+        //             }
+        //             return { obj, updateEpoch: epoch };
+        //         });
+        //     return {
+        //         sync,
+        //         hash,
+        //         updateEpoch,
+        //         reset: true
+        //     };
+        // }
+        // // 3. Find the data that changed and return it
+        // let updateEpoch = 0;
+        // const sync = (Object.values(this.data) as Obj[])
+        //     .map(obj => {
+        //         const epoch = this.getUpdateEpoch(obj);
+        //         if (epoch > updateEpoch) {
+        //             updateEpoch = epoch;
+        //         }
+        //         return { obj, updateEpoch: epoch };
+        //     })
+        //     .filter(obj => obj.updateEpoch > lastUpdateEpoch);
+        // if (!sync.length) {
+        //     return null;
+        // }
+        // return {
+        //     sync,
+        //     hash,
+        //     updateEpoch,
+        //     reset: false
+        // };
+    }
+}
+exports.RESTBucketAdapter = RESTBucketAdapter;

package/lib/elements/entities/bucket/adapters/rest.nql.d.ts

@@ -0,0 +1,15 @@
+import { NQL_Result, NQLRunner } from '../query/nql_engine';
+import { AnyTrxNode } from "../../../../engine/transaction/trx_node";
+import { NQL_Pagination, NQL_Part } from '../query/nql.schema';
+import { AnyRESTBucketAdapter } from './rest.bucket_adapter';
+type Obj = Record<string, any>;
+/**
+ * @category NQL
+ * */
+export declare class RESTNQLRunner extends NQLRunner {
+    protected adapter?: AnyRESTBucketAdapter;
+    constructor();
+    bind(adapter: AnyRESTBucketAdapter): void;
+    run(trx: AnyTrxNode, part: NQL_Part, params: Obj[], param_templates: Record<string, string>[], pagination?: NQL_Pagination): Promise<NQL_Result>;
+}
+export {};

package/lib/elements/entities/bucket/adapters/rest.nql.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESTNQLRunner = void 0;
+const nql_engine_1 = require("../query/nql_engine");
+const nql_compiler_1 = require("../query/nql_compiler");
+/**
+ * @category NQL
+ * */
+class RESTNQLRunner extends nql_engine_1.NQLRunner {
+    adapter;
+    constructor() {
+        super();
+    }
+    bind(adapter) {
+        this.adapter = adapter;
+    }
+    async run(trx, part, params, param_templates, pagination) {
+        if (!this.adapter) {
+            throw new Error('No adapter bound to NQL Runner');
+        }
+        const query = nql_compiler_1.NQL_Decompiler.decompile(part, params, param_templates);
+        const res = await this.adapter.fetch(trx, '/query', {
+            method: 'POST',
+            body: JSON.stringify({
+                query,
+                page: pagination?.page,
+                perPage: pagination?.perPage,
+            })
+        });
+        return res.data;
+    }
+}
+exports.RESTNQLRunner = RESTNQLRunner;

package/lib/elements/entities/bucket/bucket.config.d.ts

@@ -18,16 +18,16 @@ export type BucketConfig<M extends $Module, B extends $Bucket, Services extends
              * - **past**: Update/delete the object and update all objects modified before it, then return
              * - **all**: Update/reset the cache, then return
             */
-            get?: 'one' | 'past' | 'all';
+            get?: 'eager' | 'one' | 'past' | 'all';
             /** Cache mode for `index`:
              * - **all**: Update/reset the cache, then return
             */
-            index?: 'all';
+            index?: 'eager' | 'all';
             /** Cache mode for `query`:
              * - **incremental**: Query ids only, then query data for modified entries only, save them and return
              * - **all**: Update/reset the cache, then query the inner adapter and return
             */
-            query?: 'incremental' | 'all';
+            query?: 'eager' | 'incremental' | 'all';
         };
     };
 };

package/lib/elements/entities/bucket/bucket.js

@@ -13,6 +13,7 @@ const tree_1 = require("../../../engine/data/tree");
 const crypto_1 = require("../../../engine/util/crypto");
 const bucket_model_schema_1 = require("./model/bucket_model.schema");
 const trash_1 = require("../../../engine/data/trash");
+const trx_1 = require("../../../engine/transaction/trx");
 /**
  * **This should only be used inside a `#composition` of a bucket `create`** to refer to the parent id, which doesn't exist yet.
  *
@@ -88,7 +89,7 @@ class Bucket {
             : this.getTenancyQuery(trx);
         let raw;
         // With Tenancy
-        const adapter = this.cache || this.adapter;
+        const adapter = await trx_1.Trx.getCache(trx, this) || this.cache || this.adapter;
         if (tenancy) {
             const result = await adapter.query(trx, {
                 id,
@@ -127,9 +128,9 @@ class Bucket {
             : this.getTenancyQuery(trx);
         let raws;
         // With Tenancy
-        const adapter = this.cache || this.adapter;
+        const adapter = await trx_1.Trx.getCache(trx, this) || this.cache || this.adapter;
         if (tenancy) {
-            const result = await adapter.query(trx, tenancy, undefined, options?.query_view ? [{ view: options?.query_view }] : undefined);
+            const result = await adapter.query(trx, tenancy, undefined, undefined, undefined, options?.query_view ? { view: options?.query_view } : undefined);
             raws = result.data;
         }
         // Without Tenancy
@@ -432,7 +433,7 @@ class Bucket {
         // Read old object, if safe, to check if it exists
         let oldObj;
         if (!options?.unsafe) {
-            const adapter = this.cache || this.adapter;
+            const adapter = await trx_1.Trx.getCache(trx, this) || this.cache || this.adapter;
             // With Tenancy
             if (tenancy) {
                 const result = await adapter.query(trx, {
@@ -620,7 +621,7 @@ class Bucket {
                 await trx.bucket(link.bucket.short).unsafe.deleteMany(linked.map((l) => l.id));
             }
             else {
-                await trx.bucket(link.bucket.short).delete(linked.id);
+                await trx.bucket(link.bucket.short).unsafe.delete(linked.id);
             }
         }
         // Delete the object itself
@@ -727,7 +728,7 @@ class Bucket {
                 pagination.perPage = undefined;
         }
         // Query
-        const adapter = this.cache || this.adapter;
+        const adapter = await trx_1.Trx.getCache(trx, this) || this.cache || this.adapter;
         const result = await adapter.query(trx, query, pagination, options?.params, options?.param_templates);
         if (!result.data.length)
             return result;

package/lib/elements/entities/bucket/cache/bucket_cache.d.ts

@@ -32,17 +32,50 @@ export declare class BucketCache<Obj extends NesoiObj> {
     private outerAdapter;
     constructor(bucket: AnyBucket, config: NonNullable<BucketConfig<any, any, any>['cache']>);
     get(trx: AnyTrxNode, id: NesoiObj['id']): Promise<any>;
-    index(trx: AnyTrxNode): Promise<any[]>;
-    query<MetadataOnly extends boolean>(trx: AnyTrxNode, query: NQL_AnyQuery, pagination?: NQL_Pagination, params?: Record<string, any>[], config?: {
+    index(trx: AnyTrxNode): Promise<{
+        id: Obj["id"];
+    }[]>;
+    query<MetadataOnly extends boolean>(trx: AnyTrxNode, query: NQL_AnyQuery, pagination?: NQL_Pagination, params?: Record<string, any>[], param_templates?: Record<string, string>[], config?: {
         view?: string;
         metadataOnly?: MetadataOnly;
     }): Promise<NQL_Result<MetadataOnly extends true ? {
         id: Obj['id'];
         [x: string]: any;
     } : Obj>>;
+    /**
+     * Update inner adapter with data from outer adapter.
+     */
+    sync(trx: AnyTrxNode): Promise<void>;
+    /**
+     * If doesnt exist on inner adapter, read.
+     * If it exists, check if it's updated (query metadata).
+     *
+     * [get.one]
+     * - reduces transit payload for data that doesn't change much
+     */
     private syncOne;
+    /**
+     * If doesnt exist on inner adapter, read.
+     * If it exists, read past.
+     *
+     * [get.past]
+     * - reduces transit payload for data that changes a little
+     */
     private syncOneAndPast;
+    /**
+     * Compare ids hash with outer. If it matches, read updated data.
+     * If not, hard resync.
+     *
+     * [get.all, index.all, query.all]
+     * - reduces transit payload for data that's not often deleted
+     */
     private syncAll;
+    /**
+     * Query metadata from outer, then query data from outer - only newer than inner data.
+     *
+     * [query.incremental]
+     * - reduces transit payload for data that doesn't change much
+     */
     private syncQuery;
 }
 export type AnyBucketCache = BucketCache<any>;

package/lib/elements/entities/bucket/cache/bucket_cache.js

@@ -47,6 +47,14 @@ class BucketCache {
     }
     async get(trx, id) {
         const mode = this.config?.mode?.get;
+        if (mode === 'eager') {
+            log_1.Log.debug('bucket', this.bucket.schema.name, `CACHE get.eager, ${id}`);
+            const sync = await this.innerAdapter.get(trx, id);
+            if (!sync)
+                return undefined;
+            const { __update_epoch, __sync_epoch, ...obj } = sync;
+            return obj;
+        }
         if (mode === 'one') {
             const { action, sync } = await this.syncOne(trx, id);
             log_1.Log.debug('bucket', this.bucket.schema.name, `CACHE get.one, ${action}`);
@@ -76,21 +84,33 @@ class BucketCache {
     }
     async index(trx) {
         const mode = this.config?.mode?.index;
-        if (mode === 'all') {
+        let data;
+        if (mode === 'eager') {
+            log_1.Log.debug('bucket', this.bucket.schema.name, 'CACHE index.eager');
+            data = await this.innerAdapter.index(trx);
+        }
+        else if (mode === 'all') {
             const { action, sync } = await this.syncAll(trx);
             log_1.Log.debug('bucket', this.bucket.schema.name, `CACHE index.all, ${action}`);
-            const data = [];
-            for (const e of sync) {
-                const { __update_epoch, __sync_epoch, ...obj } = e;
-                data.push(obj);
-            }
-            return data;
+            data = sync;
+        }
+        else {
+            throw new Error(`Invalid index cache mode '${mode}'`);
         }
-        return this.outerAdapter.index(trx);
+        const out = [];
+        for (const e of data) {
+            const { __update_epoch, __sync_epoch, ...obj } = e;
+            out.push(obj);
+        }
+        return out;
     }
-    async query(trx, query, pagination, params, config) {
+    async query(trx, query, pagination, params, param_templates, config) {
         const mode = this.config?.mode?.query;
         let data;
+        if (mode === 'eager') {
+            log_1.Log.debug('bucket', this.bucket.schema.name, 'CACHE index.eager');
+            data = await this.innerAdapter.query(trx, query, pagination, params, param_templates, config);
+        }
         if (mode === 'incremental') {
             const { action, sync } = await this.syncQuery(trx, query, pagination, params);
             log_1.Log.debug('bucket', this.bucket.schema.name, `CACHE query.incremental, ${action}`);
@@ -125,6 +145,22 @@ class BucketCache {
         return { data };
     }
     /* Cache modes */
+    /**
+     * Update inner adapter with data from outer adapter.
+     */
+    async sync(trx) {
+        const objects = await this.outerAdapter.index(trx);
+        const entries = objects.map(obj => new BucketCacheEntry(obj, this.outerAdapter.getUpdateEpoch(obj), this.lastSyncEpoch));
+        await this.innerAdapter.deleteEverything(trx);
+        await this.innerAdapter.putMany(trx, entries);
+    }
+    /**
+     * If doesnt exist on inner adapter, read.
+     * If it exists, check if it's updated (query metadata).
+     *
+     * [get.one]
+     * - reduces transit payload for data that doesn't change much
+     */
     async syncOne(trx, id) {
         let localObj = await this.innerAdapter.get(trx, id);
         if (!localObj) {
@@ -148,6 +184,13 @@ class BucketCache {
         await this.innerAdapter.put(trx, localObj);
         return { action: 'update', sync: localObj };
     }
+    /**
+     * If doesnt exist on inner adapter, read.
+     * If it exists, read past.
+     *
+     * [get.past]
+     * - reduces transit payload for data that changes a little
+     */
     async syncOneAndPast(trx, id) {
         const localObj = await this.innerAdapter.get(trx, id);
         if (!localObj) {
@@ -170,6 +213,13 @@ class BucketCache {
         await this.innerAdapter.putMany(trx, entries);
         return { action: 'update', sync: entries.find(e => e.id === id) };
     }
+    /**
+     * Compare ids hash with outer. If it matches, read updated data.
+     * If not, hard resync.
+     *
+     * [get.all, index.all, query.all]
+     * - reduces transit payload for data that's not often deleted
+     */
     async syncAll(trx) {
         const sync = await this.outerAdapter.syncAll(trx, this.lastHash, this.lastUpdateEpoch);
         if (sync === null) {
@@ -188,6 +238,12 @@ class BucketCache {
         await this.innerAdapter.putMany(trx, entries);
         return { action: 'update', sync: entries };
     }
+    /**
+     * Query metadata from outer, then query data from outer - only newer than inner data.
+     *
+     * [query.incremental]
+     * - reduces transit payload for data that doesn't change much
+     */
     async syncQuery(trx, query, pagination, params) {
         // 1. Query id and epoch from outer adapter
         const outerMetadata = await this.outerAdapter.query(trx, query, pagination, params, undefined, {