@lazarusa/netcdf4-wasm-test 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 netcdf4-wasm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,386 @@
+# netcdf4-wasm
+
+NetCDF4 library compiled to WebAssembly with JavaScript/TypeScript bindings.
+
+## Overview
+
+This project provides a complete WebAssembly port of the NetCDF4 C library, enabling NetCDF file operations in browser and Node.js environments. It includes:
+
+- Complete NetCDF4 C library compiled to WASM using Emscripten
+- High-level TypeScript/JavaScript API
+- Support for reading and writing NetCDF4 files
+- Comprehensive test suite
+
+## Installation
+
+```bash
+npm install netcdf4-wasm
+```
+
+## Prerequisites
+
+For building from source, you'll need:
+
+- Emscripten SDK
+- CMake
+- Make
+- wget or curl
+
+Check dependencies:
+
+```bash
+npm run check-deps
+```
+
+Install Emscripten locally:
+
+```bash
+npm run install-emscripten
+```
+
+## Usage
+
+The JavaScript API is modeled closely on the [netcdf4-python](https://unidata.github.io/netcdf4-python) API.
+
+### Basic Example
+
+```typescript
+import { Dataset } from "netcdf4-wasm";
+// or: import { NetCDF4 } from 'netcdf4-wasm';
+
+async function example() {
+  // Create a new NetCDF file (similar to Python netCDF4.Dataset)
+  const nc = await Dataset("example.nc", "w", { format: "NETCDF4" });
+  // or: const nc = await NetCDF4.Dataset('example.nc', 'w', { format: 'NETCDF4' });
+
+  // Create dimensions
+  const lat = await nc.createDimension("lat", 73);
+  const lon = await nc.createDimension("lon", 144);
+  const time = await nc.createDimension("time", null); // unlimited dimension
+
+  // Create variables
+  const temp = await nc.createVariable("temperature", "f4", [
+    "time",
+    "lat",
+    "lon",
+  ]);
+  const times = await nc.createVariable("time", "f8", ["time"]);
+
+  // Set variable attributes
+  temp.units = "Kelvin";
+  temp.long_name = "surface temperature";
+  times.units = "hours since 0001-01-01 00:00:00.0";
+  times.calendar = "gregorian";
+
+  // Set global attributes
+  nc.setncattr("description", "bogus example script");
+  nc.setncattr("history", "Created " + new Date().toISOString());
+  nc.setncattr("source", "netCDF4-wasm example");
+
+  // Write data
+  const tempData = new Float64Array(73 * 144);
+  tempData.fill(288.0); // Fill with 288K
+  await temp.setValue(tempData);
+
+  // Close the file
+  await nc.close();
+}
+```
+
+### Reading Files
+
+```typescript
+import { Dataset } from "netcdf4-wasm";
+
+async function readExample() {
+  // Open existing file for reading
+  const nc = await Dataset("data.nc", "r");
+
+  // Access dimensions
+  console.log("Dimensions:", Object.keys(nc.dimensions));
+  console.log("Time dimension size:", nc.dimensions.time.size);
+
+  // Access variables
+  console.log("Variables:", Object.keys(nc.variables));
+  const temp = nc.variables.temperature;
+
+  // Read variable attributes
+  console.log("Temperature units:", temp.units);
+  console.log("Temperature long name:", temp.long_name);
+
+  // Read data
+  const data = await temp.getValue();
+  console.log("Temperature data shape:", data.length);
+  console.log("First few values:", data.slice(0, 5));
+
+  // Access global attributes
+  console.log("Global attributes:", nc.ncattrs());
+  console.log("Description:", nc.getncattr("description"));
+
+  await nc.close();
+}
+```
+
+### Alternative Constructor (Direct Instantiation)
+
+```typescript
+import { NetCDF4 } from "netcdf4-wasm";
+
+async function directExample() {
+  // Direct instantiation (requires manual initialization)
+  const nc = new NetCDF4("example.nc", "w", { format: "NETCDF4" });
+  await nc.initialize();
+
+  // Use same API as above...
+  const lat = await nc.createDimension("lat", 10);
+  const temp = await nc.createVariable("temperature", "f8", ["lat"]);
+
+  await nc.close();
+}
+```
+
+### Working with Groups
+
+```typescript
+async function groupExample() {
+  const nc = await Dataset("grouped.nc", "w", { format: "NETCDF4" });
+
+  // Create a group
+  const forecasts = nc.createGroup("forecasts");
+
+  // Create dimensions and variables in the group
+  const time = await forecasts.createDimension("time", 24);
+  const temp = await forecasts.createVariable("temperature", "f4", ["time"]);
+
+  // Set group attributes
+  forecasts.setncattr("description", "Forecast data");
+
+  await nc.close();
+}
+```
+
+## API Reference
+
+The API closely follows netcdf4-python conventions for ease of use by scientists familiar with Python.
+
+### Classes
+
+#### `NetCDF4`
+
+Main class for NetCDF file operations, similar to `netCDF4.Dataset` in Python.
+
+**Constructor**
+
+```typescript
+new NetCDF4(filename?: string, mode?: string, options?: NetCDF4WasmOptions)
+```
+
+**Static Methods**
+
+- `NetCDF4.Dataset(filename: string, mode?: string, options?: object): Promise<NetCDF4>` - Factory method (Python-like)
+
+**Module Functions**
+
+- `Dataset(filename: string, mode?: string, options?: object): Promise<NetCDF4>` - Convenience function (import directly)
+
+**Properties**
+
+- `dimensions: {[name: string]: Dimension}` - Dictionary of dimensions
+- `variables: {[name: string]: Variable}` - Dictionary of variables
+- `groups: {[name: string]: Group}` - Dictionary of groups
+- `file_format: string` - File format (e.g., 'NETCDF4')
+- `filepath: string` - Path to the file
+- `isopen: boolean` - Whether file is currently open
+
+**Methods**
+
+_File Operations_
+
+- `initialize(): Promise<void>` - Initialize the WASM module
+- `close(): Promise<void>` - Close the file
+- `sync(): Promise<void>` - Flush data to disk
+
+_Structure Definition_
+
+- `createDimension(name: string, size: number): Promise<Dimension>` - Create dimension
+- `createVariable(name: string, datatype: string, dimensions: string[], options?: object): Promise<Variable>` - Create variable
+- `createGroup(name: string): Group` - Create hierarchical group
+
+_Attribute Access_
+
+- `setncattr(name: string, value: any): void` - Set global attribute
+- `getncattr(name: string): any` - Get global attribute
+- `ncattrs(): string[]` - List all global attributes
+
+#### `Variable`
+
+Represents a NetCDF variable, similar to Python's Variable class.
+
+**Properties**
+
+- `name: string` - Variable name
+- `datatype: string` - Data type ('f4', 'f8', 'i4', etc.)
+- `dimensions: string[]` - Dimension names
+- `units: string` - Units attribute (convenience property)
+- `long_name: string` - Long name attribute (convenience property)
+- `standard_name: string` - Standard name attribute (convenience property)
+
+**Methods**
+
+- `getValue(): Promise<Float64Array>` - Read variable data
+- `setValue(data: Float64Array): Promise<void>` - Write variable data
+- `setncattr(name: string, value: any): void` - Set variable attribute
+- `getncattr(name: string): any` - Get variable attribute
+- `ncattrs(): string[]` - List variable attributes
+
+#### `Dimension`
+
+Represents a NetCDF dimension.
+
+**Properties**
+
+- `name: string` - Dimension name
+- `size: number` - Dimension size
+- `isUnlimited: boolean` - Whether dimension is unlimited
+
+**Methods**
+
+- `__len__(): number` - Get dimension size (Python-like)
+
+### Constants
+
+The `NC_CONSTANTS` object provides NetCDF constants:
+
+```typescript
+NC_CONSTANTS.NC_NOERR; // No error
+NC_CONSTANTS.NC_NOWRITE; // Read-only access
+NC_CONSTANTS.NC_WRITE; // Write access
+NC_CONSTANTS.NC_CLOBBER; // Overwrite existing file
+NC_CONSTANTS.NC_NETCDF4; // NetCDF4 format
+NC_CONSTANTS.NC_DOUBLE; // Double data type
+NC_CONSTANTS.NC_UNLIMITED; // Unlimited dimension
+```
+
+## Building
+
+### Install dependencies
+
+```bash
+npm install
+```
+
+### Check build dependencies
+
+```bash
+npm run check-deps
+```
+
+### Build the project
+
+```bash
+npm run build
+```
+
+This will:
+
+1. Download and compile zlib, HDF5, and NetCDF4 C libraries
+2. Create the WASM module with Emscripten
+3. Compile TypeScript bindings
+
+### Clean build artifacts
+
+```bash
+npm run clean
+```
+
+## Testing
+
+Run tests:
+
+```bash
+npm test
+```
+
+Run tests with coverage:
+
+```bash
+npm run test:coverage
+```
+
+Watch mode:
+
+```bash
+npm run test:watch
+```
+
+## Development
+
+### Project Structure
+
+```
+netcdf4-wasm/
+├── src/                    # TypeScript source code
+│   ├── index.ts           # Main API exports
+│   ├── types.ts           # Type definitions
+│   ├── constants.ts       # NetCDF constants
+│   ├── netcdf4.ts         # Main NetCDF4 class
+│   ├── group.ts           # Group class
+│   ├── variable.ts        # Variable class
+│   ├── dimension.ts       # Dimension class
+│   ├── wasm-module.ts     # WASM module loader
+│   └── __tests__/         # Test files
+├── scripts/               # Build scripts
+│   ├── build-wasm.sh     # Main WASM build script
+│   ├── check-dependencies.sh
+│   └── install-emscripten.sh
+├── bindings/              # WASM bindings
+│   ├── pre.js            # Pre-run JavaScript
+│   └── post.js           # Post-run JavaScript
+├── build/                 # Build artifacts (generated)
+├── dist/                  # Distribution files (generated)
+└── package.json
+```
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Run the test suite
+6. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## NetCDF4 Documentation
+
+For more information about NetCDF4, visit: https://docs.unidata.ucar.edu/netcdf-c/current/
+
+## Troubleshooting
+
+### WASM Module Not Found
+
+Make sure the WASM files are properly built and accessible:
+
+```bash
+npm run build:wasm
+```
+
+### Emscripten Not Found
+
+Install Emscripten:
+
+```bash
+npm run install-emscripten
+source build/emsdk/emsdk_env.sh
+```
+
+### Memory Issues
+
+If you encounter memory-related errors, try increasing the initial memory:
+
+```typescript
+const netcdf = new NetCDF4({ memoryInitialPages: 512 });
+```

package/dist/constants.d.ts

@@ -0,0 +1,20 @@
+export declare const NC_CONSTANTS: {
+    NC_NOERR: number;
+    NC_NOWRITE: number;
+    NC_WRITE: number;
+    NC_CLOBBER: number;
+    NC_NOCLOBBER: number;
+    NC_NETCDF4: number;
+    NC_BYTE: number;
+    NC_CHAR: number;
+    NC_SHORT: number;
+    NC_INT: number;
+    NC_FLOAT: number;
+    NC_DOUBLE: number;
+    NC_UNLIMITED: number;
+    NC_GLOBAL: number;
+};
+export declare const DATA_TYPE_MAP: {
+    [key: string]: number;
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;CAsBxB,CAAC;AAGF,eAAO,MAAM,aAAa,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAalD,CAAC"}

package/dist/constants.js

@@ -0,0 +1,37 @@
+// NetCDF4 constants (populated from NetCDF4 headers)
+export const NC_CONSTANTS = {
+    // Error codes
+    NC_NOERR: 0,
+    // File modes
+    NC_NOWRITE: 0,
+    NC_WRITE: 1,
+    NC_CLOBBER: 0,
+    NC_NOCLOBBER: 4,
+    NC_NETCDF4: 4096,
+    // Data types
+    NC_BYTE: 1,
+    NC_CHAR: 2,
+    NC_SHORT: 3,
+    NC_INT: 4,
+    NC_FLOAT: 5,
+    NC_DOUBLE: 6,
+    // Special values
+    NC_UNLIMITED: -1000, // Use special value to distinguish from 0
+    NC_GLOBAL: -1,
+};
+// Data type mapping from string names to NetCDF constants
+export const DATA_TYPE_MAP = {
+    'f8': NC_CONSTANTS.NC_DOUBLE,
+    'f4': NC_CONSTANTS.NC_FLOAT,
+    'i4': NC_CONSTANTS.NC_INT,
+    'i2': NC_CONSTANTS.NC_SHORT,
+    'i1': NC_CONSTANTS.NC_BYTE,
+    'S1': NC_CONSTANTS.NC_CHAR,
+    'double': NC_CONSTANTS.NC_DOUBLE,
+    'float': NC_CONSTANTS.NC_FLOAT,
+    'int': NC_CONSTANTS.NC_INT,
+    'short': NC_CONSTANTS.NC_SHORT,
+    'byte': NC_CONSTANTS.NC_BYTE,
+    'char': NC_CONSTANTS.NC_CHAR
+};
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,qDAAqD;AAErD,MAAM,CAAC,MAAM,YAAY,GAAG;IACxB,cAAc;IACd,QAAQ,EAAE,CAAC;IAEX,aAAa;IACb,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,CAAC;IACX,UAAU,EAAE,CAAC;IACb,YAAY,EAAE,CAAC;IACf,UAAU,EAAE,IAAI;IAEhB,aAAa;IACb,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,CAAC;IACV,QAAQ,EAAE,CAAC;IACX,MAAM,EAAE,CAAC;IACT,QAAQ,EAAE,CAAC;IACX,SAAS,EAAE,CAAC;IAEZ,iBAAiB;IACjB,YAAY,EAAE,CAAC,IAAI,EAAE,0CAA0C;IAC/D,SAAS,EAAE,CAAC,CAAC;CAChB,CAAC;AAEF,0DAA0D;AAC1D,MAAM,CAAC,MAAM,aAAa,GAA8B;IACpD,IAAI,EAAE,YAAY,CAAC,SAAS;IAC5B,IAAI,EAAE,YAAY,CAAC,QAAQ;IAC3B,IAAI,EAAE,YAAY,CAAC,MAAM;IACzB,IAAI,EAAE,YAAY,CAAC,QAAQ;IAC3B,IAAI,EAAE,YAAY,CAAC,OAAO;IAC1B,IAAI,EAAE,YAAY,CAAC,OAAO;IAC1B,QAAQ,EAAE,YAAY,CAAC,SAAS;IAChC,OAAO,EAAE,YAAY,CAAC,QAAQ;IAC9B,KAAK,EAAE,YAAY,CAAC,MAAM;IAC1B,OAAO,EAAE,YAAY,CAAC,QAAQ;IAC9B,MAAM,EAAE,YAAY,CAAC,OAAO;IAC5B,MAAM,EAAE,YAAY,CAAC,OAAO;CAC/B,CAAC"}

package/dist/dimension.d.ts

@@ -0,0 +1,9 @@
+export declare class Dimension {
+    readonly name: string;
+    readonly size: number;
+    readonly isUnlimited: boolean;
+    constructor(name: string, size: number, isUnlimited?: boolean);
+    __len__(): number;
+    toString(): string;
+}
+//# sourceMappingURL=dimension.d.ts.map

package/dist/dimension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dimension.d.ts","sourceRoot":"","sources":["../src/dimension.ts"],"names":[],"mappings":"AAEA,qBAAa,SAAS;aAEE,IAAI,EAAE,MAAM;aACZ,IAAI,EAAE,MAAM;aACZ,WAAW,EAAE,OAAO;gBAFpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,WAAW,GAAE,OAAe;IAGhD,OAAO,IAAI,MAAM;IAIjB,QAAQ,IAAI,MAAM;CAIrB"}

package/dist/dimension.js

@@ -0,0 +1,19 @@
+// Dimension class similar to netcdf4-python
+export class Dimension {
+    name;
+    size;
+    isUnlimited;
+    constructor(name, size, isUnlimited = false) {
+        this.name = name;
+        this.size = size;
+        this.isUnlimited = isUnlimited;
+    }
+    __len__() {
+        return this.size;
+    }
+    toString() {
+        const sizeStr = this.isUnlimited ? 'unlimited' : this.size.toString();
+        return `<netCDF4.Dimension '${this.name}': size = ${sizeStr}>`;
+    }
+}
+//# sourceMappingURL=dimension.js.map

package/dist/dimension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dimension.js","sourceRoot":"","sources":["../src/dimension.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAE5C,MAAM,OAAO,SAAS;IAEE;IACA;IACA;IAHpB,YACoB,IAAY,EACZ,IAAY,EACZ,cAAuB,KAAK;QAF5B,SAAI,GAAJ,IAAI,CAAQ;QACZ,SAAI,GAAJ,IAAI,CAAQ;QACZ,gBAAW,GAAX,WAAW,CAAiB;IAC7C,CAAC;IAEJ,OAAO;QACH,OAAO,IAAI,CAAC,IAAI,CAAC;IACrB,CAAC;IAED,QAAQ;QACJ,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACtE,OAAO,uBAAuB,IAAI,CAAC,IAAI,aAAa,OAAO,GAAG,CAAC;IACnE,CAAC;CACJ"}

package/dist/group.d.ts

@@ -0,0 +1,33 @@
+import type { NetCDF4 } from './netcdf4.js';
+import { Dimension } from './dimension.js';
+import { Variable } from './variable.js';
+import type { VariableOptions } from './types.js';
+export declare class Group {
+    protected netcdf: NetCDF4;
+    readonly name: string;
+    protected groupId: number;
+    readonly dimensions: {
+        [name: string]: Dimension;
+    };
+    readonly variables: {
+        [name: string]: Variable;
+    };
+    readonly groups: {
+        [name: string]: Group;
+    };
+    private _attributes;
+    constructor(netcdf: NetCDF4, name: string, groupId: number);
+    setAttr(name: string, value: any): void;
+    getAttr(name: string): any;
+    attrs(): string[];
+    createDimension(name: string, size: number | null): Promise<Dimension>;
+    loadMockDimensions(): void;
+    createVariable(name: string, datatype: string, dimensions?: string[], options?: VariableOptions): Promise<Variable>;
+    createGroup(name: string): Group;
+    children(): {
+        [name: string]: Group;
+    };
+    get path(): string;
+    toString(): string;
+}
+//# sourceMappingURL=group.d.ts.map

package/dist/group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../src/group.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,qBAAa,KAAK;IAOV,SAAS,CAAC,MAAM,EAAE,OAAO;aACT,IAAI,EAAE,MAAM;IAC5B,SAAS,CAAC,OAAO,EAAE,MAAM;IAR7B,SAAgB,UAAU,EAAE;QAAE,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAM;IAC/D,SAAgB,SAAS,EAAE;QAAE,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAA;KAAE,CAAM;IAC7D,SAAgB,MAAM,EAAE;QAAE,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,CAAM;IACvD,OAAO,CAAC,WAAW,CAA8B;gBAGnC,MAAM,EAAE,OAAO,EACT,IAAI,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM;IAI7B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAcvC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG;IAgB1B,KAAK,IAAI,MAAM,EAAE;IAIX,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC;IAuBrE,kBAAkB,IAAI,IAAI;IA8B3B,cAAc,CAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,UAAU,GAAE,MAAM,EAAO,EACzB,OAAO,GAAE,eAAoB,GAC9B,OAAO,CAAC,QAAQ,CAAC;IAqCpB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK;IAQhC,QAAQ,IAAI;QAAE,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE;IAKrC,IAAI,IAAI,IAAI,MAAM,CAGjB;IAED,QAAQ,IAAI,MAAM;CAGrB"}