@oceanum/datamesh 0.5.2 → 0.6.3

package/dist/lib/cftime.d.ts

@@ -0,0 +1,127 @@
+/**
+ * cftime - CF Conventions time parsing for JavaScript
+ *
+ * Provides time-handling functionality for netCDF files that conform to the
+ * Climate and Forecasting (CF) conventions. This is a JavaScript port of the
+ * core functionality from Python's cftime library by Unidata.
+ *
+ * Currently supports Gregorian calendars only:
+ * - 'standard' / 'gregorian' (mixed Julian/Gregorian)
+ * - 'proleptic_gregorian'
+ *
+ * @see https://unidata.github.io/cftime/
+ * @see http://cfconventions.org/cf-conventions/cf-conventions
+ */
+/** Supported time units in CF conventions */
+export type CFTimeUnit = "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds";
+/** Supported calendar types (Gregorian only for now) */
+export type CFCalendar = "standard" | "gregorian" | "proleptic_gregorian";
+/** Parsed CF time units */
+export interface ParsedCFUnits {
+    /** The time unit (days, hours, etc.) */
+    unit: CFTimeUnit;
+    /** Reference date as JavaScript Date */
+    referenceDate: Date;
+    /** Reference date as milliseconds since Unix epoch */
+    referenceMs: number;
+    /** Original units string */
+    original: string;
+}
+/**
+ * Parse a CF time units string.
+ *
+ * @param units - CF time units string (e.g., "days since 1970-01-01")
+ * @returns Parsed units object
+ * @throws Error if units string is invalid
+ *
+ * @example
+ * ```ts
+ * const parsed = parseCFUnits("days since 1970-01-01");
+ * // { unit: "days", referenceDate: Date, referenceMs: 0, original: "..." }
+ *
+ * const parsed2 = parseCFUnits("hours since 2000-01-01 00:00:00");
+ * // { unit: "hours", referenceDate: Date, referenceMs: 946684800000, original: "..." }
+ * ```
+ */
+export declare function parseCFUnits(units: string): ParsedCFUnits;
+/**
+ * Convert numeric time value(s) to JavaScript Date object(s).
+ *
+ * @param times - Numeric time value or array of values
+ * @param units - CF time units string (e.g., "days since 1970-01-01")
+ * @param calendar - Calendar type (default: "standard")
+ * @returns Date object or array of Date objects
+ * @throws Error if calendar is not supported
+ *
+ * @example
+ * ```ts
+ * // Single value
+ * const date = num2date(0, "days since 1970-01-01");
+ * // Date: 1970-01-01T00:00:00.000Z
+ *
+ * // Array of values
+ * const dates = num2date([0, 1, 2], "days since 1970-01-01");
+ * // [Date: 1970-01-01, Date: 1970-01-02, Date: 1970-01-03]
+ *
+ * // Hours since reference
+ * const date2 = num2date(24, "hours since 2000-01-01");
+ * // Date: 2000-01-02T00:00:00.000Z
+ * ```
+ */
+export declare function num2date(times: number, units: string, calendar?: CFCalendar): Date;
+export declare function num2date(times: number[], units: string, calendar?: CFCalendar): Date[];
+export declare function num2date(times: Float64Array | Float32Array | Int32Array, units: string, calendar?: CFCalendar): Date[];
+/**
+ * Convert JavaScript Date object(s) to numeric time value(s).
+ *
+ * @param dates - Date object or array of Date objects
+ * @param units - CF time units string (e.g., "days since 1970-01-01")
+ * @param calendar - Calendar type (default: "standard")
+ * @returns Numeric time value or array of values
+ * @throws Error if calendar is not supported
+ *
+ * @example
+ * ```ts
+ * // Single value
+ * const num = date2num(new Date("1970-01-02"), "days since 1970-01-01");
+ * // 1
+ *
+ * // Array of values
+ * const nums = date2num([new Date("1970-01-01"), new Date("1970-01-02")], "days since 1970-01-01");
+ * // [0, 1]
+ * ```
+ */
+export declare function date2num(dates: Date, units: string, calendar?: CFCalendar): number;
+export declare function date2num(dates: Date[], units: string, calendar?: CFCalendar): number[];
+/**
+ * Check if a calendar type is supported.
+ *
+ * @param calendar - Calendar type string
+ * @returns true if the calendar is supported
+ */
+export declare function isCalendarSupported(calendar: string): boolean;
+/**
+ * Get the list of supported calendars.
+ *
+ * @returns Array of supported calendar names
+ */
+export declare function getSupportedCalendars(): string[];
+/**
+ * Check if attributes indicate CF time units.
+ * CF time units follow the pattern: "<unit> since <reference_time>"
+ *
+ * @param attrs - Variable attributes record
+ * @returns true if the attributes contain valid CF time units
+ */
+export declare function hasCFTimeUnits(attrs: Record<string, unknown>): boolean;
+/**
+ * Convert CF time values to Unix timestamp (seconds since 1970-01-01).
+ * Used for lazy conversion when accessing zarr data with CF time units.
+ *
+ * @param data - Array of numeric time values
+ * @param units - CF time units string (e.g., "days since 1970-01-01")
+ * @param calendar - CF calendar type (defaults to "standard")
+ * @returns Float64Array of Unix timestamps in seconds, or null if calendar unsupported
+ */
+export declare function cftimeToUnixSeconds(data: ArrayLike<number | bigint>, units: string, calendar?: string): Float64Array | null;
+//# sourceMappingURL=cftime.d.ts.map

package/dist/lib/cftime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cftime.d.ts","sourceRoot":"","sources":["../../src/lib/cftime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,6CAA6C;AAC7C,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,OAAO,GACP,SAAS,GACT,SAAS,GACT,cAAc,GACd,cAAc,CAAC;AAEnB,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,qBAAqB,CAAC;AAE1E,2BAA2B;AAC3B,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,IAAI,EAAE,UAAU,CAAC;IACjB,wCAAwC;IACxC,aAAa,EAAE,IAAI,CAAC;IACpB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAkDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAgCzD;AAwDD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,UAAU,GACpB,IAAI,CAAC;AACR,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,EAAE,EACf,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,UAAU,GACpB,IAAI,EAAE,CAAC;AACV,wBAAgB,QAAQ,CACtB,KAAK,EAAE,YAAY,GAAG,YAAY,GAAG,UAAU,EAC/C,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,UAAU,GACpB,IAAI,EAAE,CAAC;AAmCV;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,IAAI,EACX,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,UAAU,GACpB,MAAM,CAAC;AACV,wBAAgB,QAAQ,CACtB,KAAK,EAAE,IAAI,EAAE,EACb,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,UAAU,GACpB,MAAM,EAAE,CAAC;AA8BZ;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAGtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAChC,KAAK,EAAE,MAAM,EACb,QAAQ,SAAa,GACpB,YAAY,GAAG,IAAI,CAqBrB"}

package/dist/lib/connector.d.ts

@@ -0,0 +1,142 @@
+import { Datasource } from './datasource';
+import { IQuery, Stage } from './query';
+import { Dataset, HttpZarr, TempZarr } from './datamodel';
+import { Session } from './session';
+export declare class Connector {
+    static LAZY_LOAD_SIZE: number;
+    private _token;
+    private _host;
+    private _authHeaders;
+    private _gateway;
+    private _nocache;
+    private _isV1;
+    private _sessionParams;
+    private _currentSession;
+    service?: string;
+    gateway?: string;
+    /**
+     * Datamesh connector constructor
+     *
+     * @param token - Your datamesh access token. Defaults to environment variable DATAMESH_TOKEN is defined else as literal string "DATAMESH_TOKEN". DO NOT put your Datamesh token directly into public facing browser code.
+     * @param options - Constructor options.
+     * @param options.service - URL of datamesh service. Defaults to environment variable DATAMESH_SERVICE or "https://datamesh.oceanum.io".
+     * @param options.gateway - URL of gateway service. Defaults to "https://gateway.<datamesh_service_domain>".
+     * @param options.jwtAuth - JWT for Oceanum service.
+     * @param options.nocache - Disable caching of datamesh results.
+     * @param options.sessionDuration - The desired length of time for acquired datamesh sessions in hours. Will be 1 hour by default.
+     *
+     * @throws {Error} - If a valid token is not provided.
+     */
+    constructor(token?: string, options?: {
+        service?: string;
+        gateway?: string;
+        jwtAuth?: string;
+        nocache?: boolean;
+        sessionDuration?: number;
+    });
+    /**
+     * Check if the API version supports sessions.
+     *
+     * @private
+     */
+    private _checkApiVersion;
+    /**
+     * Get datamesh host.
+     *
+     * @returns The datamesh server host.
+     */
+    get host(): string;
+    /**
+     * Check the status of the metadata server.
+     *
+     * @returns True if the server is up, false otherwise.
+     */
+    status(): Promise<boolean>;
+    /**
+     * Validate response from server.
+     *
+     * @param response - The response object to validate.
+     * @throws {Error} - If the response contains an error status code.
+     */
+    private validateResponse;
+    /**
+     * Create a new session.
+     *
+     * @param options - Session options.
+     * @param options.duration - The desired length of time for the session in hours. Defaults to the value set in the constructor or 1 hour.
+     * @returns A new session instance.
+     */
+    createSession(options?: {
+        duration?: number;
+    }): Promise<Session>;
+    /**
+     * Get the current session or create a new one if none exists.
+     *
+     * @returns The current session.
+     */
+    getSession(): Promise<Session>;
+    /**
+     * Get headers with session information if available.
+     *
+     * @param additionalHeaders - Additional headers to include.
+     * @returns Headers with session information.
+     */
+    private getSessionHeaders;
+    /**
+     * Request metadata from datamesh.
+     *
+     * @param datasourceId - The ID of the datasource to request.
+     * @param params - Additional parameters for the request.
+     * @returns The response from the server.
+     */
+    private metadataRequest;
+    /**
+     * Request data from datamesh.
+     *
+     * @param datasourceId - The ID of the datasource to request.
+     * @param dataFormat - The format of the requested data. Defaults to "application/json".
+     * @returns The path to the cached file.
+     */
+    private dataRequest;
+    /**
+     * Stage a query to the datamesh.
+     *
+     * @param query - The query to stage.
+     * @returns The staged response.
+     */
+    stageRequest(query: IQuery): Promise<Stage | null>;
+    /**
+     * Execute a query to the datamesh.
+     *
+     * @param query - The query to execute.
+     * @param options.timeout - Additional options for the query.
+     * @returns The response from the server.
+     */
+    query(query: IQuery, options?: {
+        timeout?: number;
+    }): Promise<Dataset<HttpZarr | TempZarr> | null>;
+    /**
+     * Get a datasource instance from the datamesh.
+     *
+     * @param datasourceId - Unique datasource ID.
+     * @returns The datasource instance.
+     * @throws {Error} - If the datasource cannot be found or is not authorized.
+     */
+    getDatasource(datasourceId: string): Promise<Datasource>;
+    /**
+     * Load a datasource into the work environment.
+     *
+     * @param datasourceId - Unique datasource ID.
+     * @param parameters - Additional datasource parameters.
+     * @returns The dataset.
+     */
+    loadDatasource(datasourceId: string, parameters?: Record<string, string | number>): Promise<Dataset<HttpZarr | TempZarr> | null>;
+    /**
+     * Close the current session if one exists.
+     *
+     * @param finaliseWrite - Whether to finalise any write operations. Defaults to false.
+     * @returns A promise that resolves when the session is closed.
+     */
+    closeSession(finaliseWrite?: boolean): Promise<void>;
+}
+//# sourceMappingURL=connector.d.ts.map

package/dist/lib/connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../src/lib/connector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG1D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC,qBAAa,SAAS;IACpB,MAAM,CAAC,cAAc,SAAO;IAC5B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,YAAY,CAAyB;IAC7C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,cAAc,CAA8B;IACpD,OAAO,CAAC,eAAe,CAAwB;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;;;;;;OAYG;gBAED,KAAK,SAEgB,EACrB,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B;IA2CH;;;;OAIG;YACW,gBAAgB;IAqB9B;;;;OAIG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAOhC;;;;;OAKG;YACW,gBAAgB;IAa9B;;;;;;OAMG;IACG,aAAa,CAAC,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ1E;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAOpC;;;;;OAKG;YACW,iBAAiB;IAiB/B;;;;;;OAMG;YACW,eAAe;IAsB7B;;;;;;OAMG;YACW,WAAW;IAYzB;;;;;OAKG;IAEG,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IAqBxD;;;;;;OAMG;IAEG,KAAK,CACT,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GACjC,OAAO,CAAC,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,GAAG,IAAI,CAAC;IAwC/C;;;;;;OAMG;IAEG,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAU9D;;;;;;OAMG;IAEG,cAAc,CAClB,YAAY,EAAE,MAAM,EACpB,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAM,GAC/C,OAAO,CAAC,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,GAAG,IAAI,CAAC;IAM/C;;;;;OAKG;IACG,YAAY,CAAC,aAAa,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAMzD"}

package/dist/lib/datamodel.d.ts

@@ -0,0 +1,227 @@
+import { DataType, Location, Listable } from '@zarrita/core';
+import { Mutable, AsyncReadable } from '@zarrita/storage';
+import { Slice } from '@zarrita/indexing';
+import { Table } from 'apache-arrow';
+import { Geometry, Feature, FeatureCollection } from 'geojson';
+import { CachedHTTPStore } from './zarr';
+import { Schema, Coordkeys } from './datasource';
+import * as zarr from "@zarrita/core";
+export type ATypedArray = Int8Array | Int16Array | Int32Array | BigInt64Array | Uint8Array | Uint16Array | Uint32Array | BigUint64Array | Float32Array | Float64Array;
+export type Scalar = string | number | boolean;
+export type NDArray = Scalar[] | Scalar[][] | Scalar[][][] | Scalar[][][][] | ATypedArray[] | ATypedArray[][] | ATypedArray[][][] | ATypedArray[][][][];
+export type Data = NDArray | ATypedArray | Scalar;
+/**
+ * Represents a data variable.
+ */
+export type DataVariable = {
+    /**
+     * Attributes of the variable.
+     */
+    attributes: Record<string, string | unknown>;
+    /**
+     * Dimensions of the variable
+     *  */
+    dimensions: string[];
+    /**
+     * Datatype of the variable.
+     */
+    dtype?: DataType;
+    /**
+     * Data associated with the variable.
+     */
+    data?: Data;
+    /**
+     * Chunk sizes for the variable dimensions.
+     * If not specified, uses the global chunk configuration or defaults to the full shape.
+     */
+    chunks?: number[];
+};
+/**
+ * Configuration for chunking when writing zarr data.
+ */
+export type ChunkConfig = {
+    /**
+     * Global chunk sizes by dimension name.
+     * These apply to all variables unless overridden per-variable.
+     */
+    dimensions?: Record<string, number>;
+    /**
+     * Per-variable chunk size overrides.
+     * Keys are variable names, values are arrays of chunk sizes matching the variable dimensions.
+     */
+    variables?: Record<string, number[]>;
+};
+/**
+ * Options for writing dataset to zarr format.
+ */
+export type ZarrWriteOptions = {
+    /**
+     * Chunk configuration for the output zarr.
+     */
+    chunks?: ChunkConfig;
+    /**
+     * Whether to consolidate metadata (zarr v2 compatible).
+     */
+    consolidated?: boolean;
+};
+export declare const wkb_to_geojson: (wkb: string) => any;
+/** @ignore */
+export type HttpZarr = Location<Listable<CachedHTTPStore>>;
+/** @ignore */
+export type TempZarr = Location<Mutable>;
+type SliceDef = (null | Slice | number)[] | null | undefined;
+/**
+ * Represents a data variable within a dataset.
+ */
+export declare class DataVar<
+/** @ignore */
+DType extends DataType, S extends TempZarr | HttpZarr> {
+    /**
+     * Creates an instance of DataVar.
+     * @param id - The identifier for the data variable.
+     * @param dimensions - The dimensions associated with the data variable.
+     * @param attributes - The attributes of the data variable, represented as a record of key-value pairs.
+     * @param arr - The zarr array associated with the data variable.
+     */
+    id: string;
+    dimensions: string[];
+    attributes: Record<string, unknown>;
+    arr: S extends TempZarr ? zarr.Array<DType, Mutable> : zarr.Array<DType, AsyncReadable>;
+    constructor(id: string, dimensions: string[], attributes: Record<string, unknown>, arr: S extends TempZarr ? zarr.Array<DType, Mutable> : zarr.Array<DType, AsyncReadable>);
+    /**
+     * Retrieves the data from the zarr array. If the data is already cached, it returns the cached data.
+     * @param index - Optional slice parameters to retrieve specific data from the zarr array.
+     * @returns A promise that resolves to the data of the zarr array.
+     */
+    get(index?: SliceDef | string[]): Promise<Data>;
+}
+/**
+ * Represents a dataset with dimensions, data variables, and attributes.
+ * Implements the DatasetApi interface.
+ */
+export interface ZarrOptions {
+    parameters?: Record<string, string | number>;
+    chunks?: string;
+    downsample?: Record<string, number>;
+    coordkeys?: Coordkeys;
+    timeout?: number;
+    /**
+     * @deprecated Use `ttl: 0` instead to disable caching
+     */
+    nocache?: boolean;
+    /**
+     * Time to live for cache entries in seconds.
+     * - If undefined, cache never expires
+     * - If 0, caching is disabled entirely
+     * - If > 0, cache will be invalidated after this many seconds
+     */
+    ttl?: number;
+}
+export declare class Dataset<S extends HttpZarr | TempZarr> {
+    /**
+     * Creates an instance of Dataset.
+     * @param dimensions - The dimensions of the dataset.
+     * @param variables - The data variables of the dataset.
+     * @param attributes - The attributes of the dataset.
+     * @param root - The root group of the dataset.
+     * @param coordkeys - The coordinates map of the dataset.
+     */
+    dimensions: Record<string, number>;
+    variables: S extends TempZarr ? Record<string, DataVar<DataType, TempZarr>> : Record<string, DataVar<DataType, HttpZarr>>;
+    attributes: Record<string, unknown>;
+    coordkeys: Coordkeys;
+    root: S;
+    constructor(dimensions: Record<string, number>, variables: S extends TempZarr ? Record<string, DataVar<DataType, TempZarr>> : Record<string, DataVar<DataType, HttpZarr>>, attributes: Record<string, unknown>, coordkeys: Coordkeys, root: S);
+    /**
+     * Creates a Dataset instance from a Zarr store.
+     * @param url - The URL of the datamesh gateway.
+     * @param authHeaders - The authentication headers.
+     * @param options.chunks - Optional chunking for the request.
+     * @param options.downsample - Optional downsample parameters for the request.
+     * @param options.parameters - Optional parameters for the request.
+     * @param options.coordkeys - Optional coordinates for the request.
+     * @param options.timeout - Optional timeout for the request.
+     * @param options.nocache - Disable caching
+     * @returns A promise that resolves to a Dataset instance.
+     */
+    static zarr(url: string, authHeaders: Record<string, string>, options?: ZarrOptions): Promise<Dataset<HttpZarr>>;
+    static fromArrow(data: Table, coordkeys: Coordkeys): Promise<Dataset<TempZarr>>;
+    static fromGeojson(geojson: FeatureCollection | Feature, coordkeys?: Coordkeys): Promise<Dataset<TempZarr>>;
+    /**
+     * Initializes an in memory Dataset instance from a data object.
+     * @param datasource - An object containing id, dimensions, data variables, and attributes.
+     * @param coordkeys - Optional coordinate key mappings.
+     * @param chunkConfig - Optional chunk configuration for global and per-variable chunking.
+     */
+    static init(datasource: Schema, coordkeys?: Coordkeys, chunkConfig?: ChunkConfig): Promise<Dataset<TempZarr>>;
+    /**
+     * Converts the dataset into a dataframe format.
+     *
+     * @returns {Promise<Record<string, unknown>[]>} A promise that resolves to an array of records,
+     * where each record represents a row in the dataframe.
+     *
+     * @remarks
+     * This method iterates over the data variables, retrieves their dimensions and data,
+     * and then flattens the data into a dataframe structure.
+     * Time coordinates are converted to IDO8601 format.
+     * BigInt datatypes are coerced to number.
+     *
+     * @example
+     * ```typescript
+     * const dataframe = await instance.asDataframe();
+     * console.log(dataframe);
+     * ```
+     */
+    asDataframe(): Promise<Record<string, unknown>[]>;
+    /**
+     * Converts the dataset into a GeoJSON Feature.
+     * @param geometry - Optional GeoJSON geometry to apply to all records, otherwise geometry column is required. Will override geometry column if present.
+     *
+     * @returns {Promise<FeatureCollection>} A promise that resolves to an array of records,
+     * where each record represents a row in the dataframe.
+     *
+     * @throws Will throw an error if no geometry is found in data or as a parameter
+     *
+     * @remarks
+     * This method iterates over the data variables, retrieves their dimensions and data,
+     * and then flattens the data into a dataframe structure.
+     *
+     * @example
+     * ```typescript
+     * const dataframe = await instance.asDataframe();
+     * console.log(dataframe);
+     * ```
+     */
+    asGeojson(geometry?: Geometry): Promise<FeatureCollection>;
+    /**
+     * Asynchronously assigns data to a variable in the dataset.
+     *
+     * @param varid - The identifier for the variable.
+     * @param dims - An array of dimension names corresponding to the data.
+     * @param data - The data to be assigned, which can be a multi-dimensional array.
+     * @param attrs - Optional. A record of attributes to be associated with the variable.
+     * @param dtype - Optional. The data type of the data.
+     * @param chunks - Optional. An array specifying the chunk sizes for the data.
+     *
+     * @returns A promise that resolves when the data has been successfully assigned.
+     * @throws Will throw an error if the shape of the data does not match the provided dimensions.
+     * @throws Will throw an error if an existing dimension size does not match the new data.
+     */
+    assign(varid: string, dims: string[], data: Data, attrs?: Record<string, unknown>, dtype?: DataType, chunks?: number[]): Promise<void>;
+    /**
+     * Exports the dataset to a zarr format represented as a Map of path-to-data.
+     * This can be used for serialization or writing to a zarr store.
+     *
+     * @param options - Optional configuration for the zarr output.
+     * @returns A promise that resolves to a Map containing the zarr store data.
+     *
+     * @example
+     * ```typescript
+     * const zarrStore = await dataset.toZarr();
+     * // zarrStore is a Map<string, Uint8Array>
+     * ```
+     */
+    toZarr(options?: ZarrWriteOptions): Promise<Map<string, Uint8Array>>;
+}
+export {};
+//# sourceMappingURL=datamodel.d.ts.map

package/dist/lib/datamodel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datamodel.d.ts","sourceRoot":"","sources":["../../src/lib/datamodel.ts"],"names":[],"mappings":"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"}

package/dist/lib/datasource.d.ts

@@ -0,0 +1,117 @@
+import { Geometry } from 'geojson';
+import { default as dayjs } from 'dayjs';
+import { default as duration } from 'dayjs/plugin/duration';
+import { DataVariable } from './datamodel';
+export type Coordinate = "s" | "e" | "b" | "c" | "q" | "n" | "m" | "t" | "z" | "y" | "x" | "g" | "f" | "d" | "i" | "j" | "k";
+export type Coordkeys = {
+    [key in Coordinate]?: string;
+};
+/**
+ * Represents the internal schema of a data source.
+ */
+export type Schema = {
+    /**
+     * Attributes of the schema.
+     */
+    attributes?: Record<string, string | number>;
+    /**
+     * Dimensions of the schema.
+     */
+    dimensions: Record<string, number>;
+    /**
+     * Coordinate map of the schema.
+     */
+    coordkeys?: Coordkeys;
+    /**
+     * Data variables of the schema.
+     */
+    variables: Record<string, DataVariable>;
+};
+/**
+ * Datamesh schema
+ */
+export type DatameshSchema = {
+    /**
+     * Attributes of the schema.
+     */
+    attrs?: Record<string, string | number>;
+    /**
+     * Dimensions of the schema.
+     */
+    dims: Record<string, number>;
+    /**
+     * Coordinate map of the schema.
+     */
+    coords?: Record<string, DatameshSchema>;
+    /**
+     * Data variables of the schema.
+     */
+    data_vars?: Record<string, DatameshSchema>;
+};
+/**
+ * Represents a data source.
+ */
+export type Datasource = {
+    /**
+     * Unique identifier for the data source.
+     */
+    id: string;
+    /**
+     * Name of the data source.
+     */
+    name: string;
+    /**
+     * Description of the data source.
+     */
+    description?: string;
+    /**
+     * Parameters associated with the data source.
+     */
+    parameters?: Record<string, string | number>;
+    /**
+     * Geometric representation of the data source.
+     */
+    geom?: Geometry;
+    /**
+     * Start time for the data source.
+     */
+    tstart?: dayjs.Dayjs;
+    /**
+     * End time for the data source.
+     */
+    tend?: dayjs.Dayjs;
+    /**
+     * Forecast time period for the data source.
+     */
+    pforecast?: duration.Duration;
+    /**
+     * Archive time period for the data source.
+     */
+    parchive?: duration.Duration;
+    /**
+     * Tags associated with the data source.
+     */
+    tags?: string[];
+    /**
+     * Additional information about the data source.
+     */
+    info?: Record<string, unknown>;
+    /**
+     * Schema information for the data source.
+     */
+    schema: DatameshSchema;
+    /**
+     * Coordinate map for the data source.
+     */
+    coordinates: Coordkeys;
+    /**
+     * Additional details about the data source.
+     */
+    details?: string;
+    /**
+     * Last modified date of the data source.
+     */
+    last_modified?: Date;
+    driver: string;
+};
+//# sourceMappingURL=datasource.d.ts.map

package/dist/lib/datasource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datasource.d.ts","sourceRoot":"","sources":["../../src/lib/datasource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,QAAQ,MAAM,uBAAuB,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,UAAU,GAClB,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,CAAC;AAER,MAAM,MAAM,SAAS,GAAG;KACrB,GAAG,IAAI,UAAU,CAAC,CAAC,EAAE,MAAM;CAC7B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IAE7C;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEnC;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACzC,CAAC;AAEF;;GAEG;AAEH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IAExC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAExC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC5C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IAE7C;;OAEG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAEhB;;OAEG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC;IAErB;;OAEG;IACH,IAAI,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC;IAEnB;;OAEG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC;IAE7B;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE/B;;OAEG;IACH,MAAM,EAAE,cAAc,CAAC;IAEvB;;OAEG;IACH,WAAW,EAAE,SAAS,CAAC;IAEvB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,aAAa,CAAC,EAAE,IAAI,CAAC;IAErB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC"}

package/dist/lib/observe.d.ts

@@ -0,0 +1,3 @@
+/** @ignore */
+export declare function measureTime(target: any, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor;
+//# sourceMappingURL=observe.d.ts.map

package/dist/lib/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/lib/observe.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,wBAAgB,WAAW,CACzB,MAAM,EAAE,GAAG,EACX,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,kBAAkB,sBAgB/B"}