@milaboratories/pl-model-middle-layer 1.14.0 → 1.16.0

package/dist/pframe/internal_api/api_wasm.d.ts

@@ -1,68 +1,63 @@
 import { FindColumnsRequest, FindColumnsResponse } from "./find_columns.js";
 import { DeleteColumnFromColumnsRequest, DeleteColumnFromColumnsResponse } from "./delete_column.js";
-import { DiscoverColumnsRequest, DiscoverColumnsResponse } from "./discover_columns.js";
+import { DiscoverColumnsRequestV2, DiscoverColumnsResponse } from "./discover_columns.js";
 import { AxesId, AxesSpec, DataQuery, JoinEntry, PColumnSpec, PObjectId, PTableColumnId, PTableColumnSpec, PTableRecordFilter, PTableSorting, SingleAxisSelector, SpecQuery } from "@milaboratories/pl-model-common";
 
 //#region src/pframe/internal_api/api_wasm.d.ts
-interface PFrameWasmAPI {
+/**
+ * V2 PFrame interface with include/exclude column filtering in discoverColumns.
+ */
+interface PFrameWasmV2 extends Disposable {
   /**
-   * Creates a new PFrame from a map of column IDs to column specifications.
+   * Deletes columns from a columns specification.
    */
-  createPFrame(spec: Record<string, PColumnSpec>): PFrameWasm;
+  deleteColumns(request: DeleteColumnFromColumnsRequest): DeleteColumnFromColumnsResponse;
   /**
-   * Expands an {@link AxesSpec} into {@link AxesId}s with parent information
-   * resolved.
+   * Discovers columns compatible with a given axes integration,
+   * with separate include and exclude filters.
+   * Exclude filter is applied after include, removing matching columns from results.
    */
-  expandAxes(spec: AxesSpec): AxesId;
+  discoverColumns(request: DiscoverColumnsRequestV2): DiscoverColumnsResponse;
   /**
-   * Collapses {@link AxesId} into {@link AxesSpec}.
+   * Finds columns in the PFrame matching the given filter criteria.
    */
-  collapseAxes(ids: AxesId): AxesSpec;
+  findColumns(request: FindColumnsRequest): FindColumnsResponse;
   /**
-   * Finds the index of an axis matching the given selector.
-   * Returns -1 if no matching axis is found.
+   * Evaluates a query specification against this PFrame.
    */
-  findAxis(spec: AxesSpec, selector: SingleAxisSelector): number;
+  evaluateQuery(request: SpecQuery): EvaluateQueryResponse;
   /**
-   * Finds the flat index of a table column matching the given
-   * selector within a table spec. Returns -1 if not found.
+   * Rewrites a legacy query format (V4) to the current SpecQuery format.
    */
-  findTableColumn(tableSpec: PTableColumnSpec[], selector: PTableColumnId): number;
+  rewriteLegacyQuery(request: LegacyQuery): SpecQuery;
 }
 /**
- * A PFrame represents a collection of columns that can be queried and joined.
+ * V2 PFrame API factory with createPFrame returning PFrameWasmV2.
  */
-interface PFrameWasm extends Disposable {
+interface PFrameWasmAPIV2 {
   /**
-   * Deletes columns from a columns specification.
+   * Creates a new V2 PFrame from a map of column IDs to column specifications.
    */
-  deleteColumns(request: DeleteColumnFromColumnsRequest): DeleteColumnFromColumnsResponse;
+  createPFrame(spec: Record<string, PColumnSpec>): PFrameWasmV2;
   /**
-   * Discovers columns compatible with a given axes integration.
-   * Returns columns that could be integrated with the provided column set,
-   * along with possible mapping variants describing how to integrate them.
+   * Expands an {@link AxesSpec} into {@link AxesId}s with parent information
+   * resolved.
    */
-  discoverColumns(request: DiscoverColumnsRequest): DiscoverColumnsResponse;
+  expandAxes(spec: AxesSpec): AxesId;
   /**
-   * Finds columns in the PFrame matching the given filter criteria.
+   * Collapses {@link AxesId} into {@link AxesSpec}.
    */
-  findColumns(request: FindColumnsRequest): FindColumnsResponse;
+  collapseAxes(ids: AxesId): AxesSpec;
   /**
-   * Evaluates a query specification against this PFrame.
-   *
-   * Takes a SpecQuery (which can represent columns, joins, filters, sorts,
-   * etc.) and returns the resulting table specification along with the data
-   * layer query representation.
+   * Finds the index of an axis matching the given selector.
+   * Returns -1 if no matching axis is found.
    */
-  evaluateQuery(request: SpecQuery): EvaluateQueryResponse;
+  findAxis(spec: AxesSpec, selector: SingleAxisSelector): number;
   /**
-   * Rewrites a legacy query format (V4) to the current SpecQuery format.
-   *
-   * This method upgrades older query structures that use JoinEntryV4, filters,
-   * and sorting into the new unified SpecQuery format with proper filter and
-   * sort query nodes.
+   * Finds the flat index of a table column matching the given
+   * selector within a table spec. Returns -1 if not found.
    */
-  rewriteLegacyQuery(request: LegacyQuery): SpecQuery;
+  findTableColumn(tableSpec: PTableColumnSpec[], selector: PTableColumnId): number;
 }
 /**
  * Response from evaluating a query against a PFrame.
@@ -82,7 +77,7 @@ type EvaluateQueryResponse = {
 /**
  * Represents a legacy (V4) query format used before the unified SpecQuery.
  *
- * This type is used with {@link PFrameWasm.rewriteLegacyQuery} to upgrade
+ * This type is used with {@link PFrameWasmV2.rewriteLegacyQuery} to upgrade
  * older query structures to the current {@link SpecQuery} format.
  */
 type LegacyQuery = {
@@ -91,5 +86,5 @@ type LegacyQuery = {
   sorting?: PTableSorting[];
 };
 //#endregion
-export { EvaluateQueryResponse, LegacyQuery, PFrameWasm, PFrameWasmAPI };
+export { EvaluateQueryResponse, LegacyQuery, PFrameWasmAPIV2, PFrameWasmV2 };
 //# sourceMappingURL=api_wasm.d.ts.map

package/dist/pframe/internal_api/discover_columns.d.ts

@@ -1,5 +1,5 @@
 import { AxisQualification, ColumnAxesWithQualifications } from "./common.js";
-import { PColumnIdAndSpec } from "@milaboratories/pl-model-common";
+import { AxisValueType, ColumnValueType, DiscoverColumnsLinkerStep, DiscoverColumnsStepInfo, PColumnIdAndSpec } from "@milaboratories/pl-model-common";
 
 //#region src/pframe/internal_api/discover_columns.d.ts
 /** Matches a string value either exactly or by regex pattern */
@@ -15,7 +15,7 @@ type MatcherMap = Record<string, StringMatcher[]>;
 /** Selector for matching axes by various criteria */
 interface MultiAxisSelector {
   /** Match any of the axis types listed here */
-  readonly type?: string[];
+  readonly type?: AxisValueType[];
   /** Match any of the axis names listed here */
   readonly name?: StringMatcher[];
   /** Match requires all the domains listed here */
@@ -29,7 +29,7 @@ interface MultiAxisSelector {
  * Multiple selectors are OR-ed: a column matches if it satisfies any selector. */
 interface MultiColumnSelector {
   /** Match any of the value types listed here */
-  readonly type?: string[];
+  readonly type?: ColumnValueType[];
   /** Match any of the names listed here */
   readonly name?: StringMatcher[];
   /** Match requires all the domains listed here */
@@ -54,12 +54,16 @@ interface DiscoverColumnsConstraints {
   /** Allow hit column axes to be qualified (contextDomain extended) */
   allowHitQualifications: boolean;
 }
-/** Request for discovering columns compatible with a given axes integration */
-interface DiscoverColumnsRequest {
-  /** Column filters (OR-ed); empty array matches all columns */
-  columnFilter?: MultiColumnSelector[];
+/** V2 request with separate include/exclude filters */
+interface DiscoverColumnsRequestV2 {
+  /** Include columns matching these selectors (OR-ed); empty or omitted matches all columns */
+  includeColumns?: MultiColumnSelector[];
+  /** Exclude columns matching these selectors (OR-ed); applied after include filter */
+  excludeColumns?: MultiColumnSelector[];
   /** Already integrated axes with qualifications */
   axes: ColumnAxesWithQualifications[];
+  /** Maximum number of hops allowed between provided axes integration and returned hits (0 = direct only) */
+  maxHops?: number;
   /** Constraints controlling axes matching and qualification behavior */
   constraints: DiscoverColumnsConstraints;
 }
@@ -83,6 +87,8 @@ interface DiscoverColumnsResponseHit {
   hit: PColumnIdAndSpec;
   /** Possible ways to integrate this column with the existing set */
   mappingVariants: DiscoverColumnsMappingVariant[];
+  /** Linker steps traversed to reach this hit; empty for direct matches */
+  path: DiscoverColumnsStepInfo[];
 }
 /** Response from discover columns */
 interface DiscoverColumnsResponse {
@@ -90,5 +96,5 @@ interface DiscoverColumnsResponse {
   hits: DiscoverColumnsResponseHit[];
 }
 //#endregion
-export { DiscoverColumnsConstraints, DiscoverColumnsMappingVariant, DiscoverColumnsRequest, DiscoverColumnsResponse, DiscoverColumnsResponseHit, DiscoverColumnsResponseQualifications, MatcherMap, MultiAxisSelector, MultiColumnSelector, StringMatcher };
+export { DiscoverColumnsConstraints, type DiscoverColumnsLinkerStep, DiscoverColumnsMappingVariant, DiscoverColumnsRequestV2, DiscoverColumnsResponse, DiscoverColumnsResponseHit, DiscoverColumnsResponseQualifications, type DiscoverColumnsStepInfo, MatcherMap, MultiAxisSelector, MultiColumnSelector, StringMatcher };
 //# sourceMappingURL=discover_columns.d.ts.map

package/dist/pframe/internal_api/index.d.ts

@@ -6,14 +6,14 @@ import { PTableV8 } from "./table.js";
 import { PFrameReadAPIV11 } from "./api_read.js";
 import { BaseObjectStore, FileRange, FsStoreOptions, HttpAuthorizationToken, HttpHelpers, HttpMethod, HttpRange, HttpServer, HttpServerInfo, HttpServerOptions, ObjectStore, ObjectStoreOptions, ObjectStoreResponse, ObjectStoreUrl, ParquetExtension, ParquetFileName, PemCertificate, RequestHandlerOptions } from "./http_helpers.js";
 import { DataInfo, DataInfoExtension, FilePath, PFrameBlobId, PFrameDataSourceV2, PFrameFactoryAPIV4, SpecExtension } from "./api_factory.js";
-import { DiscoverColumnsConstraints, DiscoverColumnsMappingVariant, DiscoverColumnsRequest, DiscoverColumnsResponse, DiscoverColumnsResponseHit, DiscoverColumnsResponseQualifications, MatcherMap, MultiAxisSelector, MultiColumnSelector, StringMatcher } from "./discover_columns.js";
-import { EvaluateQueryResponse, LegacyQuery, PFrameWasm, PFrameWasmAPI } from "./api_wasm.js";
+import { DiscoverColumnsConstraints, DiscoverColumnsLinkerStep, DiscoverColumnsMappingVariant, DiscoverColumnsRequestV2, DiscoverColumnsResponse, DiscoverColumnsResponseHit, DiscoverColumnsResponseQualifications, DiscoverColumnsStepInfo, MatcherMap, MultiAxisSelector, MultiColumnSelector, StringMatcher } from "./discover_columns.js";
+import { EvaluateQueryResponse, LegacyQuery, PFrameWasmAPIV2, PFrameWasmV2 } from "./api_wasm.js";
 import { PFrameFactoryV4, PFrameOptionsV2, PFrameV13 } from "./pframe.js";
 import { SingleAxisSelector as SingleAxisSelector$1 } from "@milaboratories/pl-model-common";
 
 //#region src/pframe/internal_api/index.d.ts
 declare namespace index_d_exports {
-  export { ArtificialColumnJoinEntry, AxisQualification, BaseObjectStore, ColumnAxesWithQualifications, ColumnJoinEntry, ConstantAxisFilter, CreateTableRequestV4, DataInfo, DataInfoExtension, DeleteColumnFromColumnsRequest, DeleteColumnFromColumnsResponse, DiscoverColumnsConstraints, DiscoverColumnsMappingVariant, DiscoverColumnsRequest, DiscoverColumnsResponse, DiscoverColumnsResponseHit, DiscoverColumnsResponseQualifications, EvaluateQueryResponse, FilePath, FileRange, FindColumnResponseQualifications, FindColumnsMappingVariant, FindColumnsRequest, FindColumnsResponse, FindColumnsResponseHit, FsStoreOptions, FullJoinV4, HttpAuthorizationToken, HttpHelpers, HttpMethod, HttpRange, HttpServer, HttpServerInfo, HttpServerOptions, InlineColumnJoinEntry, InnerJoinV4, JoinEntryV4, LegacyQuery, Logger, MatcherMap, MultiAxisSelector, MultiColumnSelector, ObjectStore, ObjectStoreOptions, ObjectStoreResponse, ObjectStoreUrl, OuterJoinV4, PFrameBlobId, PFrameDataSourceV2, PFrameFactoryAPIV4, PFrameFactoryV4, PFrameId, PFrameOptionsV2, PFrameReadAPIV11, PFrameV13, PFrameWasm, PFrameWasmAPI, PTableId, PTableV8, ParquetExtension, ParquetFileName, PemCertificate, RequestHandlerOptions, SingleAxisSelector$1 as SingleAxisSelector, SlicedColumnJoinEntry, SpecExtension, StringMatcher };
+  export { ArtificialColumnJoinEntry, AxisQualification, BaseObjectStore, ColumnAxesWithQualifications, ColumnJoinEntry, ConstantAxisFilter, CreateTableRequestV4, DataInfo, DataInfoExtension, DeleteColumnFromColumnsRequest, DeleteColumnFromColumnsResponse, DiscoverColumnsConstraints, DiscoverColumnsLinkerStep, DiscoverColumnsMappingVariant, DiscoverColumnsRequestV2, DiscoverColumnsResponse, DiscoverColumnsResponseHit, DiscoverColumnsResponseQualifications, DiscoverColumnsStepInfo, EvaluateQueryResponse, FilePath, FileRange, FindColumnResponseQualifications, FindColumnsMappingVariant, FindColumnsRequest, FindColumnsResponse, FindColumnsResponseHit, FsStoreOptions, FullJoinV4, HttpAuthorizationToken, HttpHelpers, HttpMethod, HttpRange, HttpServer, HttpServerInfo, HttpServerOptions, InlineColumnJoinEntry, InnerJoinV4, JoinEntryV4, LegacyQuery, Logger, MatcherMap, MultiAxisSelector, MultiColumnSelector, ObjectStore, ObjectStoreOptions, ObjectStoreResponse, ObjectStoreUrl, OuterJoinV4, PFrameBlobId, PFrameDataSourceV2, PFrameFactoryAPIV4, PFrameFactoryV4, PFrameId, PFrameOptionsV2, PFrameReadAPIV11, PFrameV13, PFrameWasmAPIV2, PFrameWasmV2, PTableId, PTableV8, ParquetExtension, ParquetFileName, PemCertificate, RequestHandlerOptions, SingleAxisSelector$1 as SingleAxisSelector, SlicedColumnJoinEntry, SpecExtension, StringMatcher };
 }
 //#endregion
 export { index_d_exports };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-model-middle-layer",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Common model between middle layer and non-block UI code",
   "files": [
     "./dist/**/*",
@@ -21,13 +21,13 @@
     "utility-types": "^3.11.0",
     "zod": "~3.23.8",
     "@milaboratories/helpers": "1.14.0",
-    "@milaboratories/pl-model-common": "1.27.0"
+    "@milaboratories/pl-model-common": "1.29.0"
   },
   "devDependencies": {
     "@types/node": "~24.5.2",
     "typescript": "~5.9.3",
-    "@milaboratories/ts-configs": "1.2.2",
     "@milaboratories/build-configs": "1.5.2",
+    "@milaboratories/ts-configs": "1.2.2",
     "@milaboratories/ts-builder": "1.3.0"
   },
   "scripts": {

package/src/pframe/internal_api/api_wasm.ts

@@ -16,76 +16,72 @@ import type {
   DeleteColumnFromColumnsRequest,
   DeleteColumnFromColumnsResponse,
 } from "./delete_column";
-import type { DiscoverColumnsRequest, DiscoverColumnsResponse } from "./discover_columns";
+import type { DiscoverColumnsRequestV2, DiscoverColumnsResponse } from "./discover_columns";
 import type { FindColumnsRequest, FindColumnsResponse } from "./find_columns";
 
-export interface PFrameWasmAPI {
+/**
+ * V2 PFrame interface with include/exclude column filtering in discoverColumns.
+ */
+export interface PFrameWasmV2 extends Disposable {
   /**
-   * Creates a new PFrame from a map of column IDs to column specifications.
+   * Deletes columns from a columns specification.
    */
-  createPFrame(spec: Record<string, PColumnSpec>): PFrameWasm;
+  deleteColumns(request: DeleteColumnFromColumnsRequest): DeleteColumnFromColumnsResponse;
 
   /**
-   * Expands an {@link AxesSpec} into {@link AxesId}s with parent information
-   * resolved.
+   * Discovers columns compatible with a given axes integration,
+   * with separate include and exclude filters.
+   * Exclude filter is applied after include, removing matching columns from results.
    */
-  expandAxes(spec: AxesSpec): AxesId;
+  discoverColumns(request: DiscoverColumnsRequestV2): DiscoverColumnsResponse;
 
   /**
-   * Collapses {@link AxesId} into {@link AxesSpec}.
+   * Finds columns in the PFrame matching the given filter criteria.
    */
-  collapseAxes(ids: AxesId): AxesSpec;
+  findColumns(request: FindColumnsRequest): FindColumnsResponse;
 
   /**
-   * Finds the index of an axis matching the given selector.
-   * Returns -1 if no matching axis is found.
+   * Evaluates a query specification against this PFrame.
    */
-  findAxis(spec: AxesSpec, selector: SingleAxisSelector): number;
+  evaluateQuery(request: SpecQuery): EvaluateQueryResponse;
 
   /**
-   * Finds the flat index of a table column matching the given
-   * selector within a table spec. Returns -1 if not found.
+   * Rewrites a legacy query format (V4) to the current SpecQuery format.
    */
-  findTableColumn(tableSpec: PTableColumnSpec[], selector: PTableColumnId): number;
+  rewriteLegacyQuery(request: LegacyQuery): SpecQuery;
 }
 
 /**
- * A PFrame represents a collection of columns that can be queried and joined.
+ * V2 PFrame API factory with createPFrame returning PFrameWasmV2.
  */
-export interface PFrameWasm extends Disposable {
+export interface PFrameWasmAPIV2 {
   /**
-   * Deletes columns from a columns specification.
+   * Creates a new V2 PFrame from a map of column IDs to column specifications.
    */
-  deleteColumns(request: DeleteColumnFromColumnsRequest): DeleteColumnFromColumnsResponse;
+  createPFrame(spec: Record<string, PColumnSpec>): PFrameWasmV2;
 
   /**
-   * Discovers columns compatible with a given axes integration.
-   * Returns columns that could be integrated with the provided column set,
-   * along with possible mapping variants describing how to integrate them.
+   * Expands an {@link AxesSpec} into {@link AxesId}s with parent information
+   * resolved.
    */
-  discoverColumns(request: DiscoverColumnsRequest): DiscoverColumnsResponse;
+  expandAxes(spec: AxesSpec): AxesId;
 
   /**
-   * Finds columns in the PFrame matching the given filter criteria.
+   * Collapses {@link AxesId} into {@link AxesSpec}.
    */
-  findColumns(request: FindColumnsRequest): FindColumnsResponse;
+  collapseAxes(ids: AxesId): AxesSpec;
+
   /**
-   * Evaluates a query specification against this PFrame.
-   *
-   * Takes a SpecQuery (which can represent columns, joins, filters, sorts,
-   * etc.) and returns the resulting table specification along with the data
-   * layer query representation.
+   * Finds the index of an axis matching the given selector.
+   * Returns -1 if no matching axis is found.
    */
-  evaluateQuery(request: SpecQuery): EvaluateQueryResponse;
+  findAxis(spec: AxesSpec, selector: SingleAxisSelector): number;
 
   /**
-   * Rewrites a legacy query format (V4) to the current SpecQuery format.
-   *
-   * This method upgrades older query structures that use JoinEntryV4, filters,
-   * and sorting into the new unified SpecQuery format with proper filter and
-   * sort query nodes.
+   * Finds the flat index of a table column matching the given
+   * selector within a table spec. Returns -1 if not found.
    */
-  rewriteLegacyQuery(request: LegacyQuery): SpecQuery;
+  findTableColumn(tableSpec: PTableColumnSpec[], selector: PTableColumnId): number;
 }
 
 /**
@@ -107,7 +103,7 @@ export type EvaluateQueryResponse = {
 /**
  * Represents a legacy (V4) query format used before the unified SpecQuery.
  *
- * This type is used with {@link PFrameWasm.rewriteLegacyQuery} to upgrade
+ * This type is used with {@link PFrameWasmV2.rewriteLegacyQuery} to upgrade
  * older query structures to the current {@link SpecQuery} format.
  */
 export type LegacyQuery = {

package/src/pframe/internal_api/discover_columns.ts

@@ -1,6 +1,14 @@
-import type { PColumnIdAndSpec } from "@milaboratories/pl-model-common";
+import type {
+  AxisValueType,
+  ColumnValueType,
+  DiscoverColumnsLinkerStep,
+  DiscoverColumnsStepInfo,
+  PColumnIdAndSpec,
+} from "@milaboratories/pl-model-common";
 import type { AxisQualification, ColumnAxesWithQualifications } from "./common";
 
+export type { DiscoverColumnsLinkerStep, DiscoverColumnsStepInfo };
+
 /** Matches a string value either exactly or by regex pattern */
 export type StringMatcher = { type: "exact"; value: string } | { type: "regex"; value: string };
 
@@ -10,7 +18,7 @@ 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?: string[];
+  readonly type?: AxisValueType[];
   /** Match any of the axis names listed here */
   readonly name?: StringMatcher[];
   /** Match requires all the domains listed here */
@@ -25,7 +33,7 @@ export interface MultiAxisSelector {
  * 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?: string[];
+  readonly type?: ColumnValueType[];
   /** Match any of the names listed here */
   readonly name?: StringMatcher[];
   /** Match requires all the domains listed here */
@@ -52,12 +60,16 @@ export interface DiscoverColumnsConstraints {
   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[];
+/** V2 request with separate include/exclude filters */
+export interface DiscoverColumnsRequestV2 {
+  /** Include columns matching these selectors (OR-ed); empty or omitted matches all columns */
+  includeColumns?: MultiColumnSelector[];
+  /** Exclude columns matching these selectors (OR-ed); applied after include filter */
+  excludeColumns?: MultiColumnSelector[];
   /** Already integrated axes with qualifications */
   axes: ColumnAxesWithQualifications[];
+  /** Maximum number of hops allowed between provided axes integration and returned hits (0 = direct only) */
+  maxHops?: number;
   /** Constraints controlling axes matching and qualification behavior */
   constraints: DiscoverColumnsConstraints;
 }
@@ -84,6 +96,8 @@ export interface DiscoverColumnsResponseHit {
   hit: PColumnIdAndSpec;
   /** Possible ways to integrate this column with the existing set */
   mappingVariants: DiscoverColumnsMappingVariant[];
+  /** Linker steps traversed to reach this hit; empty for direct matches */
+  path: DiscoverColumnsStepInfo[];
 }
 
 /** Response from discover columns */