@milaboratories/pl-model-common 1.26.1 → 1.28.0

package/src/drivers/pspec.ts

@@ -0,0 +1,155 @@
+import type { Branded } from "@milaboratories/helpers";
+import type {
+  ValueType,
+  SingleAxisSelector,
+  AxisSpec,
+  PColumnIdAndSpec,
+  PColumnSpec,
+} from "./pframe";
+
+// --- Discover columns types (duplicated from middle-layer internal_api) ---
+
+/** Matches a string value either exactly or by regex pattern */
+export type StringMatcher = { type: "exact"; value: string } | { type: "regex"; value: string };
+
+/** Map of key to array of string matchers (OR-ed per key, AND-ed across keys) */
+export type MatcherMap = Record<string, StringMatcher[]>;
+
+/** Selector for matching axes by various criteria */
+export interface MultiAxisSelector {
+  /** Match any of the axis types listed here */
+  readonly type?: ValueType[];
+  /** Match any of the axis names listed here */
+  readonly name?: StringMatcher[];
+  /** Match requires all the domains listed here */
+  readonly domain?: MatcherMap;
+  /** Match requires all the context domains listed here */
+  readonly contextDomain?: MatcherMap;
+  /** Match requires all the annotations listed here */
+  readonly annotations?: MatcherMap;
+}
+
+/** Column selector for discover columns request, matching columns by various criteria.
+ * Multiple selectors are OR-ed: a column matches if it satisfies any selector. */
+export interface MultiColumnSelector {
+  /** Match any of the value types listed here */
+  readonly type?: ValueType[];
+  /** Match any of the names listed here */
+  readonly name?: StringMatcher[];
+  /** Match requires all the domains listed here */
+  readonly domain?: MatcherMap;
+  /** Match requires all the context domains listed here */
+  readonly contextDomain?: MatcherMap;
+  /** Match requires all the annotations listed here */
+  readonly annotations?: MatcherMap;
+  /** Match any of the axis selectors listed here */
+  readonly axes?: MultiAxisSelector[];
+  /** When true (default), allows matching if only a subset of axes match */
+  readonly partialAxesMatch?: boolean;
+}
+
+/** Qualification applied to a single axis to make it compatible during integration. */
+export interface AxisQualification {
+  /** Axis selector identifying which axis is qualified. */
+  readonly axis: SingleAxisSelector;
+  /** Additional context domain entries applied to the axis. */
+  readonly contextDomain: Record<string, string>;
+}
+
+/** Qualifications needed for both query (already-integrated) columns and the hit column. */
+export interface ColumnAxesWithQualifications {
+  /** Already integrated (query) columns with their qualifications. */
+  axesSpec: AxisSpec[];
+  /** Qualifications for each already integrated (query) column. */
+  qualifications: AxisQualification[];
+}
+
+/** Fine-grained constraints controlling axes matching and qualification behavior */
+export interface DiscoverColumnsConstraints {
+  /** Allow source (query) axes that have no match in the hit column */
+  allowFloatingSourceAxes: boolean;
+  /** Allow hit column axes that have no match in the source (query) */
+  allowFloatingHitAxes: boolean;
+  /** Allow source (query) axes to be qualified (contextDomain extended) */
+  allowSourceQualifications: boolean;
+  /** Allow hit column axes to be qualified (contextDomain extended) */
+  allowHitQualifications: boolean;
+}
+
+/** Request for discovering columns compatible with a given axes integration */
+export interface DiscoverColumnsRequest {
+  /** Column filters (OR-ed); empty array matches all columns */
+  columnFilter?: MultiColumnSelector[];
+  /** Already integrated axes with qualifications */
+  axes: ColumnAxesWithQualifications[];
+  /** Constraints controlling axes matching and qualification behavior */
+  constraints: DiscoverColumnsConstraints;
+}
+
+/** Linker step: traversal through a linker column */
+export interface DiscoverColumnsLinkerStep {
+  type: "linker";
+  /** The linker column traversed in this step */
+  linker: PColumnIdAndSpec;
+  /** Axis qualifications produced when matching the linker's many-side axes */
+  qualifications: AxisQualification[];
+}
+
+/** A step traversed during path-based column discovery. Discriminated by `type`. */
+export type DiscoverColumnsStepInfo = DiscoverColumnsLinkerStep;
+
+/** Qualifications info for a discover columns response mapping variant */
+export interface DiscoverColumnsResponseQualifications {
+  /** Qualifications for each query (already-integrated) column set */
+  forQueries: AxisQualification[][];
+  /** Qualifications for the hit column */
+  forHit: AxisQualification[];
+}
+
+/** A single mapping variant describing how a hit column can be integrated */
+export interface DiscoverColumnsMappingVariant {
+  /** Full qualifications needed for integration */
+  qualifications: DiscoverColumnsResponseQualifications;
+  /** Distinctive (minimal) qualifications needed for integration */
+  distinctiveQualifications: DiscoverColumnsResponseQualifications;
+}
+
+/** A single hit in the discover columns response */
+export interface DiscoverColumnsResponseHit {
+  /** The column that was found compatible */
+  hit: PColumnIdAndSpec;
+  /** Possible ways to integrate this column with the existing set */
+  mappingVariants: DiscoverColumnsMappingVariant[];
+}
+
+/** Response from discover columns */
+export interface DiscoverColumnsResponse {
+  /** Columns that could be integrated and possible ways to integrate them */
+  hits: DiscoverColumnsResponseHit[];
+}
+
+// --- Spec driver ---
+
+/** Handle to a spec-only PFrame (no data, synchronous operations). */
+export type SpecFrameHandle = Branded<string, "SpecFrameHandle">;
+
+/**
+ * Synchronous driver for spec-level PFrame operations.
+ *
+ * Unlike the async PFrameDriver (which works with data), this driver
+ * operates on column specifications only. All methods are synchronous
+ * because the underlying WASM PFrame computes results immediately.
+ */
+export interface PSpecDriver {
+  /** Create a spec-only PFrame from column specs. Returns a handle. */
+  createSpecFrame(specs: Record<string, PColumnSpec>): SpecFrameHandle;
+
+  /** Discover columns compatible with given axes integration. */
+  specFrameDiscoverColumns(
+    handle: SpecFrameHandle,
+    request: DiscoverColumnsRequest,
+  ): DiscoverColumnsResponse;
+
+  /** Dispose a spec frame, freeing WASM resources. */
+  disposeSpecFrame(handle: SpecFrameHandle): void;
+}

package/src/index.ts

@@ -17,3 +17,4 @@ export * from "./value_or_error";
 export * from "./base64";
 export * from "./util";
 export * from "./httpAuth";
+export * from "./resource_types";

package/src/resource_types.ts

@@ -0,0 +1,47 @@
+/** Well-known resource type names used across the platform. */
+export const ResourceTypeName = {
+  StreamManager: "StreamManager",
+  StdMap: "StdMap",
+  StdMapSlash: "std/map",
+  EphStdMap: "EphStdMap",
+  PFrame: "PFrame",
+  ParquetChunk: "ParquetChunk",
+  BContext: "BContext",
+  BlockPackCustom: "BlockPackCustom",
+  BinaryMap: "BinaryMap",
+  BinaryValue: "BinaryValue",
+  BlobMap: "BlobMap",
+  BResolveSingle: "BResolveSingle",
+  BResolveSingleNoResult: "BResolveSingleNoResult",
+  BQueryResult: "BQueryResult",
+  TengoTemplate: "TengoTemplate",
+  TengoLib: "TengoLib",
+  SoftwareInfo: "SoftwareInfo",
+  Dummy: "Dummy",
+  JsonResourceError: "json/resourceError",
+  JsonObject: "json/object",
+  JsonGzObject: "json-gz/object",
+  JsonString: "json/string",
+  JsonArray: "json/array",
+  JsonNumber: "json/number",
+  BContextEnd: "BContextEnd",
+  FrontendFromUrl: "Frontend/FromUrl",
+  FrontendFromFolder: "Frontend/FromFolder",
+  BObjectSpec: "BObjectSpec",
+  Blob: "Blob",
+  Null: "Null",
+  Binary: "binary",
+  LSProvider: "LSProvider",
+  UserProject: "UserProject",
+  Projects: "Projects",
+  ClientRoot: "ClientRoot",
+} as const;
+
+/** Resource type name prefix constants. */
+export const ResourceTypePrefix = {
+  Blob: "Blob/",
+  BlobUpload: "BlobUpload/",
+  BlobIndex: "BlobIndex/",
+  PColumnData: "PColumnData/",
+  StreamWorkdir: "StreamWorkdir/",
+} as const;