@milaboratories/pl-model-common 1.11.3 → 1.12.0

package/src/drivers/pframe/spec/filtered_column.ts

@@ -0,0 +1,39 @@
+import type { PValue } from '../data';
+import type { AnchoredPColumnId } from './selectors';
+
+/** Axis filter by index */
+export type AxisFilterByIdx = [number, PValue];
+
+/** Axis filter by name */
+export type AxisFilterByName = [string, PValue];
+
+/** Axis filter */
+export type AxisFilter = AxisFilterByIdx | AxisFilterByName;
+
+/**
+ * Identifies a column derived from a CanonicalPColumnId by fixing values on certain axes,
+ * thus effectively reducing the dimensionality of the original column.
+ */
+export type FilteredPColumn<CID = AnchoredPColumnId, AFI = AxisFilter> = {
+  /** The original column identifier */
+  source: CID;
+
+  /**
+   * List of fixed axes and their corresponding values.
+   * Each entry fixes one axis to a specific value, creating a slice of the multidimensional data.
+   * This effectively reduces the dimensionality by one for each fixed axis.
+   * Ordered by the axis index in canonical case.
+   */
+  axisFilters: AFI[];
+};
+
+export type FilteredPColumnId = FilteredPColumn<AnchoredPColumnId, AxisFilterByIdx>;
+
+/**
+ * Checks if a given value is a FilteredPColumn
+ * @param id - The value to check
+ * @returns True if the value is a FilteredPColumn, false otherwise
+ */
+export function isFilteredPColumn(id: unknown): id is FilteredPColumn {
+  return typeof id === 'object' && id !== null && 'source' in id && 'axisFilters' in id;
+}

package/src/drivers/pframe/spec/ids.ts

@@ -0,0 +1,31 @@
+import type { Branded } from '../../../branding';
+import type { AnchoredPColumnId } from './selectors';
+import type { FilteredPColumnId } from './filtered_column';
+import canonicalize from 'canonicalize';
+/**
+ * Universal column identifier optionally anchored and optionally filtered.
+ */
+export type UniversalPColumnId = AnchoredPColumnId | FilteredPColumnId;
+
+/**
+ * Canonically serialized {@link UniversalPColumnId}.
+ */
+export type SUniversalPColumnId = Branded<string, 'SUniversalPColumnId'>;
+
+/**
+ * Canonically serializes a {@link UniversalPColumnId} to a string.
+ * @param id - The column identifier to serialize
+ * @returns The canonically serialized string
+ */
+export function stringifyColumnId(id: UniversalPColumnId): SUniversalPColumnId {
+  return canonicalize(id)! as SUniversalPColumnId;
+}
+
+/**
+ * Parses a canonically serialized {@link UniversalPColumnId} from a string.
+ * @param str - The string to parse
+ * @returns The parsed column identifier
+ */
+export function parseColumnId(str: SUniversalPColumnId): UniversalPColumnId {
+  return JSON.parse(str) as UniversalPColumnId;
+}

package/src/drivers/pframe/spec/index.ts

@@ -1,3 +1,5 @@
-export * from './anchored_id';
+export * from './anchored';
+export * from './ids';
+export * from './filtered_column';
 export * from './spec';
 export * from './selectors';

package/src/drivers/pframe/spec/selectors.ts

@@ -1,4 +1,5 @@
 import { isPColumnSpec, type PObjectSpec } from '../../../pool';
+import type { AxisFilterByIdx, FilteredPColumn } from './filtered_column';
 import type { AxisId, PColumnSpec, ValueType } from './spec';
 import { getAxisId } from './spec';
 
@@ -88,7 +89,7 @@ export type AnchoredColumnMatchStrategy = 'expectSingle' | 'expectMultiple' | 't
  * Matcher for PColumns in an anchored context
  * Supports partial matching on axes, allowing for flexible column discovery
  */
-export interface APColumnSelector {
+export interface AnchoredPColumnSelector {
   /** Optional name of the column to match; can't be used together with namePattern */
   name?: string;
   /** Optional regexp pattern for column name matching; can't be used together with name */
@@ -115,7 +116,7 @@ export interface APColumnSelector {
 /**
  * Matcher for PColumns in a non-anchored context
  */
-export interface PColumnSelector extends APColumnSelector {
+export interface PColumnSelector extends AnchoredPColumnSelector {
   domainAnchor?: never;
   domain?: Record<string, string>;
   axes?: AxisSelector[];
@@ -125,7 +126,7 @@ export interface PColumnSelector extends APColumnSelector {
  * Strict identifier for PColumns in an anchored context
  * Unlike APColumnMatcher, this requires exact matches on domain and axes
  */
-export interface APColumnId extends APColumnSelector {
+export interface AnchoredPColumnId extends AnchoredPColumnSelector {
   /** Name is required for exact column identification */
   name: string;
   /** No namePattern in ID */

package/src/drivers/pframe/spec/spec.ts

@@ -1,4 +1,5 @@
 import type { PObject, PObjectId, PObjectSpec } from '../../../pool';
+import canonicalize from 'canonicalize';
 
 /** PFrame columns and axes within them may store one of these types. */
 export type ValueType = 'Int' | 'Long' | 'Float' | 'Double' | 'String' | 'Bytes';
@@ -151,6 +152,11 @@ export function getAxesId(spec: AxesSpec): AxesId {
   return spec.map(getAxisId);
 }
 
+/** Canonicalizes axis id */
+export function canonicalizeAxisId(id: AxisId): string {
+  return canonicalize(getAxisId(id))!;
+}
+
 /** Returns true if all domains from query are found in target */
 function matchDomain(query?: Record<string, string>, target?: Record<string, string>) {
   if (query === undefined) return target === undefined;

package/dist/drivers/pframe/spec/anchored_id.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"anchored_id.d.ts","sourceRoot":"","sources":["../../../../src/drivers/pframe/spec/anchored_id.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAU,WAAW,EAAE,MAAM,QAAQ,CAAC;AAElD,OAAO,KAAK,EAAoD,UAAU,EAAE,gBAAgB,EAAgB,eAAe,EAAE,MAAM,aAAa,CAAC;AACjJ,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAkBjD,yGAAyG;AACzG,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAEvE;;;GAGG;AACH,qBAAa,eAAe;IAiBd,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhBpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyC;IAC9D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkB;IAC9C;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA6B;IAEhE;;;OAGG;gBAC0B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC;IAwBjE;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU;IA6CrC;;;;OAIG;IACH,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG,kBAAkB;CAIvD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAqC/G"}