@milaboratories/pl-model-common 1.34.1 → 1.35.0

package/dist/index.cjs

@@ -99,6 +99,7 @@ exports.collectSpecQueryColumns = require_utils.collectSpecQueryColumns;
 exports.createDiscoveredPColumn = require_discovered_column.createDiscoveredPColumn;
 exports.createDiscoveredPColumnId = require_discovered_column.createDiscoveredPColumnId;
 exports.createPlRef = require_ref.createPlRef;
+exports.createPrimaryRef = require_ref.createPrimaryRef;
 exports.createUiServiceInjectors = require_service_injector_factory.createUiServiceInjectors;
 exports.dataInfoToEntries = require_data_info.dataInfoToEntries;
 exports.deriveNativeId = require_native_id.deriveNativeId;
@@ -158,6 +159,7 @@ exports.isPFrameSpecDriverError = require_errors.isPFrameSpecDriverError;
 exports.isPTableNA = require_data_types.isPTableNA;
 exports.isPartitionedDataInfoEntries = require_data_info.isPartitionedDataInfoEntries;
 exports.isPlRef = require_ref.isPlRef;
+exports.isPrimaryRef = require_ref.isPrimaryRef;
 exports.isServiceAlreadyRegisteredError = require_errors.isServiceAlreadyRegisteredError;
 exports.isServiceError = require_errors.isServiceError;
 exports.isServiceInjectionError = require_errors.isServiceInjectionError;

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { BlockSection, BlockSectionDelimiter, BlockSectionLink, BlockSectionLink
 import { CanonicalizedJson, JsonCompatible, JsonSerializable, StringifiedJson, bigintReplacer, canonicalizeJson, parseJson, stringifyJson } from "./json.js";
 import { BlockState, BlockStateV3 } from "./block_state.js";
 import { Branded } from "./branding.js";
-import { Option, PlRef, Ref, createPlRef, isPlRef, plRefsEqual, withEnrichments } from "./ref.js";
+import { DatasetInput, DatasetOption, Option, PlRef, PrimaryRef, Ref, createPlRef, createPrimaryRef, isPlRef, isPrimaryRef, plRefsEqual, withEnrichments } from "./ref.js";
 import { ResultCollection, ResultPoolEntry } from "./pool/entry.js";
 import { BlobLike, FileLike } from "./drivers/interfaces.js";
 import { ArchiveFormat, BlobToURLDriver, BlockUIURL, FolderURL, FrontendDriver, isBlockUIURL, isFolderURL } from "./drivers/urls.js";
@@ -62,4 +62,4 @@ import { Base64Compatible, Base64Encoded, base64Decode, base64Encode } from "./b
 import { assertNever, uniqueBy } from "./util.js";
 import { BasicHttpAuth, HttpAuth, parseHttpAuth, serializeHttpAuth } from "./httpAuth.js";
 import { ResourceTypeName, ResourceTypePrefix } from "./resource_types.js";
-export { AAxisSelector, ADomain, AbortError, AllRequiresFeatureFlags, AllSupportsFeatureFlags, AnchorAxisIdOrRefBasic, AnchorAxisRef, AnchorAxisRefByIdx, AnchorAxisRefByMatcher, AnchorAxisRefByName, AnchorDomainRef, AnchoredColumnMatchStrategy, AnchoredIdDeriver, AnchoredPColumnId, AnchoredPColumnSelector, Annotation, AnnotationJson, AnyFunction, AnyLogHandle, ArchiveFormat, ArrayTypeUnion, ArtificialColumnJoinEntry, Assert, AssertKeysEqual, AuthorMarker, AxesId, AxesSpec, AxisFilter, AxisFilterByIdx, AxisFilterByName, AxisFilterValue, AxisId, AxisQualification, AxisSpec, AxisSpecNormalized, AxisTree, AxisValueType, Base64Compatible, Base64Encoded, BasicHttpAuth, BinaryChunk, BinaryPartitionedDataInfo, BinaryPartitionedDataInfoEntries, BlobDriver, BlobHandleAndSize, BlobLike, BlobToURLDriver, BlockCodeFeatureFlags, BlockCodeKnownFeatureFlags, BlockCodeWithInfo, BlockConfigContainer, BlockConfigGeneric, BlockConfigV3Generic, BlockConfigV4Generic, BlockOutputsBase, BlockRenderingMode, BlockSection, BlockSectionDelimiter, BlockSectionLink, BlockSectionLinkAppearance, BlockState, BlockStateV3, BlockUIURL, Branded, BuildQueryInput, CalculateTableDataRequest, CalculateTableDataResponse, CanonicalizedJson, ChunkedStreamReader, ChunkedStreamReaderOptions, Code, ColumnAxesWithQualifications, ColumnFilter, ColumnJoinEntry, ColumnValueType, CompositeLinkerMap, ConstantAxisFilter, ContentHandler, DataExprAxisRef, DataExprColumnRef, DataInfo, DataInfoEntries, DataQuery, DataQueryBooleanExpression, DataQueryColumn, DataQueryExpression, DataQueryFilter, DataQueryInlineColumn, DataQueryJoinEntry, DataQueryLinkerJoin, DataQueryLinkerJoinLinker, DataQueryOuterJoin, DataQuerySliceAxes, DataQuerySort, DataQuerySparseToDenseColumn, DataQuerySymmetricJoin, DefaultNavigationState, DeleteColumnRequest, DeleteColumnResponse, DiscoverColumnsConstraints, DiscoverColumnsFilterStep, DiscoverColumnsLinkerStep, DiscoverColumnsMappingVariant, DiscoverColumnsRequest, DiscoverColumnsResponse, DiscoverColumnsResponseHit, DiscoverColumnsResponseQualifications, DiscoverColumnsStepInfo, DiscoveredPColumn, DiscoveredPColumnId, Domain, DomainJson, DriverKit, ErrorHandlerStatus, EvaluateQueryResponse, FileLike, FileRange, FilterKeysByPrefix, FilterSpec, FilterSpecLeaf, FilterSpecNode, FilterSpecOfType, FilterSpecType, FilteredPColumn, FilteredPColumnId, FindColumnsRequest, FindColumnsResponse, FolderURL, FrontendDriver, FullJoin, FullPTableColumnData, GetContentOptions, HttpAuth, ImportFileHandle, ImportFileHandleIndex, ImportFileHandleUpload, ImportProgress, ImportStatus, IncompatibleFlagsError, InferFilterSpecCommonLeaf, InferFilterSpecCommonNode, InferFilterSpecLeaf, InferFilterSpecLeafColumn, InferServiceKind, InferServiceModel, InferServiceUi, InlineColumnJoinEntry, InnerJoin, Is, IsSubtypeOf, JoinEntry, JsonCompatible, JsonDataInfo, JsonDataInfoEntries, JsonPartitionedDataInfo, JsonPartitionedDataInfoEntries, JsonSerializable, KnownServiceName, LegacyAxisSelector, LinkerMap, ListFilesResult, ListOptionBase, LiveLogHandle, LocalBlobHandle, LocalBlobHandleAndSize, LocalImportFileHandle, LogsDriver, LsDriver, LsEntry, MatcherMap, Metadata, MetadataJson, ModelServiceFactoryMap, ModelServiceRegistry, ModelServices, MultiAxisSelector, MultiColumnSelector, NativePObjectId, NavigationState, OpenDialogFilter, OpenDialogOps, OpenMultipleFilesResponse, OpenSingleFileResponse, Option, OuterJoin, OutputWithStatus, PAxisName, PColumn, PColumnDataEntry, PColumnIdAndSpec, PColumnInfo, PColumnKey, PColumnLazy, PColumnName, PColumnSelector, PColumnSpec, PColumnSpecId, PColumnValue, PColumnValues, PColumnValuesEntry, PDataColumnSpec, PFrame, PFrameDef, PFrameDriver, PFrameDriverError, PFrameError, PFrameHandle, PFrameModelDriver, PFrameSpecDriver, PFrameSpecDriverError, PObject, PObjectId, PObjectSpec, PSpecPredicate, PTable, PTableColumnId, PTableColumnIdAxis, PTableColumnIdColumn, PTableColumnSpec, PTableColumnSpecAxis, PTableColumnSpecColumn, PTableDef, PTableDefV2, PTableHandle, PTableNA, PTableRecordFilter, PTableRecordSingleValueFilterV2, PTableShape, PTableSorting, PTableValue, PTableValueAxis, PTableValueBranded, PTableValueData, PTableValueDataBranded, PTableValueDouble, PTableValueFloat, PTableValueInt, PTableValueLong, PTableValueString, PTableVector, PTableVectorTyped, PUniversalColumnSpec, PVectorData, PVectorDataBytes, PVectorDataDouble, PVectorDataFloat, PVectorDataInt, PVectorDataLong, PVectorDataString, PVectorDataTyped, ParquetChunk, ParquetChunkMapping, ParquetChunkMappingAxis, ParquetChunkMappingColumn, ParquetChunkMetadata, ParquetChunkStats, ParquetPartitionedDataInfo, ParquetPartitionedDataInfoEntries, PartitionedDataInfoEntries, PlId, PlIdBytes, PlIdLength, PlRef, PoolEntry, PoolEntryGuard, ProgressLogWithInfo, RangeBytes, ReadyLogHandle, Ref, RemoteBlobHandle, RemoteBlobHandleAndSize, RequireServices, ResolveAnchorsOptions, ResourceTypeName, ResourceTypePrefix, ResultCollection, ResultOrError, ResultPoolEntry, RootFilterSpec, RuntimeCapabilities, SERVICE_CAPABILITY_FLAGS, SERVICE_FEATURE_FLAGS, SERVICE_METHOD_MAP, SUniversalPColumnId, SerializedError, ServiceAlreadyRegisteredError, ServiceBrand, ServiceDispatch, ServiceError, ServiceInjectionError, ServiceInvalidIdError, ServiceMethodNotFoundError, ServiceName, ServiceNameLiterals, ServiceNotRegisteredError, ServiceRequireFlags, ServiceType, ServiceTypesLike, Services, SingleAxisSelector, SingleValueAndPredicateV2, SingleValueEqualPredicate, SingleValueGreaterOrEqualPredicate, SingleValueGreaterPredicate, SingleValueIEqualPredicate, SingleValueInSetPredicate, SingleValueIsNAPredicate, SingleValueLessOrEqualPredicate, SingleValueLessPredicate, SingleValueMatchesPredicate, SingleValueNotPredicateV2, SingleValueOrPredicateV2, SingleValuePredicateV2, SingleValueStringContainsFuzzyPredicate, SingleValueStringContainsPredicate, SingleValueStringIContainsFuzzyPredicate, SingleValueStringIContainsPredicate, SlicedColumnJoinEntry, SpecExprAxisRef, SpecExprColumnRef, SpecFrameHandle, SpecQuery, SpecQueryBooleanExpression, SpecQueryColumn, SpecQueryExpression, SpecQueryFilter, SpecQueryInlineColumn, SpecQueryJoinEntry, SpecQueryLinkerJoin, SpecQueryLinkerJoinLinker, SpecQueryOuterJoin, SpecQuerySliceAxes, SpecQuerySort, SpecQuerySparseToDenseColumn, SpecQuerySymmetricJoin, StorageEntry, StorageHandle, StorageHandleLocal, StorageHandleRemote, StreamingApiResponse, StreamingApiResponseHandleOutdated, StreamingApiResponseOk, StringMatcher, StringifiedJson, SupportedRequirement, TableRange, Trace, TraceEntry, UiError, UiServiceFactoryMap, UiServiceInjectorMap, UiServiceRegistry, UiServices, UniqueValuesRequest, UniqueValuesResponse, UniversalPColumnId, ValueOrError, ValueType, ValueTypeSupported, ValueWithUTag, ValueWithUTagAndAuthor, assertNever, base64Decode, base64Encode, bigintReplacer, buildServiceInfo, canonicalizeAxisId, canonicalizeAxisWithParents, canonicalizeJson, checkBlockFlag, collectSpecQueryColumns, createDiscoveredPColumn, createDiscoveredPColumnId, createPlRef, createUiServiceInjectors, dataInfoToEntries, deriveNativeId, deserializeError, deserializeResult, digestPlId, ensureError, ensurePColumn, entriesToDataInfo, executePSpecPredicate, extractAllColumns, extractAllRequirements, extractAllSupports, extractCodeWithInfo, extractConfigGeneric, getArrayFromAxisTree, getAxesId, getAxesTree, getAxisId, getColumnIdAndSpec, getDenormalizedAxesList, getFileNameFromHandle, getFilePathFromHandle, getMethodNames, getNormalizedAxesList, getPColumnSpecId, getPTableColumnId, getSetFromAxisTree, getTypeFromPColumnOrAxisSpec, hasAbortError, isAbortError, isAggregateError, isAnchoredPColumnId, isAnyLogHandle, isAxisId, isBlockUIURL, isBooleanExpression, isDataInfo, isDataInfoEntries, isDiscoveredPColumn, isFilteredPColumn, isFolderURL, isImportFileHandleIndex, isImportFileHandleUpload, isKnownServiceName, isLabelColumn, isLinkerColumn, isLiveLog, isNodeService, isPColumn, isPColumnResult, isPColumnSpec, isPColumnSpecResult, isPFrameDriverError, isPFrameError, isPFrameSpecDriverError, isPTableNA, isPartitionedDataInfoEntries, isPlRef, isServiceAlreadyRegisteredError, isServiceError, isServiceInjectionError, isServiceInvalidIdError, isServiceMethodNotFoundError, isServiceNotRegisteredError, legacyColumnSelectorsToPredicate, mapDataInfo, mapDataInfoEntries, mapJoinEntry, mapPObjectData, mapPTableDef, mapPTableDefV2, mapSpecQueryColumns, mapValueInVOE, matchAxis, matchAxisId, matchPColumn, newRangeBytesOpt, pTableValue, pTableValueBranded, parseColumnId, parseDiscoveredPColumnId, parseHttpAuth, parseJson, plId, plRefsEqual, readAnnotation, readAnnotationJson, readAnnotationJsonOrThrow, readDomain, readDomainJson, readDomainJsonOrThrow, readMetadata, readMetadataJson, readMetadataJsonOrThrow, registerServiceCapabilities, resolveAnchors, resolveAnnotationParents, resolveRequiredServices, resolveUiInjector, serializeError, serializeHttpAuth, serializeResult, service, serviceFnKey, sortJoinEntry, sortPTableDef, sortSpecQuery, stringifyColumnId, stringifyDiscoveredPColumnId, stringifyJson, traverseQuerySpec, uniqueBy, uniquePlId, unwrapResult, validateRangeBytes, visitDataInfo, withEnrichments, wrapAndSerialize, wrapAndSerializeAsync, wrapAsyncCallback, wrapCallback };
+export { AAxisSelector, ADomain, AbortError, AllRequiresFeatureFlags, AllSupportsFeatureFlags, AnchorAxisIdOrRefBasic, AnchorAxisRef, AnchorAxisRefByIdx, AnchorAxisRefByMatcher, AnchorAxisRefByName, AnchorDomainRef, AnchoredColumnMatchStrategy, AnchoredIdDeriver, AnchoredPColumnId, AnchoredPColumnSelector, Annotation, AnnotationJson, AnyFunction, AnyLogHandle, ArchiveFormat, ArrayTypeUnion, ArtificialColumnJoinEntry, Assert, AssertKeysEqual, AuthorMarker, AxesId, AxesSpec, AxisFilter, AxisFilterByIdx, AxisFilterByName, AxisFilterValue, AxisId, AxisQualification, AxisSpec, AxisSpecNormalized, AxisTree, AxisValueType, Base64Compatible, Base64Encoded, BasicHttpAuth, BinaryChunk, BinaryPartitionedDataInfo, BinaryPartitionedDataInfoEntries, BlobDriver, BlobHandleAndSize, BlobLike, BlobToURLDriver, BlockCodeFeatureFlags, BlockCodeKnownFeatureFlags, BlockCodeWithInfo, BlockConfigContainer, BlockConfigGeneric, BlockConfigV3Generic, BlockConfigV4Generic, BlockOutputsBase, BlockRenderingMode, BlockSection, BlockSectionDelimiter, BlockSectionLink, BlockSectionLinkAppearance, BlockState, BlockStateV3, BlockUIURL, Branded, BuildQueryInput, CalculateTableDataRequest, CalculateTableDataResponse, CanonicalizedJson, ChunkedStreamReader, ChunkedStreamReaderOptions, Code, ColumnAxesWithQualifications, ColumnFilter, ColumnJoinEntry, ColumnValueType, CompositeLinkerMap, ConstantAxisFilter, ContentHandler, DataExprAxisRef, DataExprColumnRef, DataInfo, DataInfoEntries, DataQuery, DataQueryBooleanExpression, DataQueryColumn, DataQueryExpression, DataQueryFilter, DataQueryInlineColumn, DataQueryJoinEntry, DataQueryLinkerJoin, DataQueryLinkerJoinLinker, DataQueryOuterJoin, DataQuerySliceAxes, DataQuerySort, DataQuerySparseToDenseColumn, DataQuerySymmetricJoin, DatasetInput, DatasetOption, DefaultNavigationState, DeleteColumnRequest, DeleteColumnResponse, DiscoverColumnsConstraints, DiscoverColumnsFilterStep, DiscoverColumnsLinkerStep, DiscoverColumnsMappingVariant, DiscoverColumnsRequest, DiscoverColumnsResponse, DiscoverColumnsResponseHit, DiscoverColumnsResponseQualifications, DiscoverColumnsStepInfo, DiscoveredPColumn, DiscoveredPColumnId, Domain, DomainJson, DriverKit, ErrorHandlerStatus, EvaluateQueryResponse, FileLike, FileRange, FilterKeysByPrefix, FilterSpec, FilterSpecLeaf, FilterSpecNode, FilterSpecOfType, FilterSpecType, FilteredPColumn, FilteredPColumnId, FindColumnsRequest, FindColumnsResponse, FolderURL, FrontendDriver, FullJoin, FullPTableColumnData, GetContentOptions, HttpAuth, ImportFileHandle, ImportFileHandleIndex, ImportFileHandleUpload, ImportProgress, ImportStatus, IncompatibleFlagsError, InferFilterSpecCommonLeaf, InferFilterSpecCommonNode, InferFilterSpecLeaf, InferFilterSpecLeafColumn, InferServiceKind, InferServiceModel, InferServiceUi, InlineColumnJoinEntry, InnerJoin, Is, IsSubtypeOf, JoinEntry, JsonCompatible, JsonDataInfo, JsonDataInfoEntries, JsonPartitionedDataInfo, JsonPartitionedDataInfoEntries, JsonSerializable, KnownServiceName, LegacyAxisSelector, LinkerMap, ListFilesResult, ListOptionBase, LiveLogHandle, LocalBlobHandle, LocalBlobHandleAndSize, LocalImportFileHandle, LogsDriver, LsDriver, LsEntry, MatcherMap, Metadata, MetadataJson, ModelServiceFactoryMap, ModelServiceRegistry, ModelServices, MultiAxisSelector, MultiColumnSelector, NativePObjectId, NavigationState, OpenDialogFilter, OpenDialogOps, OpenMultipleFilesResponse, OpenSingleFileResponse, Option, OuterJoin, OutputWithStatus, PAxisName, PColumn, PColumnDataEntry, PColumnIdAndSpec, PColumnInfo, PColumnKey, PColumnLazy, PColumnName, PColumnSelector, PColumnSpec, PColumnSpecId, PColumnValue, PColumnValues, PColumnValuesEntry, PDataColumnSpec, PFrame, PFrameDef, PFrameDriver, PFrameDriverError, PFrameError, PFrameHandle, PFrameModelDriver, PFrameSpecDriver, PFrameSpecDriverError, PObject, PObjectId, PObjectSpec, PSpecPredicate, PTable, PTableColumnId, PTableColumnIdAxis, PTableColumnIdColumn, PTableColumnSpec, PTableColumnSpecAxis, PTableColumnSpecColumn, PTableDef, PTableDefV2, PTableHandle, PTableNA, PTableRecordFilter, PTableRecordSingleValueFilterV2, PTableShape, PTableSorting, PTableValue, PTableValueAxis, PTableValueBranded, PTableValueData, PTableValueDataBranded, PTableValueDouble, PTableValueFloat, PTableValueInt, PTableValueLong, PTableValueString, PTableVector, PTableVectorTyped, PUniversalColumnSpec, PVectorData, PVectorDataBytes, PVectorDataDouble, PVectorDataFloat, PVectorDataInt, PVectorDataLong, PVectorDataString, PVectorDataTyped, ParquetChunk, ParquetChunkMapping, ParquetChunkMappingAxis, ParquetChunkMappingColumn, ParquetChunkMetadata, ParquetChunkStats, ParquetPartitionedDataInfo, ParquetPartitionedDataInfoEntries, PartitionedDataInfoEntries, PlId, PlIdBytes, PlIdLength, PlRef, PoolEntry, PoolEntryGuard, PrimaryRef, ProgressLogWithInfo, RangeBytes, ReadyLogHandle, Ref, RemoteBlobHandle, RemoteBlobHandleAndSize, RequireServices, ResolveAnchorsOptions, ResourceTypeName, ResourceTypePrefix, ResultCollection, ResultOrError, ResultPoolEntry, RootFilterSpec, RuntimeCapabilities, SERVICE_CAPABILITY_FLAGS, SERVICE_FEATURE_FLAGS, SERVICE_METHOD_MAP, SUniversalPColumnId, SerializedError, ServiceAlreadyRegisteredError, ServiceBrand, ServiceDispatch, ServiceError, ServiceInjectionError, ServiceInvalidIdError, ServiceMethodNotFoundError, ServiceName, ServiceNameLiterals, ServiceNotRegisteredError, ServiceRequireFlags, ServiceType, ServiceTypesLike, Services, SingleAxisSelector, SingleValueAndPredicateV2, SingleValueEqualPredicate, SingleValueGreaterOrEqualPredicate, SingleValueGreaterPredicate, SingleValueIEqualPredicate, SingleValueInSetPredicate, SingleValueIsNAPredicate, SingleValueLessOrEqualPredicate, SingleValueLessPredicate, SingleValueMatchesPredicate, SingleValueNotPredicateV2, SingleValueOrPredicateV2, SingleValuePredicateV2, SingleValueStringContainsFuzzyPredicate, SingleValueStringContainsPredicate, SingleValueStringIContainsFuzzyPredicate, SingleValueStringIContainsPredicate, SlicedColumnJoinEntry, SpecExprAxisRef, SpecExprColumnRef, SpecFrameHandle, SpecQuery, SpecQueryBooleanExpression, SpecQueryColumn, SpecQueryExpression, SpecQueryFilter, SpecQueryInlineColumn, SpecQueryJoinEntry, SpecQueryLinkerJoin, SpecQueryLinkerJoinLinker, SpecQueryOuterJoin, SpecQuerySliceAxes, SpecQuerySort, SpecQuerySparseToDenseColumn, SpecQuerySymmetricJoin, StorageEntry, StorageHandle, StorageHandleLocal, StorageHandleRemote, StreamingApiResponse, StreamingApiResponseHandleOutdated, StreamingApiResponseOk, StringMatcher, StringifiedJson, SupportedRequirement, TableRange, Trace, TraceEntry, UiError, UiServiceFactoryMap, UiServiceInjectorMap, UiServiceRegistry, UiServices, UniqueValuesRequest, UniqueValuesResponse, UniversalPColumnId, ValueOrError, ValueType, ValueTypeSupported, ValueWithUTag, ValueWithUTagAndAuthor, assertNever, base64Decode, base64Encode, bigintReplacer, buildServiceInfo, canonicalizeAxisId, canonicalizeAxisWithParents, canonicalizeJson, checkBlockFlag, collectSpecQueryColumns, createDiscoveredPColumn, createDiscoveredPColumnId, createPlRef, createPrimaryRef, createUiServiceInjectors, dataInfoToEntries, deriveNativeId, deserializeError, deserializeResult, digestPlId, ensureError, ensurePColumn, entriesToDataInfo, executePSpecPredicate, extractAllColumns, extractAllRequirements, extractAllSupports, extractCodeWithInfo, extractConfigGeneric, getArrayFromAxisTree, getAxesId, getAxesTree, getAxisId, getColumnIdAndSpec, getDenormalizedAxesList, getFileNameFromHandle, getFilePathFromHandle, getMethodNames, getNormalizedAxesList, getPColumnSpecId, getPTableColumnId, getSetFromAxisTree, getTypeFromPColumnOrAxisSpec, hasAbortError, isAbortError, isAggregateError, isAnchoredPColumnId, isAnyLogHandle, isAxisId, isBlockUIURL, isBooleanExpression, isDataInfo, isDataInfoEntries, isDiscoveredPColumn, isFilteredPColumn, isFolderURL, isImportFileHandleIndex, isImportFileHandleUpload, isKnownServiceName, isLabelColumn, isLinkerColumn, isLiveLog, isNodeService, isPColumn, isPColumnResult, isPColumnSpec, isPColumnSpecResult, isPFrameDriverError, isPFrameError, isPFrameSpecDriverError, isPTableNA, isPartitionedDataInfoEntries, isPlRef, isPrimaryRef, isServiceAlreadyRegisteredError, isServiceError, isServiceInjectionError, isServiceInvalidIdError, isServiceMethodNotFoundError, isServiceNotRegisteredError, legacyColumnSelectorsToPredicate, mapDataInfo, mapDataInfoEntries, mapJoinEntry, mapPObjectData, mapPTableDef, mapPTableDefV2, mapSpecQueryColumns, mapValueInVOE, matchAxis, matchAxisId, matchPColumn, newRangeBytesOpt, pTableValue, pTableValueBranded, parseColumnId, parseDiscoveredPColumnId, parseHttpAuth, parseJson, plId, plRefsEqual, readAnnotation, readAnnotationJson, readAnnotationJsonOrThrow, readDomain, readDomainJson, readDomainJsonOrThrow, readMetadata, readMetadataJson, readMetadataJsonOrThrow, registerServiceCapabilities, resolveAnchors, resolveAnnotationParents, resolveRequiredServices, resolveUiInjector, serializeError, serializeHttpAuth, serializeResult, service, serviceFnKey, sortJoinEntry, sortPTableDef, sortSpecQuery, stringifyColumnId, stringifyDiscoveredPColumnId, stringifyJson, traverseQuerySpec, uniqueBy, uniquePlId, unwrapResult, validateRangeBytes, visitDataInfo, withEnrichments, wrapAndSerialize, wrapAndSerializeAsync, wrapAsyncCallback, wrapCallback };

package/dist/index.js

@@ -30,7 +30,7 @@ import { AllRequiresFeatureFlags, AllSupportsFeatureFlags } from "./flags/block_
 import { IncompatibleFlagsError, RuntimeCapabilities, checkBlockFlag, extractAllRequirements, extractAllSupports } from "./flags/flag_utils.js";
 import { DefaultNavigationState } from "./navigation.js";
 import { PlId, PlIdBytes, PlIdLength, digestPlId, plId, uniquePlId } from "./plid.js";
-import { PlRef, createPlRef, isPlRef, plRefsEqual, withEnrichments } from "./ref.js";
+import { PlRef, createPlRef, createPrimaryRef, isPlRef, isPrimaryRef, plRefsEqual, withEnrichments } from "./ref.js";
 import { mapValueInVOE } from "./value_or_error.js";
 import { base64Decode, base64Encode } from "./base64.js";
 import { parseHttpAuth, serializeHttpAuth } from "./httpAuth.js";
@@ -43,4 +43,4 @@ import { createUiServiceInjectors } from "./services/service_injector_factory.js
 import { SERVICE_METHOD_MAP, buildServiceInfo, resolveUiInjector } from "./services/service_injectors.js";
 import "./services/index.js";
 import { PoolEntryGuard } from "./pool_entry.js";
-export { AbortError, AllRequiresFeatureFlags, AllSupportsFeatureFlags, AnchoredIdDeriver, Annotation, AnnotationJson, ChunkedStreamReader, Code, DefaultNavigationState, Domain, DomainJson, IncompatibleFlagsError, LinkerMap, ModelServiceRegistry, PAxisName, PColumnName, PFrameDriverError, PFrameError, PFrameSpecDriverError, PTableNA, PlId, PlIdBytes, PlIdLength, PlRef, PoolEntryGuard, RangeBytes, ResourceTypeName, ResourceTypePrefix, RuntimeCapabilities, SERVICE_CAPABILITY_FLAGS, SERVICE_FEATURE_FLAGS, SERVICE_METHOD_MAP, ServiceAlreadyRegisteredError, ServiceError, ServiceInjectionError, ServiceInvalidIdError, ServiceMethodNotFoundError, ServiceNotRegisteredError, Services, UiError, UiServiceRegistry, ValueType, assertNever, base64Decode, base64Encode, bigintReplacer, buildServiceInfo, canonicalizeAxisId, canonicalizeAxisWithParents, canonicalizeJson, checkBlockFlag, collectSpecQueryColumns, createDiscoveredPColumn, createDiscoveredPColumnId, createPlRef, createUiServiceInjectors, dataInfoToEntries, deriveNativeId, deserializeError, deserializeResult, digestPlId, ensureError, ensurePColumn, entriesToDataInfo, executePSpecPredicate, extractAllColumns, extractAllRequirements, extractAllSupports, extractCodeWithInfo, extractConfigGeneric, getArrayFromAxisTree, getAxesId, getAxesTree, getAxisId, getColumnIdAndSpec, getDenormalizedAxesList, getFileNameFromHandle, getFilePathFromHandle, getMethodNames, getNormalizedAxesList, getPColumnSpecId, getPTableColumnId, getSetFromAxisTree, getTypeFromPColumnOrAxisSpec, hasAbortError, isAbortError, isAggregateError, isAnchoredPColumnId, isAnyLogHandle, isAxisId, isBlockUIURL, isBooleanExpression, isDataInfo, isDataInfoEntries, isDiscoveredPColumn, isFilteredPColumn, isFolderURL, isImportFileHandleIndex, isImportFileHandleUpload, isKnownServiceName, isLabelColumn, isLinkerColumn, isLiveLog, isNodeService, isPColumn, isPColumnResult, isPColumnSpec, isPColumnSpecResult, isPFrameDriverError, isPFrameError, isPFrameSpecDriverError, isPTableNA, isPartitionedDataInfoEntries, isPlRef, isServiceAlreadyRegisteredError, isServiceError, isServiceInjectionError, isServiceInvalidIdError, isServiceMethodNotFoundError, isServiceNotRegisteredError, legacyColumnSelectorsToPredicate, mapDataInfo, mapDataInfoEntries, mapJoinEntry, mapPObjectData, mapPTableDef, mapPTableDefV2, mapSpecQueryColumns, mapValueInVOE, matchAxis, matchAxisId, matchPColumn, newRangeBytesOpt, pTableValue, pTableValueBranded, parseColumnId, parseDiscoveredPColumnId, parseHttpAuth, parseJson, plId, plRefsEqual, readAnnotation, readAnnotationJson, readAnnotationJsonOrThrow, readDomain, readDomainJson, readDomainJsonOrThrow, readMetadata, readMetadataJson, readMetadataJsonOrThrow, registerServiceCapabilities, resolveAnchors, resolveAnnotationParents, resolveRequiredServices, resolveUiInjector, serializeError, serializeHttpAuth, serializeResult, service, serviceFnKey, sortJoinEntry, sortPTableDef, sortSpecQuery, stringifyColumnId, stringifyDiscoveredPColumnId, stringifyJson, traverseQuerySpec, uniqueBy, uniquePlId, unwrapResult, validateRangeBytes, visitDataInfo, withEnrichments, wrapAndSerialize, wrapAndSerializeAsync, wrapAsyncCallback, wrapCallback };
+export { AbortError, AllRequiresFeatureFlags, AllSupportsFeatureFlags, AnchoredIdDeriver, Annotation, AnnotationJson, ChunkedStreamReader, Code, DefaultNavigationState, Domain, DomainJson, IncompatibleFlagsError, LinkerMap, ModelServiceRegistry, PAxisName, PColumnName, PFrameDriverError, PFrameError, PFrameSpecDriverError, PTableNA, PlId, PlIdBytes, PlIdLength, PlRef, PoolEntryGuard, RangeBytes, ResourceTypeName, ResourceTypePrefix, RuntimeCapabilities, SERVICE_CAPABILITY_FLAGS, SERVICE_FEATURE_FLAGS, SERVICE_METHOD_MAP, ServiceAlreadyRegisteredError, ServiceError, ServiceInjectionError, ServiceInvalidIdError, ServiceMethodNotFoundError, ServiceNotRegisteredError, Services, UiError, UiServiceRegistry, ValueType, assertNever, base64Decode, base64Encode, bigintReplacer, buildServiceInfo, canonicalizeAxisId, canonicalizeAxisWithParents, canonicalizeJson, checkBlockFlag, collectSpecQueryColumns, createDiscoveredPColumn, createDiscoveredPColumnId, createPlRef, createPrimaryRef, createUiServiceInjectors, dataInfoToEntries, deriveNativeId, deserializeError, deserializeResult, digestPlId, ensureError, ensurePColumn, entriesToDataInfo, executePSpecPredicate, extractAllColumns, extractAllRequirements, extractAllSupports, extractCodeWithInfo, extractConfigGeneric, getArrayFromAxisTree, getAxesId, getAxesTree, getAxisId, getColumnIdAndSpec, getDenormalizedAxesList, getFileNameFromHandle, getFilePathFromHandle, getMethodNames, getNormalizedAxesList, getPColumnSpecId, getPTableColumnId, getSetFromAxisTree, getTypeFromPColumnOrAxisSpec, hasAbortError, isAbortError, isAggregateError, isAnchoredPColumnId, isAnyLogHandle, isAxisId, isBlockUIURL, isBooleanExpression, isDataInfo, isDataInfoEntries, isDiscoveredPColumn, isFilteredPColumn, isFolderURL, isImportFileHandleIndex, isImportFileHandleUpload, isKnownServiceName, isLabelColumn, isLinkerColumn, isLiveLog, isNodeService, isPColumn, isPColumnResult, isPColumnSpec, isPColumnSpecResult, isPFrameDriverError, isPFrameError, isPFrameSpecDriverError, isPTableNA, isPartitionedDataInfoEntries, isPlRef, isPrimaryRef, isServiceAlreadyRegisteredError, isServiceError, isServiceInjectionError, isServiceInvalidIdError, isServiceMethodNotFoundError, isServiceNotRegisteredError, legacyColumnSelectorsToPredicate, mapDataInfo, mapDataInfoEntries, mapJoinEntry, mapPObjectData, mapPTableDef, mapPTableDefV2, mapSpecQueryColumns, mapValueInVOE, matchAxis, matchAxisId, matchPColumn, newRangeBytesOpt, pTableValue, pTableValueBranded, parseColumnId, parseDiscoveredPColumnId, parseHttpAuth, parseJson, plId, plRefsEqual, readAnnotation, readAnnotationJson, readAnnotationJsonOrThrow, readDomain, readDomainJson, readDomainJsonOrThrow, readMetadata, readMetadataJson, readMetadataJsonOrThrow, registerServiceCapabilities, resolveAnchors, resolveAnnotationParents, resolveRequiredServices, resolveUiInjector, serializeError, serializeHttpAuth, serializeResult, service, serviceFnKey, sortJoinEntry, sortPTableDef, sortSpecQuery, stringifyColumnId, stringifyDiscoveredPColumnId, stringifyJson, traverseQuerySpec, uniqueBy, uniquePlId, unwrapResult, validateRangeBytes, visitDataInfo, withEnrichments, wrapAndSerialize, wrapAndSerializeAsync, wrapAsyncCallback, wrapCallback };

package/dist/ref.cjs

@@ -55,6 +55,20 @@ function withEnrichments(ref, requireEnrichments = true) {
 		return rest;
 	}
 }
+function isPrimaryRef(value) {
+	return typeof value === "object" && value !== null && value.__isPrimaryRef === "v1" && "column" in value;
+}
+function createPrimaryRef(column, filter) {
+	if (filter !== void 0) return {
+		__isPrimaryRef: "v1",
+		column,
+		filter
+	};
+	else return {
+		__isPrimaryRef: "v1",
+		column
+	};
+}
 /** Compare two PlRefs and returns true if they are qual */
 function plRefsEqual(ref1, ref2, ignoreEnrichments = false) {
 	return ref1.blockId === ref2.blockId && ref1.name === ref2.name && (ignoreEnrichments || ref1.requireEnrichments === ref2.requireEnrichments);
@@ -62,7 +76,9 @@ function plRefsEqual(ref1, ref2, ignoreEnrichments = false) {
 //#endregion
 exports.PlRef = PlRef;
 exports.createPlRef = createPlRef;
+exports.createPrimaryRef = createPrimaryRef;
 exports.isPlRef = isPlRef;
+exports.isPrimaryRef = isPrimaryRef;
 exports.plRefsEqual = plRefsEqual;
 exports.withEnrichments = withEnrichments;
 

package/dist/ref.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"ref.cjs","names":["z"],"sources":["../src/ref.ts"],"sourcesContent":["import { z } from \"zod\";\n\nexport const PlRef = z\n  .object({\n    __isRef: z\n      .literal(true)\n      .describe(\"Crucial marker for the block dependency tree reconstruction\"),\n    blockId: z.string().describe(\"Upstream block id\"),\n    name: z.string().describe(\"Name of the output provided to the upstream block's output context\"),\n    requireEnrichments: z\n      .literal(true)\n      .optional()\n      .describe(\n        \"True if current block that stores this reference in its args, may need enrichments \" +\n          \"for the references value originating from the blocks in between current and referenced block\",\n      ),\n  })\n  .describe(\n    \"Universal reference type, allowing to set block connections. It is crucial that \" +\n      \"{@link __isRef} is present and equal to true, internal logic relies on this marker \" +\n      \"to build block dependency trees.\",\n  )\n  .readonly();\nexport type PlRef = z.infer<typeof PlRef>;\n/** @deprecated use {@link PlRef} */\nexport type Ref = PlRef;\n\n/**\n * Type guard to check if a value is a PlRef.\n *\n * @param value - The value to check.\n * @returns True if the value is a PlRef, false otherwise.\n */\nexport function isPlRef(value: unknown): value is PlRef {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"__isRef\" in value &&\n    (value as { __isRef: unknown }).__isRef === true &&\n    \"blockId\" in value &&\n    \"name\" in value\n  );\n}\n\n/** Standard way how to communicate possible connections given specific\n * requirements for incoming data. */\nexport type Option = {\n  /** Fully rendered reference to be assigned for the intended field in block's\n   * args */\n  readonly ref: PlRef;\n\n  /** Label to be present for the user in i.e. drop-down list */\n  readonly label: string;\n};\n\n/**\n * Creates a PlRef with the given blockId and name.\n *\n * @param blockId - The blockId of the reference.\n * @param name - The name of the reference.\n * @param requireEnrichments - Whether the reference requires enrichments.\n */\nexport function createPlRef(blockId: string, name: string, requireEnrichments: boolean = false) {\n  if (requireEnrichments)\n    return {\n      __isRef: true,\n      blockId,\n      name,\n      requireEnrichments: true,\n    };\n  else\n    return {\n      __isRef: true,\n      blockId,\n      name,\n    };\n}\n\n/**\n * Creates a new PlRef based on an existing one, explicitly setting (default) or removing the\n * requireEnrichments property.\n *\n * @param ref - The original PlRef object.\n * @param requireEnrichments - If true, the `requireEnrichments: true` property is added\n *   to the returned PlRef. If false, the `requireEnrichments` property is removed. Defaults to true.\n * @returns A new PlRef object with the `requireEnrichments` property set or removed accordingly.\n */\nexport function withEnrichments(ref: PlRef, requireEnrichments: boolean = true): PlRef {\n  if (requireEnrichments)\n    return {\n      ...ref,\n      requireEnrichments: true,\n    };\n  else {\n    const { requireEnrichments: _, ...rest } = ref;\n    return rest;\n  }\n}\n\n/** Compare two PlRefs and returns true if they are qual */\nexport function plRefsEqual(ref1: PlRef, ref2: PlRef, ignoreEnrichments: boolean = false) {\n  return (\n    ref1.blockId === ref2.blockId &&\n    ref1.name === ref2.name &&\n    (ignoreEnrichments || ref1.requireEnrichments === ref2.requireEnrichments)\n  );\n}\n"],"mappings":";;;AAEA,MAAa,QAAQA,IAAAA,EAClB,OAAO;CACN,SAASA,IAAAA,EACN,QAAQ,KAAK,CACb,SAAS,8DAA8D;CAC1E,SAASA,IAAAA,EAAE,QAAQ,CAAC,SAAS,oBAAoB;CACjD,MAAMA,IAAAA,EAAE,QAAQ,CAAC,SAAS,qEAAqE;CAC/F,oBAAoBA,IAAAA,EACjB,QAAQ,KAAK,CACb,UAAU,CACV,SACC,kLAED;CACJ,CAAC,CACD,SACC,sMAGD,CACA,UAAU;;;;;;;AAWb,SAAgB,QAAQ,OAAgC;AACtD,QACE,OAAO,UAAU,YACjB,UAAU,QACV,aAAa,SACZ,MAA+B,YAAY,QAC5C,aAAa,SACb,UAAU;;;;;;;;;AAsBd,SAAgB,YAAY,SAAiB,MAAc,qBAA8B,OAAO;AAC9F,KAAI,mBACF,QAAO;EACL,SAAS;EACT;EACA;EACA,oBAAoB;EACrB;KAED,QAAO;EACL,SAAS;EACT;EACA;EACD;;;;;;;;;;;AAYL,SAAgB,gBAAgB,KAAY,qBAA8B,MAAa;AACrF,KAAI,mBACF,QAAO;EACL,GAAG;EACH,oBAAoB;EACrB;MACE;EACH,MAAM,EAAE,oBAAoB,GAAG,GAAG,SAAS;AAC3C,SAAO;;;;AAKX,SAAgB,YAAY,MAAa,MAAa,oBAA6B,OAAO;AACxF,QACE,KAAK,YAAY,KAAK,WACtB,KAAK,SAAS,KAAK,SAClB,qBAAqB,KAAK,uBAAuB,KAAK"}
+{"version":3,"file":"ref.cjs","names":["z"],"sources":["../src/ref.ts"],"sourcesContent":["import { z } from \"zod\";\n\nexport const PlRef = z\n  .object({\n    __isRef: z\n      .literal(true)\n      .describe(\"Crucial marker for the block dependency tree reconstruction\"),\n    blockId: z.string().describe(\"Upstream block id\"),\n    name: z.string().describe(\"Name of the output provided to the upstream block's output context\"),\n    requireEnrichments: z\n      .literal(true)\n      .optional()\n      .describe(\n        \"True if current block that stores this reference in its args, may need enrichments \" +\n          \"for the references value originating from the blocks in between current and referenced block\",\n      ),\n  })\n  .describe(\n    \"Universal reference type, allowing to set block connections. It is crucial that \" +\n      \"{@link __isRef} is present and equal to true, internal logic relies on this marker \" +\n      \"to build block dependency trees.\",\n  )\n  .readonly();\nexport type PlRef = z.infer<typeof PlRef>;\n/** @deprecated use {@link PlRef} */\nexport type Ref = PlRef;\n\n/**\n * Type guard to check if a value is a PlRef.\n *\n * @param value - The value to check.\n * @returns True if the value is a PlRef, false otherwise.\n */\nexport function isPlRef(value: unknown): value is PlRef {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"__isRef\" in value &&\n    (value as { __isRef: unknown }).__isRef === true &&\n    \"blockId\" in value &&\n    \"name\" in value\n  );\n}\n\n/** Standard way how to communicate possible connections given specific\n * requirements for incoming data. */\nexport type Option = {\n  /** Fully rendered reference to be assigned for the intended field in block's\n   * args */\n  readonly ref: PlRef;\n\n  /** Label to be present for the user in i.e. drop-down list */\n  readonly label: string;\n};\n\n/**\n * Creates a PlRef with the given blockId and name.\n *\n * @param blockId - The blockId of the reference.\n * @param name - The name of the reference.\n * @param requireEnrichments - Whether the reference requires enrichments.\n */\nexport function createPlRef(\n  blockId: string,\n  name: string,\n  requireEnrichments: boolean = false,\n): PlRef {\n  if (requireEnrichments)\n    return {\n      __isRef: true,\n      blockId,\n      name,\n      requireEnrichments: true,\n    };\n  else\n    return {\n      __isRef: true,\n      blockId,\n      name,\n    };\n}\n\n/**\n * Creates a new PlRef based on an existing one, explicitly setting (default) or removing the\n * requireEnrichments property.\n *\n * @param ref - The original PlRef object.\n * @param requireEnrichments - If true, the `requireEnrichments: true` property is added\n *   to the returned PlRef. If false, the `requireEnrichments` property is removed. Defaults to true.\n * @returns A new PlRef object with the `requireEnrichments` property set or removed accordingly.\n */\nexport function withEnrichments(ref: PlRef, requireEnrichments: boolean = true): PlRef {\n  if (requireEnrichments)\n    return {\n      ...ref,\n      requireEnrichments: true,\n    };\n  else {\n    const { requireEnrichments: _, ...rest } = ref;\n    return rest;\n  }\n}\n\n/** Primary dataset reference with an optional filter. */\nexport type PrimaryRef = {\n  readonly __isPrimaryRef: \"v1\";\n  readonly column: PlRef;\n  readonly filter?: PlRef;\n};\n\nexport function isPrimaryRef(value: unknown): value is PrimaryRef {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    (value as { __isPrimaryRef?: unknown }).__isPrimaryRef === \"v1\" &&\n    \"column\" in value\n  );\n}\n\nexport function createPrimaryRef(column: PlRef, filter?: PlRef): PrimaryRef {\n  if (filter !== undefined) return { __isPrimaryRef: \"v1\", column, filter };\n  else return { __isPrimaryRef: \"v1\", column };\n}\n\n/** Block args accept either form — backward compatible. */\nexport type DatasetInput = PlRef | PrimaryRef;\n\n/** Dataset option with optional filter choices. */\nexport type DatasetOption = Option & {\n  readonly filters?: readonly Option[];\n};\n\n/** Compare two PlRefs and returns true if they are qual */\nexport function plRefsEqual(ref1: PlRef, ref2: PlRef, ignoreEnrichments: boolean = false) {\n  return (\n    ref1.blockId === ref2.blockId &&\n    ref1.name === ref2.name &&\n    (ignoreEnrichments || ref1.requireEnrichments === ref2.requireEnrichments)\n  );\n}\n"],"mappings":";;;AAEA,MAAa,QAAQA,IAAAA,EAClB,OAAO;CACN,SAASA,IAAAA,EACN,QAAQ,KAAK,CACb,SAAS,8DAA8D;CAC1E,SAASA,IAAAA,EAAE,QAAQ,CAAC,SAAS,oBAAoB;CACjD,MAAMA,IAAAA,EAAE,QAAQ,CAAC,SAAS,qEAAqE;CAC/F,oBAAoBA,IAAAA,EACjB,QAAQ,KAAK,CACb,UAAU,CACV,SACC,kLAED;CACJ,CAAC,CACD,SACC,sMAGD,CACA,UAAU;;;;;;;AAWb,SAAgB,QAAQ,OAAgC;AACtD,QACE,OAAO,UAAU,YACjB,UAAU,QACV,aAAa,SACZ,MAA+B,YAAY,QAC5C,aAAa,SACb,UAAU;;;;;;;;;AAsBd,SAAgB,YACd,SACA,MACA,qBAA8B,OACvB;AACP,KAAI,mBACF,QAAO;EACL,SAAS;EACT;EACA;EACA,oBAAoB;EACrB;KAED,QAAO;EACL,SAAS;EACT;EACA;EACD;;;;;;;;;;;AAYL,SAAgB,gBAAgB,KAAY,qBAA8B,MAAa;AACrF,KAAI,mBACF,QAAO;EACL,GAAG;EACH,oBAAoB;EACrB;MACE;EACH,MAAM,EAAE,oBAAoB,GAAG,GAAG,SAAS;AAC3C,SAAO;;;AAWX,SAAgB,aAAa,OAAqC;AAChE,QACE,OAAO,UAAU,YACjB,UAAU,QACT,MAAuC,mBAAmB,QAC3D,YAAY;;AAIhB,SAAgB,iBAAiB,QAAe,QAA4B;AAC1E,KAAI,WAAW,KAAA,EAAW,QAAO;EAAE,gBAAgB;EAAM;EAAQ;EAAQ;KACpE,QAAO;EAAE,gBAAgB;EAAM;EAAQ;;;AAY9C,SAAgB,YAAY,MAAa,MAAa,oBAA6B,OAAO;AACxF,QACE,KAAK,YAAY,KAAK,WACtB,KAAK,SAAS,KAAK,SAClB,qBAAqB,KAAK,uBAAuB,KAAK"}

package/dist/ref.d.ts

@@ -42,17 +42,7 @@ type Option = {
  * @param name - The name of the reference.
  * @param requireEnrichments - Whether the reference requires enrichments.
  */
-declare function createPlRef(blockId: string, name: string, requireEnrichments?: boolean): {
-  __isRef: boolean;
-  blockId: string;
-  name: string;
-  requireEnrichments: boolean;
-} | {
-  __isRef: boolean;
-  blockId: string;
-  name: string;
-  requireEnrichments?: undefined;
-};
+declare function createPlRef(blockId: string, name: string, requireEnrichments?: boolean): PlRef;
 /**
  * Creates a new PlRef based on an existing one, explicitly setting (default) or removing the
  * requireEnrichments property.
@@ -63,8 +53,22 @@ declare function createPlRef(blockId: string, name: string, requireEnrichments?:
  * @returns A new PlRef object with the `requireEnrichments` property set or removed accordingly.
  */
 declare function withEnrichments(ref: PlRef, requireEnrichments?: boolean): PlRef;
+/** Primary dataset reference with an optional filter. */
+type PrimaryRef = {
+  readonly __isPrimaryRef: "v1";
+  readonly column: PlRef;
+  readonly filter?: PlRef;
+};
+declare function isPrimaryRef(value: unknown): value is PrimaryRef;
+declare function createPrimaryRef(column: PlRef, filter?: PlRef): PrimaryRef;
+/** Block args accept either form — backward compatible. */
+type DatasetInput = PlRef | PrimaryRef;
+/** Dataset option with optional filter choices. */
+type DatasetOption = Option & {
+  readonly filters?: readonly Option[];
+};
 /** Compare two PlRefs and returns true if they are qual */
 declare function plRefsEqual(ref1: PlRef, ref2: PlRef, ignoreEnrichments?: boolean): boolean;
 //#endregion
-export { Option, PlRef, Ref, createPlRef, isPlRef, plRefsEqual, withEnrichments };
+export { DatasetInput, DatasetOption, Option, PlRef, PrimaryRef, Ref, createPlRef, createPrimaryRef, isPlRef, isPrimaryRef, plRefsEqual, withEnrichments };
 //# sourceMappingURL=ref.d.ts.map

package/dist/ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ref.d.ts","names":[],"sources":["../src/ref.ts"],"mappings":";;;cAEa,KAAA,EAAK,CAAA,CAAA,WAAA,CAAA,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;KAqBN,KAAA,GAAQ,CAAA,CAAE,KAAA,QAAa,KAAA;;KAEvB,GAAA,GAAM,KAAA;;;;;;;iBAQF,OAAA,CAAQ,KAAA,YAAiB,KAAA,IAAS,KAAA;;;KAatC,MAAA;;;WAGD,GAAA,EAAK,KAAA;WAGL,KAAA;AAAA;;;;;;;;iBAUK,WAAA,CAAY,OAAA,UAAiB,IAAA,UAAc,kBAAA;;;;;;;;;;;;AArC3D;;;;;AAQA;;;iBAsDgB,eAAA,CAAgB,GAAA,EAAK,KAAA,EAAO,kBAAA,aAAqC,KAAA;;iBAajE,WAAA,CAAY,IAAA,EAAM,KAAA,EAAO,IAAA,EAAM,KAAA,EAAO,iBAAA"}
+{"version":3,"file":"ref.d.ts","names":[],"sources":["../src/ref.ts"],"mappings":";;;cAEa,KAAA,EAAK,CAAA,CAAA,WAAA,CAAA,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;KAqBN,KAAA,GAAQ,CAAA,CAAE,KAAA,QAAa,KAAA;;KAEvB,GAAA,GAAM,KAAA;;;;;;;iBAQF,OAAA,CAAQ,KAAA,YAAiB,KAAA,IAAS,KAAA;;;KAatC,MAAA;;;WAGD,GAAA,EAAK,KAAA;WAGL,KAAA;AAAA;;;;;;;;iBAUK,WAAA,CACd,OAAA,UACA,IAAA,UACA,kBAAA,aACC,KAAA;;;AA3CH;;;;;;;iBAoEgB,eAAA,CAAgB,GAAA,EAAK,KAAA,EAAO,kBAAA,aAAqC,KAAA;;KAarE,UAAA;EAAA,SACD,cAAA;EAAA,SACA,MAAA,EAAQ,KAAA;EAAA,SACR,MAAA,GAAS,KAAA;AAAA;AAAA,iBAGJ,YAAA,CAAa,KAAA,YAAiB,KAAA,IAAS,UAAA;AAAA,iBASvC,gBAAA,CAAiB,MAAA,EAAQ,KAAA,EAAO,MAAA,GAAS,KAAA,GAAQ,UAAA;;KAMrD,YAAA,GAAe,KAAA,GAAQ,UAAA;;KAGvB,aAAA,GAAgB,MAAA;EAAA,SACjB,OAAA,YAAmB,MAAA;AAAA;;iBAId,WAAA,CAAY,IAAA,EAAM,KAAA,EAAO,IAAA,EAAM,KAAA,EAAO,iBAAA"}

package/dist/ref.js

@@ -54,11 +54,25 @@ function withEnrichments(ref, requireEnrichments = true) {
 		return rest;
 	}
 }
+function isPrimaryRef(value) {
+	return typeof value === "object" && value !== null && value.__isPrimaryRef === "v1" && "column" in value;
+}
+function createPrimaryRef(column, filter) {
+	if (filter !== void 0) return {
+		__isPrimaryRef: "v1",
+		column,
+		filter
+	};
+	else return {
+		__isPrimaryRef: "v1",
+		column
+	};
+}
 /** Compare two PlRefs and returns true if they are qual */
 function plRefsEqual(ref1, ref2, ignoreEnrichments = false) {
 	return ref1.blockId === ref2.blockId && ref1.name === ref2.name && (ignoreEnrichments || ref1.requireEnrichments === ref2.requireEnrichments);
 }
 //#endregion
-export { PlRef, createPlRef, isPlRef, plRefsEqual, withEnrichments };
+export { PlRef, createPlRef, createPrimaryRef, isPlRef, isPrimaryRef, plRefsEqual, withEnrichments };
 
 //# sourceMappingURL=ref.js.map

package/dist/ref.js.map

@@ -1 +1 @@
-{"version":3,"file":"ref.js","names":[],"sources":["../src/ref.ts"],"sourcesContent":["import { z } from \"zod\";\n\nexport const PlRef = z\n  .object({\n    __isRef: z\n      .literal(true)\n      .describe(\"Crucial marker for the block dependency tree reconstruction\"),\n    blockId: z.string().describe(\"Upstream block id\"),\n    name: z.string().describe(\"Name of the output provided to the upstream block's output context\"),\n    requireEnrichments: z\n      .literal(true)\n      .optional()\n      .describe(\n        \"True if current block that stores this reference in its args, may need enrichments \" +\n          \"for the references value originating from the blocks in between current and referenced block\",\n      ),\n  })\n  .describe(\n    \"Universal reference type, allowing to set block connections. It is crucial that \" +\n      \"{@link __isRef} is present and equal to true, internal logic relies on this marker \" +\n      \"to build block dependency trees.\",\n  )\n  .readonly();\nexport type PlRef = z.infer<typeof PlRef>;\n/** @deprecated use {@link PlRef} */\nexport type Ref = PlRef;\n\n/**\n * Type guard to check if a value is a PlRef.\n *\n * @param value - The value to check.\n * @returns True if the value is a PlRef, false otherwise.\n */\nexport function isPlRef(value: unknown): value is PlRef {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"__isRef\" in value &&\n    (value as { __isRef: unknown }).__isRef === true &&\n    \"blockId\" in value &&\n    \"name\" in value\n  );\n}\n\n/** Standard way how to communicate possible connections given specific\n * requirements for incoming data. */\nexport type Option = {\n  /** Fully rendered reference to be assigned for the intended field in block's\n   * args */\n  readonly ref: PlRef;\n\n  /** Label to be present for the user in i.e. drop-down list */\n  readonly label: string;\n};\n\n/**\n * Creates a PlRef with the given blockId and name.\n *\n * @param blockId - The blockId of the reference.\n * @param name - The name of the reference.\n * @param requireEnrichments - Whether the reference requires enrichments.\n */\nexport function createPlRef(blockId: string, name: string, requireEnrichments: boolean = false) {\n  if (requireEnrichments)\n    return {\n      __isRef: true,\n      blockId,\n      name,\n      requireEnrichments: true,\n    };\n  else\n    return {\n      __isRef: true,\n      blockId,\n      name,\n    };\n}\n\n/**\n * Creates a new PlRef based on an existing one, explicitly setting (default) or removing the\n * requireEnrichments property.\n *\n * @param ref - The original PlRef object.\n * @param requireEnrichments - If true, the `requireEnrichments: true` property is added\n *   to the returned PlRef. If false, the `requireEnrichments` property is removed. Defaults to true.\n * @returns A new PlRef object with the `requireEnrichments` property set or removed accordingly.\n */\nexport function withEnrichments(ref: PlRef, requireEnrichments: boolean = true): PlRef {\n  if (requireEnrichments)\n    return {\n      ...ref,\n      requireEnrichments: true,\n    };\n  else {\n    const { requireEnrichments: _, ...rest } = ref;\n    return rest;\n  }\n}\n\n/** Compare two PlRefs and returns true if they are qual */\nexport function plRefsEqual(ref1: PlRef, ref2: PlRef, ignoreEnrichments: boolean = false) {\n  return (\n    ref1.blockId === ref2.blockId &&\n    ref1.name === ref2.name &&\n    (ignoreEnrichments || ref1.requireEnrichments === ref2.requireEnrichments)\n  );\n}\n"],"mappings":";;AAEA,MAAa,QAAQ,EAClB,OAAO;CACN,SAAS,EACN,QAAQ,KAAK,CACb,SAAS,8DAA8D;CAC1E,SAAS,EAAE,QAAQ,CAAC,SAAS,oBAAoB;CACjD,MAAM,EAAE,QAAQ,CAAC,SAAS,qEAAqE;CAC/F,oBAAoB,EACjB,QAAQ,KAAK,CACb,UAAU,CACV,SACC,kLAED;CACJ,CAAC,CACD,SACC,sMAGD,CACA,UAAU;;;;;;;AAWb,SAAgB,QAAQ,OAAgC;AACtD,QACE,OAAO,UAAU,YACjB,UAAU,QACV,aAAa,SACZ,MAA+B,YAAY,QAC5C,aAAa,SACb,UAAU;;;;;;;;;AAsBd,SAAgB,YAAY,SAAiB,MAAc,qBAA8B,OAAO;AAC9F,KAAI,mBACF,QAAO;EACL,SAAS;EACT;EACA;EACA,oBAAoB;EACrB;KAED,QAAO;EACL,SAAS;EACT;EACA;EACD;;;;;;;;;;;AAYL,SAAgB,gBAAgB,KAAY,qBAA8B,MAAa;AACrF,KAAI,mBACF,QAAO;EACL,GAAG;EACH,oBAAoB;EACrB;MACE;EACH,MAAM,EAAE,oBAAoB,GAAG,GAAG,SAAS;AAC3C,SAAO;;;;AAKX,SAAgB,YAAY,MAAa,MAAa,oBAA6B,OAAO;AACxF,QACE,KAAK,YAAY,KAAK,WACtB,KAAK,SAAS,KAAK,SAClB,qBAAqB,KAAK,uBAAuB,KAAK"}
+{"version":3,"file":"ref.js","names":[],"sources":["../src/ref.ts"],"sourcesContent":["import { z } from \"zod\";\n\nexport const PlRef = z\n  .object({\n    __isRef: z\n      .literal(true)\n      .describe(\"Crucial marker for the block dependency tree reconstruction\"),\n    blockId: z.string().describe(\"Upstream block id\"),\n    name: z.string().describe(\"Name of the output provided to the upstream block's output context\"),\n    requireEnrichments: z\n      .literal(true)\n      .optional()\n      .describe(\n        \"True if current block that stores this reference in its args, may need enrichments \" +\n          \"for the references value originating from the blocks in between current and referenced block\",\n      ),\n  })\n  .describe(\n    \"Universal reference type, allowing to set block connections. It is crucial that \" +\n      \"{@link __isRef} is present and equal to true, internal logic relies on this marker \" +\n      \"to build block dependency trees.\",\n  )\n  .readonly();\nexport type PlRef = z.infer<typeof PlRef>;\n/** @deprecated use {@link PlRef} */\nexport type Ref = PlRef;\n\n/**\n * Type guard to check if a value is a PlRef.\n *\n * @param value - The value to check.\n * @returns True if the value is a PlRef, false otherwise.\n */\nexport function isPlRef(value: unknown): value is PlRef {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"__isRef\" in value &&\n    (value as { __isRef: unknown }).__isRef === true &&\n    \"blockId\" in value &&\n    \"name\" in value\n  );\n}\n\n/** Standard way how to communicate possible connections given specific\n * requirements for incoming data. */\nexport type Option = {\n  /** Fully rendered reference to be assigned for the intended field in block's\n   * args */\n  readonly ref: PlRef;\n\n  /** Label to be present for the user in i.e. drop-down list */\n  readonly label: string;\n};\n\n/**\n * Creates a PlRef with the given blockId and name.\n *\n * @param blockId - The blockId of the reference.\n * @param name - The name of the reference.\n * @param requireEnrichments - Whether the reference requires enrichments.\n */\nexport function createPlRef(\n  blockId: string,\n  name: string,\n  requireEnrichments: boolean = false,\n): PlRef {\n  if (requireEnrichments)\n    return {\n      __isRef: true,\n      blockId,\n      name,\n      requireEnrichments: true,\n    };\n  else\n    return {\n      __isRef: true,\n      blockId,\n      name,\n    };\n}\n\n/**\n * Creates a new PlRef based on an existing one, explicitly setting (default) or removing the\n * requireEnrichments property.\n *\n * @param ref - The original PlRef object.\n * @param requireEnrichments - If true, the `requireEnrichments: true` property is added\n *   to the returned PlRef. If false, the `requireEnrichments` property is removed. Defaults to true.\n * @returns A new PlRef object with the `requireEnrichments` property set or removed accordingly.\n */\nexport function withEnrichments(ref: PlRef, requireEnrichments: boolean = true): PlRef {\n  if (requireEnrichments)\n    return {\n      ...ref,\n      requireEnrichments: true,\n    };\n  else {\n    const { requireEnrichments: _, ...rest } = ref;\n    return rest;\n  }\n}\n\n/** Primary dataset reference with an optional filter. */\nexport type PrimaryRef = {\n  readonly __isPrimaryRef: \"v1\";\n  readonly column: PlRef;\n  readonly filter?: PlRef;\n};\n\nexport function isPrimaryRef(value: unknown): value is PrimaryRef {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    (value as { __isPrimaryRef?: unknown }).__isPrimaryRef === \"v1\" &&\n    \"column\" in value\n  );\n}\n\nexport function createPrimaryRef(column: PlRef, filter?: PlRef): PrimaryRef {\n  if (filter !== undefined) return { __isPrimaryRef: \"v1\", column, filter };\n  else return { __isPrimaryRef: \"v1\", column };\n}\n\n/** Block args accept either form — backward compatible. */\nexport type DatasetInput = PlRef | PrimaryRef;\n\n/** Dataset option with optional filter choices. */\nexport type DatasetOption = Option & {\n  readonly filters?: readonly Option[];\n};\n\n/** Compare two PlRefs and returns true if they are qual */\nexport function plRefsEqual(ref1: PlRef, ref2: PlRef, ignoreEnrichments: boolean = false) {\n  return (\n    ref1.blockId === ref2.blockId &&\n    ref1.name === ref2.name &&\n    (ignoreEnrichments || ref1.requireEnrichments === ref2.requireEnrichments)\n  );\n}\n"],"mappings":";;AAEA,MAAa,QAAQ,EAClB,OAAO;CACN,SAAS,EACN,QAAQ,KAAK,CACb,SAAS,8DAA8D;CAC1E,SAAS,EAAE,QAAQ,CAAC,SAAS,oBAAoB;CACjD,MAAM,EAAE,QAAQ,CAAC,SAAS,qEAAqE;CAC/F,oBAAoB,EACjB,QAAQ,KAAK,CACb,UAAU,CACV,SACC,kLAED;CACJ,CAAC,CACD,SACC,sMAGD,CACA,UAAU;;;;;;;AAWb,SAAgB,QAAQ,OAAgC;AACtD,QACE,OAAO,UAAU,YACjB,UAAU,QACV,aAAa,SACZ,MAA+B,YAAY,QAC5C,aAAa,SACb,UAAU;;;;;;;;;AAsBd,SAAgB,YACd,SACA,MACA,qBAA8B,OACvB;AACP,KAAI,mBACF,QAAO;EACL,SAAS;EACT;EACA;EACA,oBAAoB;EACrB;KAED,QAAO;EACL,SAAS;EACT;EACA;EACD;;;;;;;;;;;AAYL,SAAgB,gBAAgB,KAAY,qBAA8B,MAAa;AACrF,KAAI,mBACF,QAAO;EACL,GAAG;EACH,oBAAoB;EACrB;MACE;EACH,MAAM,EAAE,oBAAoB,GAAG,GAAG,SAAS;AAC3C,SAAO;;;AAWX,SAAgB,aAAa,OAAqC;AAChE,QACE,OAAO,UAAU,YACjB,UAAU,QACT,MAAuC,mBAAmB,QAC3D,YAAY;;AAIhB,SAAgB,iBAAiB,QAAe,QAA4B;AAC1E,KAAI,WAAW,KAAA,EAAW,QAAO;EAAE,gBAAgB;EAAM;EAAQ;EAAQ;KACpE,QAAO;EAAE,gBAAgB;EAAM;EAAQ;;;AAY9C,SAAgB,YAAY,MAAa,MAAa,oBAA6B,OAAO;AACxF,QACE,KAAK,YAAY,KAAK,WACtB,KAAK,SAAS,KAAK,SAClB,qBAAqB,KAAK,uBAAuB,KAAK"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-model-common",
-  "version": "1.34.1",
+  "version": "1.35.0",
   "description": "Platforma SDK Model",
   "files": [
     "./dist/**/*",

package/src/ref.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { createPlRef, isPlRef, isPrimaryRef } from "./ref";
+
+const sampleRef = createPlRef("block1", "output1", true);
+
+describe("isPrimaryRef", () => {
+  it("returns true for a valid PrimaryRef", () => {
+    expect(isPrimaryRef({ __isPrimaryRef: "v1", column: sampleRef })).toBe(true);
+  });
+
+  it("returns true for PrimaryRef with filter", () => {
+    const filter = createPlRef("block1", "filter1");
+    expect(isPrimaryRef({ __isPrimaryRef: "v1", column: sampleRef, filter })).toBe(true);
+  });
+
+  it("returns false for a PlRef", () => {
+    expect(isPrimaryRef(sampleRef)).toBe(false);
+  });
+
+  it("returns false for null", () => {
+    expect(isPrimaryRef(null)).toBe(false);
+  });
+
+  it("returns false for a plain object", () => {
+    expect(isPrimaryRef({ foo: "bar" })).toBe(false);
+  });
+});
+
+describe("isPlRef", () => {
+  it("returns false for a PrimaryRef", () => {
+    expect(isPlRef({ __isPrimaryRef: "v1", column: sampleRef })).toBe(false);
+  });
+
+  it("returns true for a PlRef", () => {
+    expect(isPlRef(sampleRef)).toBe(true);
+  });
+});

package/src/ref.ts

@@ -60,7 +60,11 @@ export type Option = {
  * @param name - The name of the reference.
  * @param requireEnrichments - Whether the reference requires enrichments.
  */
-export function createPlRef(blockId: string, name: string, requireEnrichments: boolean = false) {
+export function createPlRef(
+  blockId: string,
+  name: string,
+  requireEnrichments: boolean = false,
+): PlRef {
   if (requireEnrichments)
     return {
       __isRef: true,
@@ -97,6 +101,35 @@ export function withEnrichments(ref: PlRef, requireEnrichments: boolean = true):
   }
 }
 
+/** Primary dataset reference with an optional filter. */
+export type PrimaryRef = {
+  readonly __isPrimaryRef: "v1";
+  readonly column: PlRef;
+  readonly filter?: PlRef;
+};
+
+export function isPrimaryRef(value: unknown): value is PrimaryRef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __isPrimaryRef?: unknown }).__isPrimaryRef === "v1" &&
+    "column" in value
+  );
+}
+
+export function createPrimaryRef(column: PlRef, filter?: PlRef): PrimaryRef {
+  if (filter !== undefined) return { __isPrimaryRef: "v1", column, filter };
+  else return { __isPrimaryRef: "v1", column };
+}
+
+/** Block args accept either form — backward compatible. */
+export type DatasetInput = PlRef | PrimaryRef;
+
+/** Dataset option with optional filter choices. */
+export type DatasetOption = Option & {
+  readonly filters?: readonly Option[];
+};
+
 /** Compare two PlRefs and returns true if they are qual */
 export function plRefsEqual(ref1: PlRef, ref2: PlRef, ignoreEnrichments: boolean = false) {
   return (