@milaboratories/pl-client 2.11.8 → 2.11.9

package/dist/core/transaction.cjs

@@ -0,0 +1,626 @@
+'use strict';
+
+var types = require('./types.cjs');
+var api = require('../proto/github.com/milaboratory/pl/plapi/plapiproto/api.cjs');
+var util = require('../util/util.cjs');
+var type_conversion = require('./type_conversion.cjs');
+var tsHelpers = require('@milaboratories/ts-helpers');
+var errors = require('./errors.cjs');
+var stat = require('./stat.cjs');
+var error_resource = require('./error_resource.cjs');
+var pl = require('../helpers/pl.cjs');
+
+function isField(ref) {
+    return ref.hasOwnProperty('resourceId') && ref.hasOwnProperty('fieldName');
+}
+function isResource(ref) {
+    return (typeof ref === 'bigint' || (ref.hasOwnProperty('globalId') && ref.hasOwnProperty('localId')));
+}
+function isResourceId(ref) {
+    return typeof ref === 'bigint' && !types.isLocalResourceId(ref) && !types.isNullResourceId(ref);
+}
+function isFieldRef(ref) {
+    return isResourceRef(ref.resourceId);
+}
+function isResourceRef(ref) {
+    return ref.hasOwnProperty('globalId') && ref.hasOwnProperty('localId');
+}
+function toFieldId(ref) {
+    if (isFieldRef(ref))
+        return { resourceId: ref.resourceId.localId, fieldName: ref.fieldName };
+    else
+        return ref;
+}
+async function toGlobalFieldId(ref) {
+    if (isFieldRef(ref))
+        return { resourceId: await ref.resourceId.globalId, fieldName: ref.fieldName };
+    else
+        return ref;
+}
+function toResourceId(ref) {
+    if (isResourceRef(ref))
+        return ref.localId;
+    else
+        return ref;
+}
+async function toGlobalResourceId(ref) {
+    if (isResourceRef(ref))
+        return await ref.globalId;
+    else
+        return ref;
+}
+function field(resourceId, fieldName) {
+    return { resourceId, fieldName };
+}
+/** If transaction commit failed due to write conflicts */
+class TxCommitConflict extends Error {
+    name = 'TxCommitConflict';
+}
+async function notFoundToUndefined(cb) {
+    try {
+        return await cb();
+    }
+    catch (e) {
+        if (errors.isNotFoundError(e))
+            return undefined;
+        throw e;
+    }
+}
+/**
+ * Each platform transaction has 3 stages:
+ *   - initialization (txOpen message -> txInfo response)
+ *   - communication (create resources, fields, references and so on)
+ *   - finalization (txCommit or txDiscard message)
+ *
+ * This class encapsulates finalization stage and provides ready-to-communication transaction object.
+ * */
+class PlTransaction {
+    ll;
+    name;
+    writable;
+    _clientRoot;
+    finalPredicate;
+    sharedResourceDataCache;
+    enableFormattedErrors;
+    globalTxId;
+    localTxId = PlTransaction.nextLocalTxId();
+    /** Used in caching */
+    txOpenTimestamp = Date.now();
+    localResourceIdCounter = 0;
+    /** Store logical tx open / closed state to prevent invalid sequence of requests.
+     * True means output stream was completed.
+     * Contract: there must be no async operations between setting this field to true and sending complete signal to stream. */
+    _completed = false;
+    /** Void operation futures are placed into this pool, and corresponding method return immediately.
+     * This is done to save number of round-trips. Next operation producing result will also await those
+     * pending ops, to throw any pending errors. */
+    pendingVoidOps = [];
+    globalTxIdWasAwaited = false;
+    _startTime = Date.now();
+    _stat = stat.initialTxStatWithoutTime();
+    get stat() {
+        return {
+            ...this._stat,
+            timeMs: Date.now() - this._startTime,
+        };
+    }
+    constructor(ll, name, writable, _clientRoot, finalPredicate, sharedResourceDataCache, enableFormattedErrors = false) {
+        this.ll = ll;
+        this.name = name;
+        this.writable = writable;
+        this._clientRoot = _clientRoot;
+        this.finalPredicate = finalPredicate;
+        this.sharedResourceDataCache = sharedResourceDataCache;
+        this.enableFormattedErrors = enableFormattedErrors;
+        // initiating transaction
+        this.globalTxId = this.sendSingleAndParse({
+            oneofKind: 'txOpen',
+            txOpen: {
+                name,
+                enableFormattedErrors,
+                writable: writable
+                    ? api.TxAPI_Open_Request_WritableTx.WRITABLE
+                    : api.TxAPI_Open_Request_WritableTx.NOT_WRITABLE,
+            },
+        }, (r) => tsHelpers.notEmpty(r.txOpen.tx?.id));
+        // To avoid floating promise
+        this.globalTxId.catch((err) => {
+            if (!this.globalTxIdWasAwaited) {
+                console.warn(err);
+            }
+        });
+        // Adding stats
+        this._stat.txCount++;
+    }
+    async drainAndAwaitPendingOps() {
+        if (this.pendingVoidOps.length === 0)
+            return;
+        // drain pending operations into temp array
+        const pending = this.pendingVoidOps;
+        this.pendingVoidOps = [];
+        // awaiting these pending operations first, to catch any errors
+        await Promise.all(pending);
+    }
+    async sendSingleAndParse(r, parser) {
+        // pushing operation packet to server
+        const rawResponsePromise = this.ll.send(r, false);
+        await this.drainAndAwaitPendingOps();
+        // awaiting our result, and parsing the response
+        return parser(await rawResponsePromise);
+    }
+    async sendMultiAndParse(r, parser) {
+        // pushing operation packet to server
+        const rawResponsePromise = this.ll.send(r, true);
+        await this.drainAndAwaitPendingOps();
+        // awaiting our result, and parsing the response
+        return parser(await rawResponsePromise);
+    }
+    async sendVoidSync(r) {
+        await this.ll.send(r, false);
+    }
+    /** Requests sent with this method should never produce recoverable errors */
+    sendVoidAsync(r) {
+        this.pendingVoidOps.push(this.sendVoidSync(r));
+    }
+    checkTxOpen() {
+        if (this._completed)
+            throw new Error('Transaction already closed');
+    }
+    get completed() {
+        return this._completed;
+    }
+    /** Commit & closes transaction. {@link TxCommitConflict} is thrown on
+     * commit conflicts. */
+    async commit() {
+        this.checkTxOpen();
+        // tx will accept no requests after this one
+        this._completed = true;
+        if (!this.writable) {
+            // no need to explicitly commit or reject read-only tx
+            const completeResult = this.ll.complete();
+            await this.drainAndAwaitPendingOps();
+            await completeResult;
+            await this.ll.await();
+        }
+        else {
+            // @TODO, also floating promises
+            const commitResponse = this.sendSingleAndParse({ oneofKind: 'txCommit', txCommit: {} }, (r) => r.txCommit.success);
+            // send closing frame right after commit to save some time on round-trips
+            const completeResult = this.ll.complete();
+            // now when we pushed all packets into the stream, we should wait for any
+            // pending void operations from before, to catch any errors
+            await this.drainAndAwaitPendingOps();
+            if (!(await commitResponse))
+                throw new TxCommitConflict();
+            await completeResult;
+            // await event-loop completion
+            await this.ll.await();
+        }
+    }
+    async discard() {
+        this.checkTxOpen();
+        // tx will accept no requests after this one
+        this._completed = true;
+        const discardResponse = this.sendVoidSync({ oneofKind: 'txDiscard', txDiscard: {} });
+        // send closing frame right after commit to save some time on round-trips
+        const completeResult = this.ll.complete();
+        // now when we pushed all packets into the stream, we should wait for any
+        // pending void operations from before, to catch any errors
+        await this.drainAndAwaitPendingOps();
+        await discardResponse;
+        await completeResult;
+        await this.ll.await();
+    }
+    //
+    // Main tx methods
+    //
+    get clientRoot() {
+        return types.ensureResourceIdNotNull(this._clientRoot);
+    }
+    //
+    // Resources
+    //
+    createSingleton(name, type, errorIfExists = false) {
+        const localId = this.nextLocalResourceId(false);
+        const globalId = this.sendSingleAndParse({
+            oneofKind: 'resourceCreateSingleton',
+            resourceCreateSingleton: {
+                type,
+                id: localId,
+                data: Buffer.from(name),
+                errorIfExists,
+            },
+        }, (r) => r.resourceCreateSingleton.resourceId);
+        return { globalId, localId };
+    }
+    async getSingleton(name, loadFields = true) {
+        return await this.sendSingleAndParse({
+            oneofKind: 'resourceGetSingleton',
+            resourceGetSingleton: {
+                data: Buffer.from(name),
+                loadFields,
+            },
+        }, (r) => type_conversion.protoToResource(tsHelpers.notEmpty(r.resourceGetSingleton.resource)));
+    }
+    createResource(root, req, parser) {
+        const localId = this.nextLocalResourceId(root);
+        const globalId = this.sendSingleAndParse(req(localId), (r) => parser(r));
+        return { globalId, localId };
+    }
+    createRoot(type) {
+        this._stat.rootsCreated++;
+        return this.createResource(true, (localId) => ({ oneofKind: 'resourceCreateRoot', resourceCreateRoot: { type, id: localId } }), (r) => r.resourceCreateRoot.resourceId);
+    }
+    createStruct(type, data) {
+        this._stat.structsCreated++;
+        this._stat.structsCreatedDataBytes += data?.length ?? 0;
+        return this.createResource(false, (localId) => ({
+            oneofKind: 'resourceCreateStruct',
+            resourceCreateStruct: {
+                type,
+                id: localId,
+                data: data === undefined ? undefined : typeof data === 'string' ? Buffer.from(data) : data,
+            },
+        }), (r) => r.resourceCreateStruct.resourceId);
+    }
+    createEphemeral(type, data) {
+        this._stat.ephemeralsCreated++;
+        this._stat.ephemeralsCreatedDataBytes += data?.length ?? 0;
+        return this.createResource(false, (localId) => ({
+            oneofKind: 'resourceCreateEphemeral',
+            resourceCreateEphemeral: {
+                type,
+                id: localId,
+                data: data === undefined ? undefined : typeof data === 'string' ? Buffer.from(data) : data,
+            },
+        }), (r) => r.resourceCreateEphemeral.resourceId);
+    }
+    createValue(type, data, errorIfExists = false) {
+        this._stat.valuesCreated++;
+        this._stat.valuesCreatedDataBytes += data?.length ?? 0;
+        return this.createResource(false, (localId) => ({
+            oneofKind: 'resourceCreateValue',
+            resourceCreateValue: {
+                type,
+                id: localId,
+                data: typeof data === 'string' ? Buffer.from(data) : data,
+                errorIfExists,
+            },
+        }), (r) => r.resourceCreateValue.resourceId);
+    }
+    createJsonValue(data) {
+        const jsonData = tsHelpers.canonicalJsonBytes(data);
+        return this.createValue(pl.JsonObject, jsonData, false);
+    }
+    createJsonGzValue(data, minSizeToGzip = 16_384) {
+        const { data: jsonData, isGzipped } = tsHelpers.canonicalJsonGzBytes(data, minSizeToGzip);
+        return this.createValue(isGzipped ? pl.JsonGzObject : pl.JsonObject, jsonData, false);
+    }
+    createError(message) {
+        return this.createValue(error_resource.ErrorResourceType, JSON.stringify({ message }));
+    }
+    setResourceName(name, rId) {
+        this.sendVoidAsync({
+            oneofKind: 'resourceNameSet',
+            resourceNameSet: { resourceId: toResourceId(rId), name },
+        });
+    }
+    deleteResourceName(name) {
+        this.sendVoidAsync({ oneofKind: 'resourceNameDelete', resourceNameDelete: { name } });
+    }
+    async getResourceByName(name) {
+        return await this.sendSingleAndParse({ oneofKind: 'resourceNameGet', resourceNameGet: { name } }, (r) => types.ensureResourceIdNotNull(r.resourceNameGet.resourceId));
+    }
+    async checkResourceNameExists(name) {
+        return await this.sendSingleAndParse({ oneofKind: 'resourceNameExists', resourceNameExists: { name } }, (r) => r.resourceNameExists.exists);
+    }
+    removeResource(rId) {
+        this.sendVoidAsync({ oneofKind: 'resourceRemove', resourceRemove: { id: rId } });
+    }
+    async resourceExists(rId) {
+        return await this.sendSingleAndParse({ oneofKind: 'resourceExists', resourceExists: { resourceId: rId } }, (r) => r.resourceExists.exists);
+    }
+    async getResourceData(rId, loadFields = true, ignoreCache = false) {
+        if (!ignoreCache && !isResourceRef(rId) && !types.isLocalResourceId(rId)) {
+            // checking if we can return result from cache
+            const fromCache = this.sharedResourceDataCache.get(rId);
+            if (fromCache && fromCache.cacheTxOpenTimestamp < this.txOpenTimestamp) {
+                if (!loadFields) {
+                    this._stat.rGetDataCacheHits++;
+                    this._stat.rGetDataCacheBytes += fromCache.basicData.data?.length ?? 0;
+                    return fromCache.basicData;
+                }
+                else if (fromCache.data) {
+                    this._stat.rGetDataCacheHits++;
+                    this._stat.rGetDataCacheBytes += fromCache.basicData.data?.length ?? 0;
+                    this._stat.rGetDataCacheFields += fromCache.data.fields.length;
+                    return fromCache.data;
+                }
+            }
+        }
+        const result = await this.sendSingleAndParse({
+            oneofKind: 'resourceGet',
+            resourceGet: { resourceId: toResourceId(rId), loadFields: loadFields },
+        }, (r) => type_conversion.protoToResource(tsHelpers.notEmpty(r.resourceGet.resource)));
+        this._stat.rGetDataNetRequests++;
+        this._stat.rGetDataNetBytes += result.data?.length ?? 0;
+        this._stat.rGetDataNetFields += result.fields.length;
+        // we will cache only final resource data states
+        // caching result even if we were ignore the cache
+        if (!isResourceRef(rId) && !types.isLocalResourceId(rId) && this.finalPredicate(result)) {
+            tsHelpers.deepFreeze(result);
+            const fromCache = this.sharedResourceDataCache.get(rId);
+            if (fromCache) {
+                if (loadFields && !fromCache.data) {
+                    fromCache.data = result;
+                    // updating timestamp becuse we updated the record
+                    fromCache.cacheTxOpenTimestamp = this.txOpenTimestamp;
+                }
+            }
+            else {
+                const basicData = types.extractBasicResourceData(result);
+                tsHelpers.deepFreeze(basicData);
+                if (loadFields)
+                    this.sharedResourceDataCache.set(rId, {
+                        basicData,
+                        data: result,
+                        cacheTxOpenTimestamp: this.txOpenTimestamp,
+                    });
+                else
+                    this.sharedResourceDataCache.set(rId, {
+                        basicData,
+                        data: undefined,
+                        cacheTxOpenTimestamp: this.txOpenTimestamp,
+                    });
+            }
+        }
+        return result;
+    }
+    async getResourceDataIfExists(rId, loadFields = true) {
+        // calling this mehtod will ignore cache, because user intention is to detect resource absence
+        // which cache will prevent
+        const result = await notFoundToUndefined(async () => await this.getResourceData(rId, loadFields, true));
+        // cleaning cache record if resorce was removed from the db
+        if (result === undefined && !isResourceRef(rId) && !types.isLocalResourceId(rId))
+            this.sharedResourceDataCache.delete(rId);
+        return result;
+    }
+    /**
+     * Inform platform that resource will not get any new input fields.
+     * This is required, when client creates resource without schema and wants
+     * controller to start calculations.
+     * Most controllers will not start calculations even when all inputs
+     * have their values, if inputs list is not locked.
+     */
+    lockInputs(rId) {
+        this._stat.inputsLocked++;
+        this.sendVoidAsync({
+            oneofKind: 'resourceLockInputs',
+            resourceLockInputs: { resourceId: toResourceId(rId) },
+        });
+    }
+    /**
+     * Inform platform that resource will not get any new output fields.
+     * This is required for resource to pass deduplication.
+     */
+    lockOutputs(rId) {
+        this._stat.outputsLocked++;
+        this.sendVoidAsync({
+            oneofKind: 'resourceLockOutputs',
+            resourceLockOutputs: { resourceId: toResourceId(rId) },
+        });
+    }
+    lock(rID) {
+        this.lockInputs(rID);
+        this.lockOutputs(rID);
+    }
+    setResourceError(rId, ref) {
+        this.sendVoidAsync({
+            oneofKind: 'resourceSetError',
+            resourceSetError: { resourceId: toResourceId(rId), errorResourceId: toResourceId(ref) },
+        });
+    }
+    //
+    // Fields
+    //
+    createField(fId, fieldType, value) {
+        this._stat.fieldsCreated++;
+        this.sendVoidAsync({
+            oneofKind: 'fieldCreate',
+            fieldCreate: { type: type_conversion.fieldTypeToProto(fieldType), id: toFieldId(fId) },
+        });
+        if (value !== undefined)
+            this.setField(fId, value);
+    }
+    async fieldExists(fId) {
+        return await this.sendSingleAndParse({
+            oneofKind: 'fieldExists',
+            fieldExists: { field: toFieldId(fId) },
+        }, (r) => r.fieldExists.exists);
+    }
+    setField(fId, ref) {
+        this._stat.fieldsSet++;
+        if (isResource(ref))
+            this.sendVoidAsync({
+                oneofKind: 'fieldSet',
+                fieldSet: {
+                    field: toFieldId(fId),
+                    value: {
+                        resourceId: toResourceId(ref),
+                        fieldName: '', // default value, read as undefined
+                    },
+                },
+            });
+        else
+            this.sendVoidAsync({
+                oneofKind: 'fieldSet',
+                fieldSet: {
+                    field: toFieldId(fId),
+                    value: toFieldId(ref),
+                },
+            });
+    }
+    setFieldError(fId, ref) {
+        this._stat.fieldsSet++;
+        this.sendVoidAsync({
+            oneofKind: 'fieldSetError',
+            fieldSetError: { field: toFieldId(fId), errResourceId: toResourceId(ref) },
+        });
+    }
+    async getField(fId) {
+        this._stat.fieldsGet++;
+        return await this.sendSingleAndParse({ oneofKind: 'fieldGet', fieldGet: { field: toFieldId(fId) } }, (r) => type_conversion.protoToField(tsHelpers.notEmpty(r.fieldGet.field)));
+    }
+    async getFieldIfExists(fId) {
+        return notFoundToUndefined(async () => await this.getField(fId));
+    }
+    resetField(fId) {
+        this.sendVoidAsync({ oneofKind: 'fieldReset', fieldReset: { field: toFieldId(fId) } });
+    }
+    removeField(fId) {
+        this.sendVoidAsync({ oneofKind: 'fieldRemove', fieldRemove: { field: toFieldId(fId) } });
+    }
+    //
+    // KV
+    //
+    async listKeyValues(rId) {
+        const result = await this.sendMultiAndParse({
+            oneofKind: 'resourceKeyValueList',
+            resourceKeyValueList: { resourceId: toResourceId(rId), startFrom: '', limit: 0 },
+        }, (r) => r.map((e) => e.resourceKeyValueList.record));
+        this._stat.kvListRequests++;
+        this._stat.kvListEntries += result.length;
+        for (const kv of result)
+            this._stat.kvListBytes += kv.key.length + kv.value.length;
+        return result;
+    }
+    async listKeyValuesString(rId) {
+        return (await this.listKeyValues(rId)).map(({ key, value }) => ({
+            key,
+            value: Buffer.from(value).toString(),
+        }));
+    }
+    async listKeyValuesIfResourceExists(rId) {
+        return notFoundToUndefined(async () => await this.listKeyValues(rId));
+    }
+    async listKeyValuesStringIfResourceExists(rId) {
+        return notFoundToUndefined(async () => await this.listKeyValuesString(rId));
+    }
+    setKValue(rId, key, value) {
+        this._stat.kvSetRequests++;
+        this._stat.kvSetBytes++;
+        this.sendVoidAsync({
+            oneofKind: 'resourceKeyValueSet',
+            resourceKeyValueSet: {
+                resourceId: toResourceId(rId),
+                key,
+                value: util.toBytes(value),
+            },
+        });
+    }
+    deleteKValue(rId, key) {
+        this.sendVoidAsync({
+            oneofKind: 'resourceKeyValueDelete',
+            resourceKeyValueDelete: {
+                resourceId: toResourceId(rId),
+                key,
+            },
+        });
+    }
+    async getKValue(rId, key) {
+        const result = await this.sendSingleAndParse({
+            oneofKind: 'resourceKeyValueGet',
+            resourceKeyValueGet: { resourceId: toResourceId(rId), key },
+        }, (r) => r.resourceKeyValueGet.value);
+        this._stat.kvGetRequests++;
+        this._stat.kvGetBytes += result.length;
+        return result;
+    }
+    async getKValueString(rId, key) {
+        return Buffer.from(await this.getKValue(rId, key)).toString();
+    }
+    async getKValueJson(rId, key) {
+        return JSON.parse(await this.getKValueString(rId, key));
+    }
+    async getKValueIfExists(rId, key) {
+        const result = await this.sendSingleAndParse({
+            oneofKind: 'resourceKeyValueGetIfExists',
+            resourceKeyValueGetIfExists: { resourceId: toResourceId(rId), key },
+        }, (r) => r.resourceKeyValueGetIfExists.exists ? r.resourceKeyValueGetIfExists.value : undefined);
+        this._stat.kvGetRequests++;
+        this._stat.kvGetBytes += result?.length ?? 0;
+        return result;
+    }
+    async getKValueStringIfExists(rId, key) {
+        const data = await this.getKValueIfExists(rId, key);
+        return data === undefined ? undefined : Buffer.from(data).toString();
+    }
+    async getKValueJsonIfExists(rId, key) {
+        const str = await this.getKValueString(rId, key);
+        if (str === undefined)
+            return undefined;
+        return JSON.parse(str);
+    }
+    //
+    // Cache
+    //
+    // TODO
+    //
+    // High level ops
+    //
+    /** Resolves existing or create first level resource from */
+    getFutureFieldValue(rId, fieldName, fieldType) {
+        const data = Buffer.from(JSON.stringify({ fieldName, fieldType }));
+        const getFieldResource = this.createEphemeral({ name: 'json/getField', version: '1' }, data);
+        this.setField({ resourceId: getFieldResource, fieldName: 'resource' }, rId);
+        return { resourceId: getFieldResource, fieldName: 'result' };
+    }
+    //
+    // Technical
+    //
+    async getGlobalTxId() {
+        this.globalTxIdWasAwaited = true;
+        return await this.globalTxId;
+    }
+    /** Closes output event stream */
+    async complete() {
+        if (this._completed)
+            return;
+        this._completed = true;
+        const completeResult = this.ll.complete();
+        await this.drainAndAwaitPendingOps();
+        await completeResult;
+    }
+    /** Await incoming message loop termination and throw
+     * any leftover errors if it was unsuccessful */
+    async await() {
+        await this.ll.await();
+    }
+    //
+    // Helpers
+    //
+    nextLocalResourceId(root) {
+        return types.createLocalResourceId(root, ++this.localResourceIdCounter, this.localTxId);
+    }
+    static localTxIdCounter = 0;
+    static nextLocalTxId() {
+        PlTransaction.localTxIdCounter++;
+        if (PlTransaction.localTxIdCounter === types.MaxTxId)
+            PlTransaction.localTxIdCounter = 1;
+        return PlTransaction.localTxIdCounter;
+    }
+}
+
+exports.PlTransaction = PlTransaction;
+exports.TxCommitConflict = TxCommitConflict;
+exports.field = field;
+exports.isField = isField;
+exports.isFieldRef = isFieldRef;
+exports.isResource = isResource;
+exports.isResourceId = isResourceId;
+exports.isResourceRef = isResourceRef;
+exports.toFieldId = toFieldId;
+exports.toGlobalFieldId = toGlobalFieldId;
+exports.toGlobalResourceId = toGlobalResourceId;
+exports.toResourceId = toResourceId;
+//# sourceMappingURL=transaction.cjs.map