@platforma-sdk/model 1.2.22

package/src/config/model.ts

@@ -0,0 +1,197 @@
+export type Cfg =
+  | CfgGetFromCtx
+  | CfgIsolate
+  | CfgImmediate
+  | CfgMakeObject
+  | CfgMakeArray
+  | CfgGetJsonField
+  | CfgMapRecordValues
+  | CfgMapArrayValues
+  | CfgFlatten
+  | CfgIsEmpty
+  | CfgNot
+  | CfgAnd
+  | CfgOr
+  | CfgMapResourceFields
+  | CfgGetResourceField
+  | CfgResourceValueAsJson
+  | CfgBlobContent
+  | CfgBlobContentAsString
+  | CfgBlobContentAsJson
+  | CfgDownloadedBlobContent
+  | CfgOnDemandBlobContent
+  | CfgImportProgress
+  | CfgLastLogs
+  | CfgProgressLog
+  | CfgLogHandle;
+
+//
+// Isolate / Rendering Mode
+//
+
+/** Forces wrapped config to be rendered asynchronously, using its own
+ * rendering cell */
+export type CfgIsolate = {
+  type: 'Isolate';
+  cfg: Cfg;
+};
+
+//
+// Context
+//
+
+export type CfgGetFromCtx = {
+  type: 'GetFromCtx';
+  variable: string;
+};
+
+//
+// Json
+//
+
+export type CfgImmediate = {
+  type: 'Immediate';
+  value: any;
+};
+
+export type CfgGetJsonField = {
+  type: 'GetJsonField';
+  source: Cfg;
+  field: Cfg;
+};
+
+export type CfgMakeObject = {
+  type: 'MakeObject';
+  template: Record<string, Cfg>;
+};
+
+export type CfgMakeArray = {
+  type: 'MakeArray';
+  template: Cfg[];
+};
+
+export type CfgMapRecordValues = {
+  type: 'MapRecordValues';
+  source: Cfg;
+  itVar: string;
+  mapping: Cfg;
+};
+
+export type CfgMapArrayValues = {
+  type: 'MapArrayValues';
+  source: Cfg;
+  itVar: string;
+  mapping: Cfg;
+};
+
+export type CfgFlatten = {
+  type: 'Flatten';
+  source: Cfg;
+};
+
+//
+// Boolean
+//
+
+export type CfgIsEmpty = {
+  type: 'IsEmpty';
+  arg: Cfg;
+};
+
+export type CfgNot = {
+  type: 'Not';
+  operand: Cfg;
+};
+
+export type CfgAnd = {
+  type: 'And';
+  operand1: Cfg;
+  operand2: Cfg;
+};
+
+export type CfgOr = {
+  type: 'Or';
+  operand1: Cfg;
+  operand2: Cfg;
+};
+
+//
+// Resources
+//
+
+export type CfgMapResourceFields = {
+  type: 'MapResourceFields';
+  source: Cfg;
+  itVar: string;
+  mapping: Cfg;
+};
+
+export type CfgGetResourceField = {
+  type: 'GetResourceField';
+  source: Cfg;
+  field: Cfg;
+};
+
+export type CfgResourceValueAsJson = {
+  type: 'GetResourceValueAsJson';
+  source: Cfg;
+};
+
+//
+// Download Blobs
+//
+
+export type CfgBlobContent = {
+  type: 'GetBlobContent';
+  source: Cfg;
+};
+
+export type CfgBlobContentAsString = {
+  type: 'GetBlobContentAsString';
+  source: Cfg;
+};
+
+export type CfgBlobContentAsJson = {
+  type: 'GetBlobContentAsJson';
+  source: Cfg;
+};
+
+export type CfgDownloadedBlobContent = {
+  type: 'GetDownloadedBlobContent';
+  source: Cfg;
+};
+
+export type CfgOnDemandBlobContent = {
+  type: 'GetOnDemandBlobContent';
+  source: Cfg;
+};
+
+//
+// Uploads Blobs
+//
+
+export type CfgImportProgress = {
+  type: 'GetImportProgress';
+  source: Cfg;
+};
+
+//
+// Logs
+//
+
+export type CfgLastLogs = {
+  type: 'GetLastLogs';
+  source: Cfg;
+  lines: number;
+};
+
+export type CfgProgressLog = {
+  type: 'GetProgressLog';
+  source: Cfg;
+  patternToSearch: string;
+};
+
+export type CfgLogHandle = {
+  type: 'GetLogHandle';
+  source: Cfg;
+};

package/src/config/model_meta.ts

@@ -0,0 +1,5 @@
+/** Divides all configurations into two broad classes. Some configs can be
+ * executed synchronously, given all their arguments are already rendered.
+ * Some require creation of a separate rendering cell, like downloading
+ * files. */
+export type CfgRenderingMode = 'Sync' | 'Async';

package/src/config/type_engine.ts

@@ -0,0 +1,58 @@
+import { ActGetImmediate } from './actions_kinds';
+import { Cfg } from './model';
+
+// Higher kind types pattern taken from here: https://code.lol/post/programming/higher-kinded-types/
+
+type GenericFunction = (x: any) => unknown;
+
+/** This is a type constructor deriving a returned type of config given the
+ * context type. Something like ConfAction<Cfg> -> ReturnedType.  */
+export interface ConfAction {
+  readonly ctx: unknown;
+  new: GenericFunction;
+  isSync: boolean;
+}
+
+/** This type basically sets parameter to a ConfAction kind. */
+export type ActionResult<A extends ConfAction, Ctx> = ReturnType<
+  (A & {
+    readonly ctx: Ctx;
+  })['new']
+>;
+
+// Branding pattern taken from here: https://egghead.io/blog/using-branded-types-in-typescript
+
+/** Field key to attach ConfAction information to a config type. */
+declare const __config_action__: unique symbol;
+
+/** Creates branded Cfg type */
+export type TypedConfig<Action extends ConfAction = ConfAction> = Cfg & {
+  [__config_action__]: Action;
+};
+
+export type PrimitiveOrConfig = TypedConfig | string | number | boolean | null;
+
+/** Converts primitive types to immediate config */
+export type PrimitiveToCfg<T extends PrimitiveOrConfig> = T extends string | number | boolean | null
+  ? TypedConfig<ActGetImmediate<T>>
+  : T;
+
+/** Extracts action */
+export type ExtractAction<Cfg extends TypedConfig> = Cfg[typeof __config_action__];
+
+export type POCExtractAction<T extends PrimitiveOrConfig> = ExtractAction<PrimitiveToCfg<T>>;
+
+export type InferVarTypeSafe<Ctx, V> = V extends string
+  ? Ctx extends { [key in V]: infer T }
+    ? T
+    : undefined
+  : unknown;
+
+export type ConfigResult<Cfg extends TypedConfig, Ctx> = ActionResult<ExtractAction<Cfg>, Ctx>;
+
+declare const plResourceEntry: unique symbol;
+
+/** Marks that a certain variable in context is a resource entry */
+export type PlResourceEntry = typeof plResourceEntry;
+
+export type OptionalPlResourceEntry = PlResourceEntry | undefined;

package/src/config/type_util.ts

@@ -0,0 +1,25 @@
+import { ExtractAction, TypedConfig } from './type_engine';
+
+export type SyncConfAction = { isSync: true };
+
+export type IsSyncConf<Cfg extends TypedConfig> =
+  ExtractAction<Cfg> extends SyncConfAction ? true : false;
+export type CheckedSyncConf<Cfg extends TypedConfig> = Checked<Cfg, IsSyncConf<Cfg>>;
+
+export type Not<T extends boolean> = T extends true ? false : true;
+
+export type Or<A extends boolean, B extends boolean> = A extends true
+  ? true
+  : B extends true
+    ? true
+    : false;
+
+export type And<A extends boolean, B extends boolean> = A extends true
+  ? B extends true
+    ? true
+    : false
+  : false;
+
+export type IsA<T, E> = T extends E ? true : false;
+
+export type Checked<Type, Condition> = Condition extends true ? Type : 'error';

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from './block_state_patch';
+export * from './block_state_util';
+export * from './builder';
+export * from './components';
+export * from './config';
+export * from './pframe';
+export * from './platforma';
+export * from './ref_util';
+export * from './render';
+export * from './sdk_info';
+
+// reexporting everything from SDK model
+export * from '@milaboratories/pl-model-common';
+
+export * as JsRenderInternal from './render/internal';

package/src/internal.ts

@@ -0,0 +1,56 @@
+import { Platforma, PlatformaFactory } from './platforma';
+import { BlockConfig } from './builder';
+import { FutureHandle, GlobalCfgRenderCtx } from './render/internal';
+
+declare global {
+  /** Global factory method returning platforma instance */
+  const getPlatforma: PlatformaFactory;
+  const platforma: Platforma;
+
+  /** Global rendering context, present only in rendering environment */
+  const cfgRenderCtx: GlobalCfgRenderCtx;
+}
+
+/** Utility code helping to identify whether the code is running in actual UI environment */
+export function isInUI() {
+  return typeof getPlatforma !== 'undefined' || typeof platforma !== 'undefined';
+}
+
+/** Utility code helping to retrieve a platforma instance form the environment */
+export function getPlatformaInstance(config: BlockConfig): Platforma {
+  if (typeof getPlatforma === 'function') return getPlatforma(config);
+  else if (typeof platforma !== 'undefined') return platforma;
+  else throw new Error("Can't get platforma instance.");
+}
+
+export function tryGetCfgRenderCtx(): GlobalCfgRenderCtx | undefined {
+  if (typeof cfgRenderCtx !== 'undefined') return cfgRenderCtx;
+  else return undefined;
+}
+
+export function getCfgRenderCtx(): GlobalCfgRenderCtx {
+  if (typeof cfgRenderCtx !== 'undefined') return cfgRenderCtx;
+  else throw new Error('Not in config rendering context');
+}
+
+export function tryRegisterCallback(key: string, callback: (...args: any[]) => any): boolean {
+  const ctx = tryGetCfgRenderCtx();
+  if (ctx === undefined) return false;
+  if (key in ctx.callbackRegistry) throw new Error(`Callback with key ${key} already registered.`);
+  ctx.callbackRegistry[key] = callback;
+  return true;
+}
+
+const futureResolves = new Map<string, ((value: unknown) => void)[]>();
+
+export function registerFutureAwait(handle: FutureHandle, onResolve: (value: unknown) => void) {
+  if (!(handle in getCfgRenderCtx().callbackRegistry)) {
+    getCfgRenderCtx().callbackRegistry[handle] = (value: unknown) => {
+      for (const res of futureResolves.get(handle)!) {
+        res(value);
+      }
+    };
+    futureResolves.set(handle, []);
+  }
+  futureResolves.get(handle)!.push(onResolve);
+}

package/src/pframe.ts

@@ -0,0 +1,39 @@
+import {
+  CalculateTableDataRequest,
+  CalculateTableDataResponse,
+  FindColumnsRequest,
+  FindColumnsResponse,
+  PColumnIdAndSpec,
+  PColumnSpec,
+  PFrame,
+  PFrameHandle,
+  PObjectId,
+  UniqueValuesRequest,
+  UniqueValuesResponse
+} from '@milaboratories/pl-model-common';
+
+export class PFrameImpl implements PFrame {
+  constructor(private readonly handle: PFrameHandle) {}
+
+  public async findColumns(request: FindColumnsRequest): Promise<FindColumnsResponse> {
+    return await platforma.pFrameDriver.findColumns(this.handle, request);
+  }
+
+  public async getColumnSpec(columnId: PObjectId): Promise<PColumnSpec> {
+    return await platforma.pFrameDriver.getColumnSpec(this.handle, columnId);
+  }
+
+  public async listColumns(): Promise<PColumnIdAndSpec[]> {
+    return await platforma.pFrameDriver.listColumns(this.handle);
+  }
+
+  public async calculateTableData(
+    request: CalculateTableDataRequest<PObjectId>
+  ): Promise<CalculateTableDataResponse> {
+    return await platforma.pFrameDriver.calculateTableData(this.handle, request);
+  }
+
+  public async getUniqueValues(request: UniqueValuesRequest): Promise<UniqueValuesResponse> {
+    return await platforma.pFrameDriver.getUniqueValues(this.handle, request);
+  }
+}

package/src/platforma.ts

@@ -0,0 +1,46 @@
+import { BlockApi } from './block_api';
+import { BlockOutputsBase, BlockState, DriverKit, ValueOrErrors } from '@milaboratories/pl-model-common';
+import { BlockConfig } from './builder';
+import { SdkInfo } from './sdk_info';
+import { BlockStatePatch } from './block_state_patch';
+
+/** Defines all methods to interact with the platform environment from within a block UI. */
+export interface Platforma<
+  Args = unknown,
+  Outputs extends Record<string, ValueOrErrors<unknown>> = Record<string, ValueOrErrors<unknown>>,
+  UiState = unknown,
+  Href extends `/${string}` = `/${string}`
+> extends BlockApi<Args, Outputs, UiState, Href>,
+    DriverKit {
+  /** Information about SDK version current platforma environment was compiled with. */
+  readonly sdkInfo: SdkInfo;
+}
+
+export type InferArgsType<Pl extends Platforma> = Pl extends Platforma<infer Args> ? Args : never;
+
+export type InferOutputsType<Pl extends Platforma> =
+  Pl extends Platforma<unknown, infer Outputs> ? Outputs : never;
+
+export type InferUiState<Pl extends Platforma> =
+  Pl extends Platforma<unknown, Record<string, ValueOrErrors<unknown>>, infer UiState>
+    ? UiState
+    : never;
+
+export type InferHrefType<Pl extends Platforma> =
+  Pl extends Platforma<unknown, BlockOutputsBase, unknown, infer Href> ? Href : never;
+
+export type PlatformaFactory = (config: BlockConfig) => Platforma;
+
+export type InferBlockState<Pl extends Platforma> = BlockState<
+  InferArgsType<Pl>,
+  InferOutputsType<Pl>,
+  InferUiState<Pl>,
+  InferHrefType<Pl>
+>;
+
+export type InferBlockStatePatch<Pl extends Platforma> = BlockStatePatch<
+  InferArgsType<Pl>,
+  InferOutputsType<Pl>,
+  InferUiState<Pl>,
+  InferHrefType<Pl>
+>;

package/src/ref_util.ts

@@ -0,0 +1,16 @@
+import { getJsonField, makeObject, TypedConfig } from './config';
+
+export function fromPlRef<Source extends TypedConfig>(source: Source) {
+  return makeObject({
+    __isRef: true,
+    blockId: getJsonField(source, 'blockId'),
+    name: getJsonField(source, 'name')
+  });
+}
+
+export function fromPlOption<Source extends TypedConfig>(source: Source) {
+  return makeObject({
+    ref: fromPlRef(getJsonField(source, 'ref')),
+    label: getJsonField(source, 'label')
+  });
+}

package/src/render/accessor.ts

@@ -0,0 +1,223 @@
+import {
+  AnyLogHandle,
+  ImportProgress,
+  LocalBlobHandleAndSize,
+  PColumn,
+  PObject,
+  RemoteBlobHandleAndSize,
+  isPColumn,
+  mapPObjectData
+} from '@milaboratories/pl-model-common';
+import { getCfgRenderCtx } from '../internal';
+import { FutureRef } from './future';
+import { AccessorHandle } from './internal';
+import { CommonFieldTraverseOps, FieldTraversalStep, ResourceType } from './traversal_ops';
+
+function ifDef<T, R>(value: T | undefined, cb: (value: T) => R): R | undefined {
+  return value === undefined ? undefined : cb(value);
+}
+
+function wrapBuffer(buf: ArrayBuffer | undefined): Uint8Array | undefined {
+  return buf === undefined ? undefined : new Uint8Array(buf);
+}
+
+function wrapAccessor(handle: AccessorHandle | undefined): TreeNodeAccessor | undefined {
+  return handle === undefined ? undefined : new TreeNodeAccessor(handle);
+}
+
+/** Represent resource tree node accessor */
+export class TreeNodeAccessor {
+  constructor(public readonly handle: AccessorHandle) {}
+
+  public resolve(
+    ...steps: [
+      Omit<FieldTraversalStep, 'errorIfFieldNotSet'> & {
+        errorIfFieldNotAssigned: true;
+      }
+    ]
+  ): TreeNodeAccessor;
+  public resolve(...steps: (FieldTraversalStep | string)[]): TreeNodeAccessor | undefined;
+  public resolve(...steps: (FieldTraversalStep | string)[]): TreeNodeAccessor | undefined {
+    return this.resolveWithCommon({}, ...steps);
+  }
+
+  public resolveWithCommon(
+    commonOptions: CommonFieldTraverseOps,
+    ...steps: (FieldTraversalStep | string)[]
+  ): TreeNodeAccessor | undefined {
+    return wrapAccessor(getCfgRenderCtx().resolveWithCommon(this.handle, commonOptions, ...steps));
+  }
+
+  public get resourceType(): ResourceType {
+    return getCfgRenderCtx().getResourceType(this.handle);
+  }
+
+  public getInputsLocked(): boolean {
+    return getCfgRenderCtx().getInputsLocked(this.handle);
+  }
+
+  public getOutputsLocked(): boolean {
+    return getCfgRenderCtx().getOutputsLocked(this.handle);
+  }
+
+  public getIsReadyOrError(): boolean {
+    return getCfgRenderCtx().getIsReadyOrError(this.handle);
+  }
+
+  public getIsFinal(): boolean {
+    return getCfgRenderCtx().getIsFinal(this.handle);
+  }
+
+  public getError(): TreeNodeAccessor | undefined {
+    return wrapAccessor(getCfgRenderCtx().getError(this.handle));
+  }
+
+  public listInputFields(): string[] {
+    return getCfgRenderCtx().listInputFields(this.handle);
+  }
+
+  public listOutputFields(): string[] {
+    return getCfgRenderCtx().listOutputFields(this.handle);
+  }
+
+  public listDynamicFields(): string[] {
+    return getCfgRenderCtx().listDynamicFields(this.handle);
+  }
+
+  public getKeyValueBase64(key: string): string | undefined {
+    return getCfgRenderCtx().getKeyValueBase64(this.handle, key);
+  }
+
+  public getKeyValueAsString(key: string): string | undefined {
+    return getCfgRenderCtx().getKeyValueAsString(this.handle, key);
+  }
+
+  public getKeyValueAsJson<T>(key: string): T {
+    const content = this.getKeyValueAsString(key);
+    if (content == undefined) throw new Error('Resource has no content.');
+    return JSON.parse(content);
+  }
+
+  public getDataBase64(): string | undefined {
+    return getCfgRenderCtx().getDataBase64(this.handle);
+  }
+
+  public getDataAsString(): string | undefined {
+    return getCfgRenderCtx().getDataAsString(this.handle);
+  }
+
+  public getDataAsJson<T>(): T {
+    const content = this.getDataAsString();
+    if (content == undefined) throw new Error('Resource has no content.');
+    return JSON.parse(content);
+  }
+
+  /**
+   *
+   */
+  public getPColumns(
+    errorOnUnknownField: boolean = false,
+    prefix: string = ''
+  ): PColumn<TreeNodeAccessor>[] | undefined {
+    const result = this.parsePObjectCollection(errorOnUnknownField, prefix);
+    if (result === undefined) return undefined;
+
+    const pf = Object.entries(result).map(([, obj]) => {
+      if (!isPColumn(obj)) throw new Error(`not a PColumn (kind = ${obj.spec.kind})`);
+      return obj;
+    });
+
+    return pf;
+  }
+
+  /**
+   *
+   */
+  public parsePObjectCollection(
+    errorOnUnknownField: boolean = false,
+    prefix: string = ''
+  ): Record<string, PObject<TreeNodeAccessor>> | undefined {
+    const pObjects = getCfgRenderCtx().parsePObjectCollection(
+      this.handle,
+      errorOnUnknownField,
+      prefix
+    );
+    if (pObjects === undefined) return undefined;
+    const result: Record<string, PObject<TreeNodeAccessor>> = {};
+    for (const [key, value] of Object.entries(pObjects))
+      result[key] = mapPObjectData(value, (c) => new TreeNodeAccessor(c));
+    return result;
+  }
+
+  public getFileContentAsBase64(): FutureRef<string | undefined> {
+    return new FutureRef(getCfgRenderCtx().getBlobContentAsBase64(this.handle));
+  }
+
+  public getFileContentAsString(): FutureRef<string | undefined> {
+    return new FutureRef(getCfgRenderCtx().getBlobContentAsString(this.handle));
+  }
+
+  public getFileContentAsJson<T>(): FutureRef<T | undefined> {
+    return new FutureRef<string | undefined>(
+      getCfgRenderCtx().getBlobContentAsString(this.handle)
+    ).mapDefined((v) => JSON.parse(v) as T);
+  }
+
+  /**
+   * @deprecated use getFileContentAsBase64
+   */
+  public getBlobContentAsBase64(): FutureRef<string | undefined> {
+    return this.getFileContentAsBase64();
+  }
+
+  /**
+   * @deprecated use getFileContentAsString
+   */
+  public getBlobContentAsString(): FutureRef<string | undefined> {
+    return this.getFileContentAsString();
+  }
+
+  /**
+   * @returns downloaded file handle
+   */
+  public getFileHandle(): FutureRef<LocalBlobHandleAndSize | undefined> {
+    return new FutureRef(getCfgRenderCtx().getDownloadedBlobContentHandle(this.handle));
+  }
+
+  /**
+   * @deprecated use getFileHandle
+   */
+  public getDownloadedBlobHandle(): FutureRef<LocalBlobHandleAndSize | undefined> {
+    return this.getFileHandle();
+  }
+
+  /**
+   * @returns downloaded file handle
+   */
+  public getRemoteFileHandle(): FutureRef<RemoteBlobHandleAndSize | undefined> {
+    return new FutureRef(getCfgRenderCtx().getOnDemandBlobContentHandle(this.handle));
+  }
+
+  /**
+   * @deprecated use getRemoteFileHandle
+   */
+  public getOnDemandBlobHandle(): FutureRef<RemoteBlobHandleAndSize | undefined> {
+    return this.getRemoteFileHandle();
+  }
+
+  public getImportProgress(): FutureRef<ImportProgress> {
+    return new FutureRef(getCfgRenderCtx().getImportProgress(this.handle));
+  }
+
+  public getLastLogs(nLines: number): FutureRef<string | undefined> {
+    return new FutureRef(getCfgRenderCtx().getLastLogs(this.handle, nLines));
+  }
+
+  public getProgressLog(patternToSearch: string): FutureRef<string | undefined> {
+    return new FutureRef(getCfgRenderCtx().getProgressLog(this.handle, patternToSearch));
+  }
+
+  public getLogHandle(): FutureRef<AnyLogHandle | undefined> {
+    return new FutureRef(getCfgRenderCtx().getLogHandle(this.handle));
+  }
+}