@milaboratories/pl-model-middle-layer 1.8.11 → 1.8.13

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

@@ -37,4 +37,22 @@ export interface PFrameFactoryAPIV2 {
      * any interactions with disposed PFrame will result in exception */
     dispose(): void;
 }
+/** API exposed by PFrames library allowing to create and provide data for
+ * PFrame objects */
+export interface PFrameFactoryAPIV3 extends Disposable {
+    /** Associates data source with this PFrame */
+    setDataSource(dataSource: PFrameDataSource): void;
+    /** Adds PColumn without data info */
+    addColumnSpec(columnId: PObjectId, columnSpec: PColumnSpec): void;
+    /**
+     * Assign data info to the specified PColumn.
+     * For parquet data info, schema resolution via network is performed during this call.
+     */
+    setColumnData(columnId: PObjectId, dataInfo: DataInfo<PFrameBlobId>, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Releases all the data previously added to PFrame using methods above,
+     * any interactions with disposed PFrame will result in exception */
+    dispose(): void;
+}
 //# sourceMappingURL=api_factory.d.ts.map

package/dist/pframe/internal_api/api_factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api_factory.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/api_factory.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,YAAY,EACZ,uBAAuB,EACvB,YAAY,EACZ,0BAA0B,EAC1B,WAAW,EACX,SAAS,EACV,MAAM,iCAAiC,CAAC;AAEzC,wFAAwF;AACxF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAGlC;+EAC+E;AAC/E,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B,gGAAgG;AAChG,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD,qEAAqE;IACrE,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC/D,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,CAAC,IAAI,IACrB,YAAY,GACZ,uBAAuB,CAAC,IAAI,CAAC,GAC7B,yBAAyB,CAAC,IAAI,CAAC,GAC/B,0BAA0B,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;AAEnD;oBACoB;AACpB,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,aAAa,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAElD,gCAAgC;IAChC,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,GAAG,IAAI,CAAC;IAElE,gDAAgD;IAChD,aAAa,CACX,QAAQ,EAAE,SAAS,EACnB,QAAQ,EAAE,QAAQ,CAAC,YAAY,CAAC,EAChC,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GACA,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;wEACoE;IACpE,OAAO,IAAI,IAAI,CAAC;CACjB"}
+{"version":3,"file":"api_factory.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/api_factory.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,YAAY,EACZ,uBAAuB,EACvB,YAAY,EACZ,0BAA0B,EAC1B,WAAW,EACX,SAAS,EACV,MAAM,iCAAiC,CAAC;AAEzC,wFAAwF;AACxF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAGlC;+EAC+E;AAC/E,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B,gGAAgG;AAChG,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD,qEAAqE;IACrE,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC/D,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,CAAC,IAAI,IACrB,YAAY,GACZ,uBAAuB,CAAC,IAAI,CAAC,GAC7B,yBAAyB,CAAC,IAAI,CAAC,GAC/B,0BAA0B,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;AAEnD;oBACoB;AACpB,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,aAAa,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAElD,gCAAgC;IAChC,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,GAAG,IAAI,CAAC;IAElE,gDAAgD;IAChD,aAAa,CACX,QAAQ,EAAE,SAAS,EACnB,QAAQ,EAAE,QAAQ,CAAC,YAAY,CAAC,EAChC,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GACA,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;wEACoE;IACpE,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;oBACoB;AACpB,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,8CAA8C;IAC9C,aAAa,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAElD,qCAAqC;IACrC,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,GAAG,IAAI,CAAC;IAElE;;;OAGG;IACH,aAAa,CACX,QAAQ,EAAE,SAAS,EACnB,QAAQ,EAAE,QAAQ,CAAC,YAAY,CAAC,EAChC,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GACA,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;wEACoE;IACpE,OAAO,IAAI,IAAI,CAAC;CACjB"}

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

@@ -2,7 +2,7 @@ import { FindColumnsRequest, FindColumnsResponse } from './find_columns';
 import { DeleteColumnFromColumnsRequest, DeleteColumnFromColumnsResponse } from './delete_column';
 import { PColumnInfo, PColumnSpec, PObjectId, UniqueValuesRequest, UniqueValuesResponse } from '@milaboratories/pl-model-common';
 import { CreateTableRequestV3 } from './create_table';
-import { PTableV6 } from './table';
+import { PTableV6, PTableV7 } from './table';
 /** Read interface exposed by PFrames library */
 export interface PFrameReadAPIV8 {
     /**
@@ -27,4 +27,31 @@ export interface PFrameReadAPIV8 {
         signal?: AbortSignal;
     }): Promise<UniqueValuesResponse>;
 }
+/** Read interface exposed by PFrames library */
+export interface PFrameReadAPIV9 {
+    /**
+     * Finds columns given filtering criteria on column name, annotations etc.
+     * and a set of qualified axes specs to find only columns with compatible
+     * axes spec.
+     *
+     * Only column specs are used, this method will work even for columns
+     * with no assigned data.
+     * */
+    findColumns(request: FindColumnsRequest): Promise<FindColumnsResponse>;
+    /**
+     * Construct new axes integration with some entry removed but integration qualificaitons preserved.
+     * Removes more then one entry in case the removal will create several disjoint sets of axes.
+     */
+    deleteColumn(request: DeleteColumnFromColumnsRequest): Promise<DeleteColumnFromColumnsResponse>;
+    /** Retrieve single column spec */
+    getColumnSpec(columnId: PObjectId): Promise<PColumnSpec>;
+    /** Retrieve information about all columns currently added to the PFrame */
+    listColumns(): Promise<PColumnInfo[]>;
+    /** Calculates data for the table and returns an object to access it */
+    createTable(request: CreateTableRequestV3): PTableV7;
+    /** Calculate set of unique values for a specific axis for the filtered set of records */
+    getUniqueValues(request: UniqueValuesRequest, ops?: {
+        signal?: AbortSignal;
+    }): Promise<UniqueValuesResponse>;
+}
 //# sourceMappingURL=api_read.d.ts.map

package/dist/pframe/internal_api/api_read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api_read.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/api_read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EAAE,8BAA8B,EAAE,+BAA+B,EAAE,MAAM,iBAAiB,CAAC;AAClG,OAAO,EACL,WAAW,EACX,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B;;;;;;;SAOK;IACL,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEvE,mCAAmC;IACnC,YAAY,CAAC,OAAO,EAAE,8BAA8B,GAAG,OAAO,CAAC,+BAA+B,CAAC,CAAC;IAEhG,kCAAkC;IAClC,aAAa,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEzD,2EAA2E;IAC3E,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAEtC,uEAAuE;IACvE,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,QAAQ,CAAC;IAErD,yFAAyF;IACzF,eAAe,CACb,OAAO,EAAE,mBAAmB,EAC5B,GAAG,CAAC,EAAE;QACJ,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GACA,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAClC"}
+{"version":3,"file":"api_read.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/api_read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EAAE,8BAA8B,EAAE,+BAA+B,EAAE,MAAM,iBAAiB,CAAC;AAClG,OAAO,EACL,WAAW,EACX,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE7C,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B;;;;;;;SAOK;IACL,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEvE,mCAAmC;IACnC,YAAY,CAAC,OAAO,EAAE,8BAA8B,GAAG,OAAO,CAAC,+BAA+B,CAAC,CAAC;IAEhG,kCAAkC;IAClC,aAAa,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEzD,2EAA2E;IAC3E,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAEtC,uEAAuE;IACvE,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,QAAQ,CAAC;IAErD,yFAAyF;IACzF,eAAe,CACb,OAAO,EAAE,mBAAmB,EAC5B,GAAG,CAAC,EAAE;QACJ,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GACA,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAClC;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B;;;;;;;SAOK;IACL,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEvE;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,8BAA8B,GAAG,OAAO,CAAC,+BAA+B,CAAC,CAAC;IAEhG,kCAAkC;IAClC,aAAa,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEzD,2EAA2E;IAC3E,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAEtC,uEAAuE;IACvE,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,QAAQ,CAAC;IAErD,yFAAyF;IACzF,eAAe,CACb,OAAO,EAAE,mBAAmB,EAC5B,GAAG,CAAC,EAAE;QACJ,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GACA,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAClC"}

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

@@ -1,14 +1,6 @@
 import type { Readable } from 'node:stream';
 import type { RequestListener } from 'node:http';
-import type { AddressInfo } from 'node:net';
-import type { Branded } from '@milaboratories/pl-model-common';
-/** File statistics */
-export type FileStats = {
-    /** File size in bytes */
-    size: number;
-    /** File modification time if available */
-    mtime?: Date;
-};
+import type { Branded, Base64Encoded } from '@milaboratories/pl-model-common';
 /** File range specification */
 export type FileRange = {
     /** Start byte position (inclusive) */
@@ -24,131 +16,129 @@ export type FileRange = {
  */
 export interface ObjectStore {
     /**
-     * Check if file exists
+     * @returns file size in bytes or `-1` if file does not exist or permissions do not allow access.
+     * @throws if file can become accessible after retry (e.g. on network error)
      *
      * @example
      * ```ts
-     * async fileExists(filename: string): Promise<boolean> {
+     * async getFileSize(filename: string): Promise<number> {
      *   const filePath = this.resolve(filename);
-     *   try {
-     *     await fs.access(filePath, constants.F_OK);
-     *     return true;
-     *   } catch {
-     *     return false;
-     *   }
+     *   return await fs
+     *     .stat(filePath)
+     *     .then((stat) => ({ size: stat.isFile() ? stat.size : -1 }))
+     *     .catch(() => ({ size: -1 }));
      * }
      * ```
      */
-    fileExists(filename: string): Promise<boolean>;
+    getFileSize(filename: string): Promise<number>;
     /**
-     * Get file statistics
+     * Execute action with readable stream (actions can be concurrency limited by the store).
+     * Action resolves when stream is closed by handler @see HttpHelpers.createRequestHandler
      *
-     * @example
-     * ```ts
-     * async getFileStats(filename: string): Promise<FileStats> {
-     *   const filePath = this.resolve(filename);
-     *   try {
-     *     const stats = await fs.stat(filePath);
-     *     return {
-     *       size: stats.size,
-     *       mtime: stats.mtime
-     *     };
-     *   } catch (err: unknown) {
-     *     throw new Error(
-     *       `Failed to get file statistics for: ${filename} - ${ensureError(err)}`
-     *     );
-     *   }
-     * }
-     * ```
-     */
-    getFileStats(filename: string): Promise<FileStats>;
-    /**
-     * Execute action with readable stream.
-     * Action resolves when stream is closed eigher by handler
-     * @see HttpHelpers.createRequestHandler or the store itself.
-     * Returned promise resolves after the action is completed.
+     * @param filename - existing file name (for which @see ObjectStore.getFileSize returned non-negative value)
+     * @param range - valid range of bytes to read from the file (store may skip validation)
+     * @param action - function to execute with the stream, responsible for closing the stream
+     * @returns promise that resolves after the action is completed
      *
      * @example
      * ```ts
      * async withReadStream(params: {
      *   filename: string;
-     *   range?: FileRange;
+     *   range: FileRange;
      *   action: (stream: Readable) => Promise<void>;
      * }): Promise<void> {
      *   const { filename, range, action } = params;
      *   const filePath = this.resolve(filename);
      *
-     *   let stream: Readable;
      *   try {
-     *     stream = createReadStream(filePath, range);
+     *     const stream = createReadStream(filePath, range);
+     *     return await action(stream);
      *   } catch (err: unknown) {
-     *     throw new Error(
-     *       `Failed to create read stream for: ${filename} - ${ensureError(err)}`
-     *     );
-     *   }
-     *
-     *   try {
-     *     await action(stream);
-     *   } finally {
-     *     if (!stream.destroyed) {
-     *       stream.destroy();
-     *     }
+     *     console.error(`failed to create read stream for ${filename} - ${ensureError(err)}`);
+     *     throw;
      *   }
      * }
      * ```
      */
     withReadStream(params: {
         filename: string;
+        range: FileRange;
         action: (stream: Readable) => Promise<void>;
-        range?: FileRange;
     }): Promise<void>;
 }
 /** Object store base URL in format accepted by Apache DataFusion and DuckDB */
 export type ObjectStoreUrl = Branded<string, 'PFrameInternal.ObjectStoreUrl'>;
+/** HTTP(S) request handler creation options */
+export type RequestHandlerOptions = {
+    /** Object store to serve files from, @see HttpHelpers.createFsStore */
+    store: ObjectStore;
+};
 /** Server configuration options */
 export type HttpServerOptions = {
-    /** HTTP request handler function */
+    /** HTTP(S) request handler function, @see HttpHelpers.createRequestHandler */
     handler: RequestListener;
-    /** Host to bind to (defaults to '127.0.0.1') */
-    host?: string;
-    /** Port to bind to (defaults to 0 for auto-assignment) */
+    /** Port to bind to (@default 0 for auto-assignment) */
     port?: number;
+    /** Do not apply authorization middleware to @param handler */
+    noAuth?: true;
+    /** Downgrade default HTTPS server to plain HTTP, @warning use only for testing */
+    http?: true;
 };
-/** Result of the server start operation */
+/**
+ * Long unique opaque string for use in Bearer authorization header
+ *
+ * @example
+ * ```ts
+ * request.setHeader('Authorization', `Bearer ${authToken}`);
+ * ```
+ */
+export type HttpAuthorizationToken = Branded<string, 'PFrameInternal.HttpAuthorizationToken'>;
+/**
+ * TLS certificate in PEM format
+ *
+ * @example
+ * ```txt
+ * -----BEGIN CERTIFICATE-----
+ * MIIC2zCCAcOgAwIBAgIJaVW7...
+ * ...
+ * ...Yf9CRK8fgnukKM7TJ
+ * -----END CERTIFICATE-----
+ * ```
+ */
+export type PemCertificate = Branded<string, 'PFrameInternal.PemCertificate'>;
+/** HTTP(S) server information and controls, @see HttpHelpers.createHttpServer */
 export interface HttpServer {
-    /** Server address info */
-    get address(): AddressInfo;
+    /** Server address info formatted as `http{s}://<host>:<port>/` */
+    get address(): ObjectStoreUrl;
+    /** Authorization token for Bearer scheme, undefined when @see HttpServerOptions.noAuth flag is set */
+    get authToken(): HttpAuthorizationToken | undefined;
+    /** Base64-encoded CA certificate in PEM format, undefined when @see HttpServerOptions.http flag is set */
+    get encodedCaCert(): Base64Encoded<PemCertificate> | undefined;
     /** Promise that resolves when the server is stopped */
     get stopped(): Promise<void>;
-    /** Stop the server */
+    /** Request server stop, returns the same promise as @see HttpServer.stopped */
     stop(): Promise<void>;
 }
+/** List of HTTP(S) related helper functions exposed by PFrame module */
 export interface HttpHelpers {
     /**
      * Create an object store for serving files from a local directory.
      * Rejects if the provided path does not exist or is not a directory.
-     * Intended for testing purposes, you will probably want to implement a different store.
      */
     createFsStore(rootDir: string): Promise<ObjectStore>;
     /**
      * Create an HTTP request handler for serving files from an object store.
-     * Accepts only paths of the form `/<filename>.parquet`, returns 404 otherwise.
+     * Accepts only paths of the form `/<filename>.parquet`, returns 410 otherwise.
      * Assumes that files are immutable (and sets cache headers accordingly).
      */
-    createRequestHandler(store: ObjectStore): RequestListener;
-    /**
-     * Create an object store URL from the server address info.
-     * Result of this function is intended to be passed to PFrames as data source parquet prefix.
-     */
-    createObjectStoreUrl(info: AddressInfo): ObjectStoreUrl;
+    createRequestHandler(options: RequestHandlerOptions): RequestListener;
     /**
-     * Serve HTTP requests using the provided handler on the given host and port.
-     * Returns a promise that resolves when the server is stopped.
+     * Serve HTTP(S) requests using the provided handler on localhost port.
+     * @returns promise that resolves when the server has stopped.
      *
      * @example
      * ```ts
      * const rootDir = '/path/to/directory/with/parquet/files';
-     * const port = 3000;
      *
      * let store = await HttpHelpers.createFsStore(rootDir).catch((err: unknown) => {
      *   throw new Error(`Failed to create file store for ${rootDir} - ${ensureError(err)}`);
@@ -156,12 +146,11 @@ export interface HttpHelpers {
      *
      * const server = await HttpHelpers.createHttpServer({
      *   handler: HttpHelpers.createRequestHandler(store),
-     *   port,
      * }).catch((err: unknown) => {
-     *   throw new Error(`Failed to start http server on port ${port} - ${ensureError(err)}`);
+     *   throw new Error(`Failed to start HTTP server - ${ensureError(err)}`);
      * });
      *
-     * const _ = HttpHelpers.createObjectStoreUrl(server.address);
+     * const { address, authToken, base64EncodedCaCert } = server;
      *
      * await server.stop();
      * ```

package/dist/pframe/internal_api/http_helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http_helpers.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/http_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAE/D,sBAAsB;AACtB,MAAM,MAAM,SAAS,GAAG;IACtB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,KAAK,CAAC,EAAE,IAAI,CAAC;CACd,CAAC;AAEF,+BAA+B;AAC/B,MAAM,MAAM,SAAS,GAAG;IACtB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE/C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,cAAc,CAAC,MAAM,EAAE;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,CAAC,MAAM,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;QAC5C,KAAK,CAAC,EAAE,SAAS,CAAC;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,+BAA+B,CAAC,CAAC;AAE9E,mCAAmC;AACnC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,oCAAoC;IACpC,OAAO,EAAE,eAAe,CAAC;IACzB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACzB,0BAA0B;IAC1B,IAAI,OAAO,IAAI,WAAW,CAAC;IAC3B,uDAAuD;IACvD,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,sBAAsB;IACtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAErD;;;;OAIG;IACH,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,eAAe,CAAC;IAE1D;;;OAGG;IACH,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,cAAc,CAAC;IAExD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACnE"}
+{"version":3,"file":"http_helpers.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/http_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAE9E,+BAA+B;AAC/B,MAAM,MAAM,SAAS,GAAG;IACtB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,cAAc,CAAC,MAAM,EAAE;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,SAAS,CAAC;QACjB,MAAM,EAAE,CAAC,MAAM,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC7C,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,+BAA+B,CAAC,CAAC;AAE9E,+CAA+C;AAC/C,MAAM,MAAM,qBAAqB,GAAG;IAClC,uEAAuE;IACvE,KAAK,EAAE,WAAW,CAAC;CAEpB,CAAA;AAED,mCAAmC;AACnC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,8EAA8E;IAC9E,OAAO,EAAE,eAAe,CAAC;IACzB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,kFAAkF;IAClF,IAAI,CAAC,EAAE,IAAI,CAAC;CACb,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAAC,MAAM,EAAE,uCAAuC,CAAC,CAAC;AAE9F;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,+BAA+B,CAAC,CAAC;AAE9E,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,IAAI,OAAO,IAAI,cAAc,CAAC;IAC9B,sGAAsG;IACtG,IAAI,SAAS,IAAI,sBAAsB,GAAG,SAAS,CAAC;IACpD,0GAA0G;IAC1G,IAAI,aAAa,IAAI,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC;IAC/D,uDAAuD;IACvD,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,+EAA+E;IAC/E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAErD;;;;OAIG;IACH,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,eAAe,CAAC;IAEtE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACnE"}

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

@@ -1,6 +1,30 @@
-import type { PFrameFactoryAPIV2 } from './api_factory';
-import type { PFrameReadAPIV8 } from './api_read';
+import type { PFrameFactoryAPIV2, PFrameFactoryAPIV3 } from './api_factory';
+import type { PFrameReadAPIV8, PFrameReadAPIV9 } from './api_read';
 export type Logger = (level: 'info' | 'warn' | 'error', message: string) => void;
 export interface PFrameV9 extends PFrameFactoryAPIV2, PFrameReadAPIV8 {
 }
+export interface PFrameV10 extends PFrameFactoryAPIV3, PFrameReadAPIV9 {
+}
+export type PFrameOptions = {
+    /** Path to directory where PFrame can create temporary files */
+    spillPath: string;
+    /** Logger instance, no logging is performed when not provided */
+    logger?: Logger;
+};
+/** List of PFrame management functions exposed by PFrame module */
+export interface PFrameFactory {
+    /**
+     * Create a new PFrame instance.
+     * @warning Use concurrency limiting to avoid OOM crashes when multiple instances are simultaneously in use.
+     */
+    createPFrame(options: PFrameOptions): PFrameV10;
+    /**
+     * Dump active allocations from all PFrames instances in pprof format.
+     * The result of this function should be saved as `profile.pb.gz`.
+     * Use {@link https://pprof.me/} or {@link https://www.speedscope.app/}
+     * to view the allocation flamechart.
+     * @warning This method will always reject on Windows!
+     */
+    pprofDump: () => Promise<Uint8Array>;
+}
 //# sourceMappingURL=pframe.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"pframe.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/pframe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,MAAM,MAAM,GAAG,CACnB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAChC,OAAO,EAAE,MAAM,KACZ,IAAI,CAAC;AAEV,MAAM,WAAW,QAAS,SAAQ,kBAAkB,EAAE,eAAe;CAAG"}
+{"version":3,"file":"pframe.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/pframe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEnE,MAAM,MAAM,MAAM,GAAG,CACnB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAChC,OAAO,EAAE,MAAM,KACZ,IAAI,CAAC;AAEV,MAAM,WAAW,QAAS,SAAQ,kBAAkB,EAAE,eAAe;CAAG;AAExE,MAAM,WAAW,SAAU,SAAQ,kBAAkB,EAAE,eAAe;CAAG;AAEzE,MAAM,MAAM,aAAa,GAAG;IAC1B,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAA;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAAC;IAEhD;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;CACtC"}

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

@@ -53,4 +53,58 @@ export interface PTableV6 {
     /** Deallocates all underlying resources */
     dispose(): void;
 }
+/**
+ * Table view returned as a result of create table operation.
+ *
+ * PTable can be thought as having a composite primary key, consisting of axes,
+ * and a set of data columns derived from PColumn values.
+ * */
+export interface PTableV7 extends Disposable {
+    /**
+     * Returns ordered array of table axes specs (primary key "columns" in SQL
+     * terms) and data column specs (regular "columns" in SQL terms).
+     *
+     * Data for a specific table column can be retrieved using unified indexing
+     * corresponding to elements in this array.
+     *
+     * Axes are always listed first.
+     * */
+    getSpec(): PTableColumnSpec[];
+    /** Transforms unified column identifiers into unified indices of columns. */
+    getColumnIndices(columnIds: PTableColumnId[]): number[];
+    /**
+     * Get PTable disk footprint in bytes
+     * Warning: This call materializes the join.
+     */
+    getFootprint(ops?: {
+        withPredecessors?: boolean;
+        signal?: AbortSignal;
+    }): Promise<number>;
+    /**
+     * Unified table shape
+     * Warning: This call materializes the join.
+     */
+    getShape(ops?: {
+        signal?: AbortSignal;
+    }): Promise<PTableShape>;
+    /**
+     * Retrieve the data from the table. To retrieve only data required, it can be
+     * sliced both horizontally ({@link columnIndices}) and vertically
+     * ({@link range}).
+     * This call materializes the join.
+     *
+     * @param columnIndices unified indices of columns to be retrieved
+     * @param range optionally limit the range of records to retrieve
+     * */
+    getData(columnIndices: number[], ops?: {
+        range?: TableRange;
+        signal?: AbortSignal;
+    }): Promise<PTableVector[]>;
+    /** Filters the table and returns new PTable instance */
+    filter(request: PTableRecordFilter[]): PTableV7;
+    /** Sorts the table and returns new PTable instance. */
+    sort(request: PTableSorting[]): PTableV7;
+    /** Deallocates all underlying resources */
+    dispose(): void;
+}
 //# sourceMappingURL=table.d.ts.map

package/dist/pframe/internal_api/table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/table.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,UAAU,EACX,MAAM,iCAAiC,CAAC;AAEzC;;;;;KAKK;AACL,MAAM,WAAW,QAAQ;IACvB;;;;;;;;SAQK;IACL,OAAO,IAAI,gBAAgB,EAAE,CAAC;IAE9B,6EAA6E;IAC7E,gBAAgB,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC;IAExD;;;OAGG;IACH,YAAY,CAAC,GAAG,CAAC,EAAE;QACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE;QACb,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEzB;;;;;;;;SAQK;IACL,OAAO,CACL,aAAa,EAAE,MAAM,EAAE,EACvB,GAAG,CAAC,EAAE;QACJ,KAAK,CAAC,EAAE,UAAU,CAAC;QACnB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GACA,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAE3B,wDAAwD;IACxD,MAAM,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,QAAQ,CAAC;IAEhD,uDAAuD;IACvD,IAAI,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,QAAQ,CAAC;IAEzC,2CAA2C;IAC3C,OAAO,IAAI,IAAI,CAAC;CACjB"}
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/table.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,UAAU,EACX,MAAM,iCAAiC,CAAC;AAEzC;;;;;KAKK;AACL,MAAM,WAAW,QAAQ;IACvB;;;;;;;;SAQK;IACL,OAAO,IAAI,gBAAgB,EAAE,CAAC;IAE9B,6EAA6E;IAC7E,gBAAgB,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC;IAExD;;;OAGG;IACH,YAAY,CAAC,GAAG,CAAC,EAAE;QACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE;QACb,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEzB;;;;;;;;SAQK;IACL,OAAO,CACL,aAAa,EAAE,MAAM,EAAE,EACvB,GAAG,CAAC,EAAE;QACJ,KAAK,CAAC,EAAE,UAAU,CAAC;QACnB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GACA,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAE3B,wDAAwD;IACxD,MAAM,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,QAAQ,CAAC;IAEhD,uDAAuD;IACvD,IAAI,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,QAAQ,CAAC;IAEzC,2CAA2C;IAC3C,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;KAKK;AACL,MAAM,WAAW,QAAS,SAAQ,UAAU;IAC1C;;;;;;;;SAQK;IACL,OAAO,IAAI,gBAAgB,EAAE,CAAC;IAE9B,6EAA6E;IAC7E,gBAAgB,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC;IAExD;;;OAGG;IACH,YAAY,CAAC,GAAG,CAAC,EAAE;QACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE;QACb,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEzB;;;;;;;;SAQK;IACL,OAAO,CACL,aAAa,EAAE,MAAM,EAAE,EACvB,GAAG,CAAC,EAAE;QACJ,KAAK,CAAC,EAAE,UAAU,CAAC;QACnB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GACA,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAE3B,wDAAwD;IACxD,MAAM,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,QAAQ,CAAC;IAEhD,uDAAuD;IACvD,IAAI,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,QAAQ,CAAC;IAEzC,2CAA2C;IAC3C,OAAO,IAAI,IAAI,CAAC;CACjB"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@milaboratories/pl-model-middle-layer",
-  "version": "1.8.11",
+  "version": "1.8.13",
   "description": "Common model between middle layer and non-block UI code",
+  "type": "module",
   "types": "./dist/index.d.ts",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
+  "main": "./dist/index.js",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -20,13 +20,13 @@
     "remeda": "^2.28.0",
     "zod": "~3.23.8",
     "utility-types": "^3.11.0",
-    "@milaboratories/pl-model-common": "^1.19.12"
+    "@milaboratories/pl-model-common": "1.19.13"
   },
   "devDependencies": {
     "typescript": "~5.6.3",
     "@milaboratories/build-configs": "1.0.8",
-    "@milaboratories/ts-builder": "1.0.4",
-    "@milaboratories/ts-configs": "1.0.6"
+    "@milaboratories/ts-configs": "1.0.6",
+    "@milaboratories/ts-builder": "1.0.5"
   },
   "scripts": {
     "type-check": "ts-builder types --target node",

package/src/pframe/internal_api/api_factory.ts

@@ -63,3 +63,29 @@ export interface PFrameFactoryAPIV2 {
    * any interactions with disposed PFrame will result in exception */
   dispose(): void;
 }
+
+/** API exposed by PFrames library allowing to create and provide data for
+ * PFrame objects */
+export interface PFrameFactoryAPIV3 extends Disposable {
+  /** Associates data source with this PFrame */
+  setDataSource(dataSource: PFrameDataSource): void;
+
+  /** Adds PColumn without data info */
+  addColumnSpec(columnId: PObjectId, columnSpec: PColumnSpec): void;
+
+  /**
+   * Assign data info to the specified PColumn.
+   * For parquet data info, schema resolution via network is performed during this call.
+   */
+  setColumnData(
+    columnId: PObjectId,
+    dataInfo: DataInfo<PFrameBlobId>,
+    options?: {
+      signal?: AbortSignal,
+    }
+  ): Promise<void>;
+
+  /** Releases all the data previously added to PFrame using methods above,
+   * any interactions with disposed PFrame will result in exception */
+  dispose(): void;
+}

package/src/pframe/internal_api/api_read.ts

@@ -8,7 +8,7 @@ import {
   UniqueValuesResponse
 } from '@milaboratories/pl-model-common';
 import { CreateTableRequestV3 } from './create_table';
-import { PTableV6 } from './table';
+import { PTableV6, PTableV7 } from './table';
 
 /** Read interface exposed by PFrames library */
 export interface PFrameReadAPIV8 {
@@ -42,3 +42,39 @@ export interface PFrameReadAPIV8 {
     }
   ): Promise<UniqueValuesResponse>;
 }
+
+/** Read interface exposed by PFrames library */
+export interface PFrameReadAPIV9 {
+  /**
+   * Finds columns given filtering criteria on column name, annotations etc.
+   * and a set of qualified axes specs to find only columns with compatible
+   * axes spec.
+   *
+   * Only column specs are used, this method will work even for columns
+   * with no assigned data.
+   * */
+  findColumns(request: FindColumnsRequest): Promise<FindColumnsResponse>;
+
+  /**
+   * Construct new axes integration with some entry removed but integration qualificaitons preserved.
+   * Removes more then one entry in case the removal will create several disjoint sets of axes.
+   */
+  deleteColumn(request: DeleteColumnFromColumnsRequest): Promise<DeleteColumnFromColumnsResponse>;
+
+  /** Retrieve single column spec */
+  getColumnSpec(columnId: PObjectId): Promise<PColumnSpec>;
+
+  /** Retrieve information about all columns currently added to the PFrame */
+  listColumns(): Promise<PColumnInfo[]>;
+
+  /** Calculates data for the table and returns an object to access it */
+  createTable(request: CreateTableRequestV3): PTableV7;
+
+  /** Calculate set of unique values for a specific axis for the filtered set of records */
+  getUniqueValues(
+    request: UniqueValuesRequest,
+    ops?: {
+      signal?: AbortSignal,
+    }
+  ): Promise<UniqueValuesResponse>;
+}

package/src/pframe/internal_api/http_helpers.ts

@@ -1,15 +1,6 @@
 import type { Readable } from 'node:stream';
 import type { RequestListener } from 'node:http';
-import type { AddressInfo } from 'node:net';
-import type { Branded } from '@milaboratories/pl-model-common';
-
-/** File statistics */
-export type FileStats = {
-  /** File size in bytes */
-  size: number;
-  /** File modification time if available */
-  mtime?: Date;
-};
+import type { Branded, Base64Encoded } from '@milaboratories/pl-model-common';
 
 /** File range specification */
 export type FileRange = {
@@ -27,140 +18,140 @@ export type FileRange = {
  */
 export interface ObjectStore {
   /**
-   * Check if file exists
+   * @returns file size in bytes or `-1` if file does not exist or permissions do not allow access.
+   * @throws if file can become accessible after retry (e.g. on network error)
    *
    * @example
    * ```ts
-   * async fileExists(filename: string): Promise<boolean> {
+   * async getFileSize(filename: string): Promise<number> {
    *   const filePath = this.resolve(filename);
-   *   try {
-   *     await fs.access(filePath, constants.F_OK);
-   *     return true;
-   *   } catch {
-   *     return false;
-   *   }
-   * }
-   * ```
-   */
-  fileExists(filename: string): Promise<boolean>;
-
-  /**
-   * Get file statistics
-   *
-   * @example
-   * ```ts
-   * async getFileStats(filename: string): Promise<FileStats> {
-   *   const filePath = this.resolve(filename);
-   *   try {
-   *     const stats = await fs.stat(filePath);
-   *     return {
-   *       size: stats.size,
-   *       mtime: stats.mtime
-   *     };
-   *   } catch (err: unknown) {
-   *     throw new Error(
-   *       `Failed to get file statistics for: ${filename} - ${ensureError(err)}`
-   *     );
-   *   }
+   *   return await fs
+   *     .stat(filePath)
+   *     .then((stat) => ({ size: stat.isFile() ? stat.size : -1 }))
+   *     .catch(() => ({ size: -1 }));
    * }
    * ```
    */
-  getFileStats(filename: string): Promise<FileStats>;
+  getFileSize(filename: string): Promise<number>;
 
   /**
-   * Execute action with readable stream.
-   * Action resolves when stream is closed eigher by handler
-   * @see HttpHelpers.createRequestHandler or the store itself.
-   * Returned promise resolves after the action is completed.
+   * Execute action with readable stream (actions can be concurrency limited by the store).
+   * Action resolves when stream is closed by handler @see HttpHelpers.createRequestHandler
+   * 
+   * @param filename - existing file name (for which @see ObjectStore.getFileSize returned non-negative value)
+   * @param range - valid range of bytes to read from the file (store may skip validation)
+   * @param action - function to execute with the stream, responsible for closing the stream
+   * @returns promise that resolves after the action is completed
    *
    * @example
    * ```ts
    * async withReadStream(params: {
    *   filename: string;
-   *   range?: FileRange;
+   *   range: FileRange;
    *   action: (stream: Readable) => Promise<void>;
    * }): Promise<void> {
    *   const { filename, range, action } = params;
    *   const filePath = this.resolve(filename);
    *
-   *   let stream: Readable;
    *   try {
-   *     stream = createReadStream(filePath, range);
+   *     const stream = createReadStream(filePath, range);
+   *     return await action(stream);
    *   } catch (err: unknown) {
-   *     throw new Error(
-   *       `Failed to create read stream for: ${filename} - ${ensureError(err)}`
-   *     );
-   *   }
-   *
-   *   try {
-   *     await action(stream);
-   *   } finally {
-   *     if (!stream.destroyed) {
-   *       stream.destroy();
-   *     }
+   *     console.error(`failed to create read stream for ${filename} - ${ensureError(err)}`);
+   *     throw;
    *   }
    * }
    * ```
    */
   withReadStream(params: {
     filename: string;
+    range: FileRange;
     action: (stream: Readable) => Promise<void>;
-    range?: FileRange;
   }): Promise<void>;
 }
 
 /** Object store base URL in format accepted by Apache DataFusion and DuckDB */
 export type ObjectStoreUrl = Branded<string, 'PFrameInternal.ObjectStoreUrl'>;
 
+/** HTTP(S) request handler creation options */
+export type RequestHandlerOptions = {
+  /** Object store to serve files from, @see HttpHelpers.createFsStore */
+  store: ObjectStore;
+  /** Here will go caching options... */
+}
+
 /** Server configuration options */
 export type HttpServerOptions = {
-  /** HTTP request handler function */
+  /** HTTP(S) request handler function, @see HttpHelpers.createRequestHandler */
   handler: RequestListener;
-  /** Host to bind to (defaults to '127.0.0.1') */
-  host?: string;
-  /** Port to bind to (defaults to 0 for auto-assignment) */
+  /** Port to bind to (@default 0 for auto-assignment) */
   port?: number;
+  /** Do not apply authorization middleware to @param handler */
+  noAuth?: true;
+  /** Downgrade default HTTPS server to plain HTTP, @warning use only for testing */
+  http?: true;
 };
 
-/** Result of the server start operation */
+/**
+ * Long unique opaque string for use in Bearer authorization header
+ * 
+ * @example
+ * ```ts
+ * request.setHeader('Authorization', `Bearer ${authToken}`);
+ * ```
+ */
+export type HttpAuthorizationToken = Branded<string, 'PFrameInternal.HttpAuthorizationToken'>;
+
+/**
+ * TLS certificate in PEM format
+ * 
+ * @example
+ * ```txt
+ * -----BEGIN CERTIFICATE-----
+ * MIIC2zCCAcOgAwIBAgIJaVW7...
+ * ...
+ * ...Yf9CRK8fgnukKM7TJ
+ * -----END CERTIFICATE-----
+ * ```
+ */
+export type PemCertificate = Branded<string, 'PFrameInternal.PemCertificate'>;
+
+/** HTTP(S) server information and controls, @see HttpHelpers.createHttpServer */
 export interface HttpServer {
-  /** Server address info */
-  get address(): AddressInfo;
+  /** Server address info formatted as `http{s}://<host>:<port>/` */
+  get address(): ObjectStoreUrl;
+  /** Authorization token for Bearer scheme, undefined when @see HttpServerOptions.noAuth flag is set */
+  get authToken(): HttpAuthorizationToken | undefined;
+  /** Base64-encoded CA certificate in PEM format, undefined when @see HttpServerOptions.http flag is set */
+  get encodedCaCert(): Base64Encoded<PemCertificate> | undefined;
   /** Promise that resolves when the server is stopped */
   get stopped(): Promise<void>;
-  /** Stop the server */
+  /** Request server stop, returns the same promise as @see HttpServer.stopped */
   stop(): Promise<void>;
 }
 
+/** List of HTTP(S) related helper functions exposed by PFrame module */
 export interface HttpHelpers {
   /**
    * Create an object store for serving files from a local directory.
    * Rejects if the provided path does not exist or is not a directory.
-   * Intended for testing purposes, you will probably want to implement a different store.
    */
   createFsStore(rootDir: string): Promise<ObjectStore>;
 
   /**
    * Create an HTTP request handler for serving files from an object store.
-   * Accepts only paths of the form `/<filename>.parquet`, returns 404 otherwise.
+   * Accepts only paths of the form `/<filename>.parquet`, returns 410 otherwise.
    * Assumes that files are immutable (and sets cache headers accordingly).
    */
-  createRequestHandler(store: ObjectStore): RequestListener;
-
-  /**
-   * Create an object store URL from the server address info.
-   * Result of this function is intended to be passed to PFrames as data source parquet prefix.
-   */
-  createObjectStoreUrl(info: AddressInfo): ObjectStoreUrl;
+  createRequestHandler(options: RequestHandlerOptions): RequestListener;
 
   /**
-   * Serve HTTP requests using the provided handler on the given host and port.
-   * Returns a promise that resolves when the server is stopped.
+   * Serve HTTP(S) requests using the provided handler on localhost port.
+   * @returns promise that resolves when the server has stopped.
    *
    * @example
    * ```ts
    * const rootDir = '/path/to/directory/with/parquet/files';
-   * const port = 3000;
    *
    * let store = await HttpHelpers.createFsStore(rootDir).catch((err: unknown) => {
    *   throw new Error(`Failed to create file store for ${rootDir} - ${ensureError(err)}`);
@@ -168,12 +159,11 @@ export interface HttpHelpers {
    *
    * const server = await HttpHelpers.createHttpServer({
    *   handler: HttpHelpers.createRequestHandler(store),
-   *   port,
    * }).catch((err: unknown) => {
-   *   throw new Error(`Failed to start http server on port ${port} - ${ensureError(err)}`);
+   *   throw new Error(`Failed to start HTTP server - ${ensureError(err)}`);
    * });
    *
-   * const _ = HttpHelpers.createObjectStoreUrl(server.address);
+   * const { address, authToken, base64EncodedCaCert } = server;
    *
    * await server.stop();
    * ```

package/src/pframe/internal_api/pframe.ts

@@ -1,5 +1,5 @@
-import type { PFrameFactoryAPIV2 } from './api_factory';
-import type { PFrameReadAPIV8 } from './api_read';
+import type { PFrameFactoryAPIV2, PFrameFactoryAPIV3 } from './api_factory';
+import type { PFrameReadAPIV8, PFrameReadAPIV9 } from './api_read';
 
 export type Logger = (
   level: 'info' | 'warn' | 'error',
@@ -7,3 +7,30 @@ export type Logger = (
 ) => void;
 
 export interface PFrameV9 extends PFrameFactoryAPIV2, PFrameReadAPIV8 {}
+
+export interface PFrameV10 extends PFrameFactoryAPIV3, PFrameReadAPIV9 {}
+
+export type PFrameOptions = {
+  /** Path to directory where PFrame can create temporary files */
+  spillPath: string;
+  /** Logger instance, no logging is performed when not provided */
+  logger?: Logger;
+}
+
+/** List of PFrame management functions exposed by PFrame module */
+export interface PFrameFactory {
+  /**
+   * Create a new PFrame instance.
+   * @warning Use concurrency limiting to avoid OOM crashes when multiple instances are simultaneously in use.
+   */
+  createPFrame(options: PFrameOptions): PFrameV10;
+
+  /**
+   * Dump active allocations from all PFrames instances in pprof format.
+   * The result of this function should be saved as `profile.pb.gz`.
+   * Use {@link https://pprof.me/} or {@link https://www.speedscope.app/}
+   * to view the allocation flamechart.
+   * @warning This method will always reject on Windows!
+   */
+  pprofDump: () => Promise<Uint8Array>;
+};

package/src/pframe/internal_api/table.ts

@@ -72,3 +72,68 @@ export interface PTableV6 {
   /** Deallocates all underlying resources */
   dispose(): void;
 }
+
+/**
+ * Table view returned as a result of create table operation.
+ *
+ * PTable can be thought as having a composite primary key, consisting of axes,
+ * and a set of data columns derived from PColumn values.
+ * */
+export interface PTableV7 extends Disposable {
+  /**
+   * Returns ordered array of table axes specs (primary key "columns" in SQL
+   * terms) and data column specs (regular "columns" in SQL terms).
+   *
+   * Data for a specific table column can be retrieved using unified indexing
+   * corresponding to elements in this array.
+   *
+   * Axes are always listed first.
+   * */
+  getSpec(): PTableColumnSpec[];
+
+  /** Transforms unified column identifiers into unified indices of columns. */
+  getColumnIndices(columnIds: PTableColumnId[]): number[];
+
+  /**
+   * Get PTable disk footprint in bytes
+   * Warning: This call materializes the join.
+   */
+  getFootprint(ops?: {
+    withPredecessors?: boolean,
+    signal?: AbortSignal,
+  }): Promise<number>;
+
+  /**
+   * Unified table shape
+   * Warning: This call materializes the join.
+   */
+  getShape(ops?: {
+    signal?: AbortSignal,
+  }): Promise<PTableShape>;
+
+  /**
+   * Retrieve the data from the table. To retrieve only data required, it can be
+   * sliced both horizontally ({@link columnIndices}) and vertically
+   * ({@link range}).
+   * This call materializes the join.
+   *
+   * @param columnIndices unified indices of columns to be retrieved
+   * @param range optionally limit the range of records to retrieve
+   * */
+  getData(
+    columnIndices: number[],
+    ops?: {
+      range?: TableRange,
+      signal?: AbortSignal,
+    },
+  ): Promise<PTableVector[]>;
+
+  /** Filters the table and returns new PTable instance */
+  filter(request: PTableRecordFilter[]): PTableV7;
+
+  /** Sorts the table and returns new PTable instance. */
+  sort(request: PTableSorting[]): PTableV7;
+
+  /** Deallocates all underlying resources */
+  dispose(): void;
+}