{"version":3,"file":"api_factory.cjs","names":[],"sources":["../../../src/pframe/internal_api/api_factory.ts"],"sourcesContent":["import type {\n  AxisValueType,\n  BinaryPartitionedDataInfo,\n  Branded,\n  ColumnValueType,\n  JsonDataInfo,\n  JsonPartitionedDataInfo,\n  ParquetChunk,\n  ParquetPartitionedDataInfo,\n  PObjectId,\n} from \"@milaboratories/pl-model-common\";\nimport type { HttpServerInfo } from \"./http_helpers\";\n\n/** PColumn spec file extension */\nexport const SpecExtension = \".spec\" as const;\n\n/** PColumn data info file extension */\nexport const DataInfoExtension = \".datainfo\" as const;\n\n/** Abstract identifier of a data blob that can be requested from the storage backend */\nexport type PFrameBlobId = Branded<string, \"PFrameInternal.PFrameBlobId\">;\n\n/** Path of the file containing requested data (blob). This path is returned by\n * {@link BlobPathResolver} as soon as blob materialized in the file system. */\nexport type FilePath = string;\n\n/** Data source allows PFrame to retrieve the data blobs for columns with assigned data info. */\nexport interface PFrameDataSourceV2 {\n  /**\n   * PFrame may notify storage backend about its plans to use particular blobs in the future.\n   * Storage backend will do its best to preload specified blob so the subsequent\n   * {@link resolveBlob} will quickly return preloaded file path.\n   */\n  preloadBlob(blobIds: PFrameBlobId[]): Promise<void>;\n\n  /** Returns raw blob data given the blob id from {@link DataInfo}. */\n  resolveBlobContent(blobId: PFrameBlobId): Promise<Uint8Array>;\n\n  /**\n   * Parquet HTTP(S) server connection settings, {@link HttpHelpers.createHttpServer}\n   * When not provided, parquet BlobIds would be treated as local file paths.\n   */\n  parquetServer?: HttpServerInfo;\n}\n\n/**\n * Structural type information for a single PColumn needed by the data side:\n * the axis value types (in canonical order) and the column value type. Mirrors\n * the on-disk `typeSpec` shape (`{ axes, column }`).\n */\nexport type PColumnValueTypeSpec = {\n  readonly axes: AxisValueType[];\n  readonly column: ColumnValueType;\n};\n\n/**\n * Union type representing all possible data storage formats for PColumn data.\n * The specific format used depends on data size, access patterns, and performance requirements.\n *\n * @template Blob - Type parameter representing the storage reference type (could be ResourceInfo, PFrameBlobId, etc.)\n */\nexport type DataInfo<Blob> = (\n  | JsonDataInfo\n  | JsonPartitionedDataInfo<Blob>\n  | BinaryPartitionedDataInfo<Blob>\n  | ParquetPartitionedDataInfo<ParquetChunk<Blob>>\n) & {\n  /**\n   * Self-contained structural type info. Present in data info produced by the\n   * new converter, absent in data info produced by the old one.\n   */\n  readonly typeSpec?: PColumnValueTypeSpec;\n};\n\n/**\n * Self-contained data info: {@link DataInfo} with a required\n * {@link PColumnValueTypeSpec}, so the data layer can interpret the values\n * without a separate spec. This is the on-disk `.datainfo` shape and the\n * payload accepted by {@link PFrameFactoryAPIV6.addColumns}.\n *\n * @template Blob - Type parameter representing the storage reference type (could be ResourceInfo, PFrameBlobId, etc.)\n */\nexport type DataInfoV2<Blob> = DataInfo<Blob> & {\n  readonly typeSpec: PColumnValueTypeSpec;\n};\n\n/**\n * Single column entry for {@link PFrameFactoryAPIV6.addColumns}. The structural\n * type info is carried inside {@link DataInfoV2.typeSpec} rather than as a\n * separate field, so `data` is self-describing.\n */\nexport interface AddColumnEntryV2 {\n  /** Unique column identifier within the PFrame. */\n  readonly id: PObjectId;\n  /** Self-contained data info (carries its own `typeSpec`). */\n  readonly data: DataInfoV2<PFrameBlobId>;\n}\n\n/**\n * API for populating a PFrame with columns and a data source. Each column's\n * structural type info is embedded in its self-contained\n * {@link AddColumnEntryV2.data} instead of a separate field.\n */\nexport interface PFrameFactoryAPIV6 extends Disposable {\n  /** Associates data source with this PFrame. */\n  setDataSource(dataSource: PFrameDataSourceV2): void;\n\n  /**\n   * Registers all PColumns at once: data info (self-contained, carrying its own\n   * `typeSpec`) is attached atomically. For parquet data info, schema resolution\n   * via network is performed during this call.\n   */\n  addColumns(\n    columns: AddColumnEntryV2[],\n    options?: {\n      signal?: AbortSignal;\n    },\n  ): Promise<void>;\n\n  /** Releases all the data previously added to PFrame using methods above,\n   * any interactions with disposed PFrame will result in exception */\n  dispose(): void;\n}\n"],"mappings":";;AAcA,MAAa,gBAAgB;;AAG7B,MAAa,oBAAoB"}