@platforma-sdk/model 1.2.22

package/src/render/api.ts

@@ -0,0 +1,170 @@
+import {
+  Option,
+  PColumn,
+  PFrameDef,
+  PFrameHandle,
+  PObject,
+  PObjectSpec,
+  PSpecPredicate,
+  PTableDef,
+  PTableHandle,
+  PTableRecordFilter,
+  PTableSorting,
+  ResultCollection,
+  ValueOrError,
+  mapPObjectData,
+  mapPTableDef,
+  mapValueInVOE
+} from '@milaboratories/pl-model-common';
+import { Optional } from 'utility-types';
+import { getCfgRenderCtx } from '../internal';
+import { TreeNodeAccessor } from './accessor';
+import { FutureRef } from './future';
+import { GlobalCfgRenderCtx, MainAccessorName, StagingAccessorName } from './internal';
+
+export class ResultPool {
+  private readonly ctx: GlobalCfgRenderCtx = getCfgRenderCtx();
+
+  public calculateOptions(predicate: PSpecPredicate): Option[] {
+    return this.ctx.calculateOptions(predicate);
+  }
+
+  public getDataFromResultPool(): ResultCollection<PObject<TreeNodeAccessor>> {
+    const result = this.ctx.getDataFromResultPool();
+    return {
+      isComplete: result.isComplete,
+      entries: result.entries.map((e) => ({
+        ref: e.ref,
+        obj: {
+          ...e.obj,
+          data: new TreeNodeAccessor(e.obj.data)
+        }
+      }))
+    };
+  }
+
+  public getDataWithErrorsFromResultPool(): ResultCollection<
+    Optional<PObject<ValueOrError<TreeNodeAccessor, string>>, 'id'>
+  > {
+    const result = this.ctx.getDataWithErrorsFromResultPool();
+    return {
+      isComplete: result.isComplete,
+      entries: result.entries.map((e) => ({
+        ref: e.ref,
+        obj: {
+          ...e.obj,
+          data: mapValueInVOE(e.obj.data, (handle) => new TreeNodeAccessor(handle))
+        }
+      }))
+    };
+  }
+
+  public getSpecsFromResultPool(): ResultCollection<PObjectSpec> {
+    return this.ctx.getSpecsFromResultPool();
+  }
+}
+
+export class RenderCtx<Args, UiState> {
+  private readonly ctx: GlobalCfgRenderCtx;
+
+  public readonly args: Args;
+  public readonly uiState: UiState | undefined;
+
+  constructor() {
+    this.ctx = getCfgRenderCtx();
+    this.args = JSON.parse(this.ctx.args);
+    this.uiState = this.ctx.uiState !== undefined ? JSON.parse(this.ctx.uiState) : undefined;
+  }
+
+  private getNamedAccessor(name: string): TreeNodeAccessor | undefined {
+    const accessorId = this.ctx.getAccessorHandleByName(name);
+    return accessorId ? new TreeNodeAccessor(accessorId) : undefined;
+  }
+
+  public get prerun(): TreeNodeAccessor | undefined {
+    return this.getNamedAccessor(StagingAccessorName);
+  }
+
+  /**
+   * @deprecated use prerun
+   */
+  public get precalc(): TreeNodeAccessor | undefined {
+    return this.prerun;
+  }
+
+  /**
+   * @deprecated use prerun
+   */
+  public get stagingOutput(): TreeNodeAccessor | undefined {
+    return this.precalc;
+  }
+
+  public get outputs(): TreeNodeAccessor | undefined {
+    return this.getNamedAccessor(MainAccessorName);
+  }
+
+  /**
+   * @deprecated use outputs
+   */
+  public get mainOutput(): TreeNodeAccessor | undefined {
+    return this.outputs;
+  }
+
+  public readonly resultPool = new ResultPool();
+
+  public createPFrame(def: PFrameDef<TreeNodeAccessor>): PFrameHandle {
+    return this.ctx.createPFrame(def.map((c) => mapPObjectData(c, (d) => d.handle)));
+  }
+
+  public createPTable(def: PTableDef<PColumn<TreeNodeAccessor>>): PTableHandle;
+  public createPTable(def: {
+    columns: PColumn<TreeNodeAccessor>[];
+    filters?: PTableRecordFilter[];
+    /** Table sorting */
+    sorting?: PTableSorting[];
+  }): PTableHandle;
+  public createPTable(
+    def:
+      | PTableDef<PColumn<TreeNodeAccessor>>
+      | {
+          columns: PColumn<TreeNodeAccessor>[];
+          filters?: PTableRecordFilter[];
+          /** Table sorting */
+          sorting?: PTableSorting[];
+        }
+  ): PTableHandle {
+    var rawDef: PTableDef<PColumn<TreeNodeAccessor>>;
+    if ('columns' in def) {
+      rawDef = {
+        src: {
+          type: 'inner',
+          entries: def.columns.map((c) => ({ type: 'column', column: c }))
+        },
+        filters: def.filters ?? [],
+        sorting: def.sorting ?? []
+      };
+    } else {
+      rawDef = def;
+    }
+    return this.ctx.createPTable(mapPTableDef(rawDef, (po) => mapPObjectData(po, (d) => d.handle)));
+  }
+
+  public getBlockLabel(blockId: string): string {
+    return this.ctx.getBlockLabel(blockId);
+  }
+}
+
+export type RenderFunction<Args = unknown, UiState = unknown, Ret = unknown> = (
+  rCtx: RenderCtx<Args, UiState>
+) => Ret;
+
+export type UnwrapFutureRef<K> =
+  K extends FutureRef<infer T>
+    ? T
+    : K extends bigint | boolean | null | number | string | symbol | undefined
+      ? K
+      : { [key in keyof K]: UnwrapFutureRef<K[key]> };
+
+export type InferRenderFunctionReturn<RF extends Function> = RF extends (...args: any) => infer R
+  ? UnwrapFutureRef<R>
+  : never;

package/src/render/future.ts

@@ -0,0 +1,37 @@
+import { FutureAwait, FutureHandle } from './internal';
+import { registerFutureAwait } from '../internal';
+
+export class FutureRef<T = unknown> {
+  private isResolved = false;
+  private resolvedValue?: T;
+
+  constructor(
+    private readonly handle: FutureHandle,
+    private readonly postProcess: (value: unknown) => T = (v) => v as T
+  ) {
+    registerFutureAwait(handle, (value) => {
+      this.resolvedValue = postProcess(value);
+      this.isResolved = true;
+    });
+  }
+
+  public map<R>(mapping: (v: T) => R): FutureRef<R> {
+    return new FutureRef<R>(this.handle, (v) => mapping(this.postProcess(v)));
+  }
+
+  public mapDefined<R>(mapping: (v: NonNullable<T>) => R): FutureRef<R | undefined> {
+    return new FutureRef<R | undefined>(this.handle, (v) => {
+      const vv = this.postProcess(v);
+      return vv ? mapping(vv) : undefined;
+    });
+  }
+
+  toJSON(): any {
+    return this.isResolved
+      ? this.resolvedValue
+      : ({ __awaited_futures__: [this.handle] } as FutureAwait);
+  }
+}
+
+export type ExtractFutureRefType<Ref extends FutureRef> =
+  Ref extends FutureRef<infer T> ? T : never;

package/src/render/index.ts

@@ -0,0 +1,5 @@
+export * from './api';
+export * from './traversal_ops';
+export * from './accessor';
+export { ExtractFutureRefType } from './future';
+export { FutureRef } from './future';

package/src/render/internal.ts

@@ -0,0 +1,164 @@
+import { Optional } from 'utility-types';
+import { Branded } from '../branding';
+import { CommonFieldTraverseOps, FieldTraversalStep, ResourceType } from './traversal_ops';
+import {
+  Option,
+  PColumn,
+  PFrameDef,
+  PFrameHandle,
+  PObject,
+  PObjectSpec,
+  PSpecPredicate,
+  PTableDef,
+  PTableHandle,
+  ResultCollection,
+  ValueOrError
+} from '@milaboratories/pl-model-common';
+
+export const StagingAccessorName = 'staging';
+export const MainAccessorName = 'main';
+
+export type AccessorHandle = Branded<string, 'AccessorHandle'>;
+export type FutureHandle = Branded<string, 'FutureHandle'>;
+
+export interface GlobalCfgRenderCtxMethods<AHandle = AccessorHandle, FHandle = FutureHandle> {
+  //
+  // Root accessor creation
+  //
+
+  getAccessorHandleByName(name: string): AHandle | undefined;
+
+  //
+  // Basic resource accessor actions
+  //
+
+  resolveWithCommon(
+    handle: AHandle,
+    commonOptions: CommonFieldTraverseOps,
+    ...steps: (FieldTraversalStep | string)[]
+  ): AHandle | undefined;
+
+  getResourceType(handle: AHandle): ResourceType;
+
+  getInputsLocked(handle: AHandle): boolean;
+
+  getOutputsLocked(handle: AHandle): boolean;
+
+  getIsReadyOrError(handle: AHandle): boolean;
+
+  getIsFinal(handle: AHandle): boolean;
+
+  getError(handle: AHandle): AHandle | undefined;
+
+  listInputFields(handle: AHandle): string[];
+
+  listOutputFields(handle: AHandle): string[];
+
+  listDynamicFields(handle: AHandle): string[];
+
+  getKeyValueBase64(handle: AHandle, key: string): string | undefined;
+
+  getKeyValueAsString(handle: AHandle, key: string): string | undefined;
+
+  getDataBase64(handle: AHandle): string | undefined;
+
+  getDataAsString(handle: AHandle): string | undefined;
+
+  /** If not final returns undefined */
+  parsePObjectCollection(
+    handle: AHandle,
+    errorOnUnknownField: boolean,
+    prefix: string
+  ): Record<string, PObject<AHandle>> | undefined;
+
+  //
+  // Blob
+  //
+
+  getBlobContentAsBase64(handle: AHandle): FHandle; // string | undefined
+
+  getBlobContentAsString(handle: AHandle): FHandle; // string | undefined
+
+  getDownloadedBlobContentHandle(handle: AHandle): FHandle; // LocalBlobHandleAndSize | undefined;
+
+  getOnDemandBlobContentHandle(handle: AHandle): FHandle; // RemoteBlobHandleAndSize | undefined;
+
+  //
+  // Import progress
+  //
+
+  getImportProgress(handle: AHandle): FHandle; // ImportProgress;
+
+  //
+  // Logs
+  //
+
+  getLastLogs(handle: AHandle, nLines: number): FHandle; // string | undefined;
+
+  getProgressLog(handle: AHandle, patternToSearch: string): FHandle; // string | undefined;
+
+  getLogHandle(handle: AHandle): FHandle; // AnyLogHandle | undefined;
+
+  //
+  // Blocks
+  //
+
+  getBlockLabel(blockId: string): string;
+
+  //
+  // Result Pool
+  //
+
+  getDataFromResultPool(): ResultCollection<PObject<AHandle>>;
+
+  getDataWithErrorsFromResultPool(): ResultCollection<
+    Optional<PObject<ValueOrError<AHandle, string>>, 'id'>
+  >;
+
+  getSpecsFromResultPool(): ResultCollection<PObjectSpec>;
+
+  calculateOptions(predicate: PSpecPredicate): Option[];
+
+  //
+  // PFrame / PTable
+  //
+
+  createPFrame(def: PFrameDef<AHandle>): PFrameHandle;
+
+  createPTable(def: PTableDef<PColumn<AHandle>>): PTableHandle;
+}
+
+export interface GlobalCfgRenderCtx extends GlobalCfgRenderCtxMethods {
+  readonly args: string;
+  readonly uiState?: string;
+  readonly callbackRegistry: Record<string, Function>;
+}
+
+export type FutureAwait = {
+  __awaited_futures__: FutureHandle[];
+};
+
+export function isFutureAwait(obj: unknown): obj is FutureAwait {
+  return typeof obj === 'object' && obj !== null && '__awaited_futures__' in obj;
+}
+
+function addAllFutureAwaits(set: Set<string>, visited: Set<unknown>, node: unknown) {
+  if (visited.has(node)) return;
+  visited.add(node);
+
+  const type = typeof node;
+  if (type === 'object') {
+    if (isFutureAwait(node)) node.__awaited_futures__.forEach((a) => set.add(a));
+    else if (Array.isArray(node))
+      for (const nested of node) addAllFutureAwaits(set, visited, nested);
+    else
+      for (const [, nested] of Object.entries(node as object))
+        if (nested !== node) addAllFutureAwaits(set, visited, nested);
+  }
+}
+
+export function getAllFutureAwaits(obj: unknown): Set<string> {
+  const set = new Set<string>();
+  addAllFutureAwaits(set, new Set(), obj);
+  return set;
+}

package/src/render/traversal_ops.ts

@@ -0,0 +1,55 @@
+export type CommonTraversalOps = {
+  /**
+   * Don't terminate chain if current resource or field has an error associated
+   * with, by default resource or field error will be thrown. If field has error
+   * and no value, error will be thrown anyway, because this is the reason
+   * traversal is terminated.
+   * */
+  ignoreError?: true;
+};
+
+export type CommonFieldTraverseOps = {
+  /**
+   * Valid only if {@link assertFieldType} is defined and equal to 'Input',
+   * 'Service' or 'Output'. By default, if field is not found, and corresponding
+   * field list is locked, call will fail with exception.
+   * */
+  allowPermanentAbsence?: true;
+
+  /** Will not mark current context as unstable, if field is not found. */
+  stableIfNotFound?: true;
+};
+
+export type FieldType = 'Input' | 'Output' | 'Service' | 'OTW' | 'Dynamic' | 'MTW';
+
+export interface ResourceType {
+  readonly name: string;
+  readonly version: string;
+}
+
+export type ResourceTraversalOps = CommonTraversalOps & {
+  /**
+   * Assert resource type of the resource the fields points to. Call will fail
+   * with exception if this assertion is not fulfilled.
+   * */
+  assertResourceType?: ResourceType | ResourceType[];
+};
+
+export type GetFieldStep = CommonFieldTraverseOps & {
+  /** Field name */
+  field: string;
+
+  /** Field must exist, if this option is set, instead error will be thrown */
+  errorIfFieldNotFound?: true;
+
+  /** Field must be assigned a value, if this option is set, instead error will be thrown */
+  errorIfFieldNotSet?: true;
+
+  /**
+   * Assert field type. Call will fail with exception if this assertion is not
+   * fulfilled
+   * */
+  assertFieldType?: FieldType;
+};
+
+export type FieldTraversalStep = GetFieldStep & ResourceTraversalOps;

package/src/sdk_info.ts

@@ -0,0 +1,9 @@
+import { PlatformaSDKVersion } from './version';
+
+export type SdkInfo = {
+  readonly sdkVersion: string;
+};
+
+export const CurrentSdkInfo: SdkInfo = {
+  sdkVersion: PlatformaSDKVersion
+};

package/src/typing.test.ts

@@ -0,0 +1,177 @@
+import {
+  BlockSection,
+  LocalBlobHandleAndSize,
+  RemoteBlobHandleAndSize,
+  ValueOrErrors
+} from '@milaboratories/pl-model-common';
+import { BlockModel, DeriveHref, StdCtx } from './builder';
+import {
+  Args,
+  ConfigResult,
+  flatten,
+  getBlobContent,
+  getBlobContentAsJson,
+  getBlobContentAsString,
+  getDownloadedBlobContent,
+  getImmediate,
+  getJsonField,
+  getOnDemandBlobContent,
+  getResourceField,
+  getResourceValueAsJson,
+  isEmpty,
+  It,
+  MainOutputs,
+  makeArray,
+  makeObject,
+  mapArrayValues,
+  mapRecordValues
+} from './config';
+import { InferHrefType, InferOutputsType } from './platforma';
+
+type AssertEqual<T, Expected> = [T] extends [Expected]
+  ? [Expected] extends [T]
+    ? true
+    : false
+  : false;
+
+export const assertType = <T, Expected>(
+  ..._: AssertEqual<T, Expected> extends true ? [] : ['invalid type']
+) => {
+  // noop
+};
+
+type AssertExtends<T, Expected> = T extends Expected ? true : false;
+
+export const assertTypeExtends = <T, Expected>(
+  ..._: AssertExtends<T, Expected> extends true ? [] : ['invalid type']
+) => {
+  // noop
+};
+
+function typeTest1() {
+  const a = getJsonField(Args, 'field1');
+  const dd = getResourceValueAsJson<{ s: boolean; g: number }>()(
+    getResourceField(MainOutputs, 'a')
+  );
+
+  const cfg1 = makeObject({
+    a,
+    b: 'attagaca',
+    c: mapRecordValues(getJsonField(Args, 'field2'), getJsonField(It, 'b')),
+    d: getJsonField(dd, 's')
+  });
+
+  type Ret = ConfigResult<
+    typeof cfg1,
+    StdCtx<{
+      field1: number;
+      field2: Record<string, { b: 'yap' }>;
+    }>
+  >;
+
+  assertType<
+    Ret,
+    {
+      a: number;
+      b: 'attagaca';
+      c: Record<string, 'yap'>;
+      d: boolean;
+    }
+  >();
+}
+
+function testCreateSections<const S extends BlockSection[]>(sections: () => S): DeriveHref<S> {
+  return undefined as any;
+}
+
+test('test config content', () => {
+  const s1 = testCreateSections(() => [
+    { type: 'delimiter' },
+    { type: 'link', href: '/a1', label: 'l' },
+    { type: 'link', href: '/a2', label: 'ls' }
+  ]);
+
+  assertType<typeof s1, '/a1' | '/a2'>();
+
+  const s2 = testCreateSections(() => [{ type: 'delimiter' }]);
+
+  assertType<typeof s2, never>();
+});
+
+test('test config content', () => {
+  const platforma = BlockModel.create<{ a: string[] }>('Heavy')
+    .initialArgs({ a: [] })
+    .output('cell1', makeObject({ b: getJsonField(Args, 'a') }))
+    .output('cell2', mapArrayValues(getJsonField(Args, 'a'), getImmediate('v1')))
+    .inputsValid(isEmpty(getJsonField(Args, 'a')))
+    .sections((r) => {
+      return [
+        { type: 'link', href: '/', label: 'Main' },
+        { type: 'link', href: '/subsection', label: 'Subsection' }
+      ];
+    })
+    .done();
+
+  assertType<
+    InferOutputsType<typeof platforma>,
+    {
+      cell1: ValueOrErrors<{ b: string[] }>;
+      cell2: ValueOrErrors<'v1'[]>;
+    }
+  >();
+
+  assertType<InferHrefType<typeof platforma>, '/' | '/subsection'>();
+
+  expect(JSON.stringify((platforma as any).config).length).toBeGreaterThan(20);
+});
+
+test('test config 2', () => {
+  const platforma = BlockModel.create<{ a: string[] }>('Heavy')
+    .initialArgs({ a: [] })
+    .output(
+      'cell1',
+      makeObject({
+        b: getBlobContentAsString(getResourceField(MainOutputs, 'field1')),
+        c: makeArray(getBlobContent(getResourceField(MainOutputs, 'field2')), 'asd'),
+        d: getBlobContentAsJson<string[]>()(getResourceField(MainOutputs, 'field3')),
+        e: flatten(
+          makeArray(
+            getBlobContentAsJson<string[]>()(getResourceField(MainOutputs, 'field3')),
+            getImmediate(['asd', 'd'] as string[])
+          )
+        ),
+        f: getDownloadedBlobContent(getResourceField(MainOutputs, 'field4')),
+        g: getOnDemandBlobContent(getResourceField(MainOutputs, 'field5'))
+      })
+    )
+    .output('cell2', (ctx) => 42)
+    .output('cell3', () => undefined)
+    .inputsValid(isEmpty(getJsonField(Args, 'a')))
+    .sections(
+      getImmediate([
+        { type: 'link', href: '/', label: 'Main' },
+        { type: 'link', href: '/subsection', label: 'Subsection' }
+      ])
+    )
+    .done();
+
+  assertType<
+    InferOutputsType<typeof platforma>,
+    {
+      cell1: ValueOrErrors<{
+        b: string;
+        c: [Uint8Array, 'asd'];
+        d: string[];
+        e: string[];
+        f: LocalBlobHandleAndSize;
+        g: RemoteBlobHandleAndSize;
+      }>;
+      cell2: ValueOrErrors<number>;
+      cell3: ValueOrErrors<undefined>;
+    }
+  >();
+
+  assertType<InferHrefType<typeof platforma>, '/' | '/subsection'>();
+
+  expect(JSON.stringify((platforma as any).config).length).toBeGreaterThan(20);
+});

package/src/unionize.ts

@@ -0,0 +1,12 @@
+/** Patch for the structural object */
+export type Patch<K, V> = {
+  /** Field name to patch */
+  readonly key: K;
+  /** New value for the field */
+  readonly value: V;
+};
+
+/** Creates union type of all possible shallow patches for the given structure */
+export type Unionize<T extends Record<string, unknown>> = {
+  [K in keyof T]: Patch<K, T[K]>;
+}[keyof T];

package/src/version.ts

@@ -0,0 +1 @@
+export const PlatformaSDKVersion = '1.2.22';