nodenetcdf 4.9.3 → 4.9.32

package/TYPESCRIPT.md

@@ -0,0 +1,211 @@
+# TypeScript Support
+
+This package includes TypeScript type definitions for full IntelliSense and type safety when using the NetCDF4 library in TypeScript projects.
+
+## Installation
+
+The type definitions are automatically included when you install the package:
+
+```bash
+npm install nodenetcdf
+```
+
+## Usage
+
+### Importing
+
+```typescript
+import { File, Group, Variable, Dimension, Attribute } from 'nodenetcdf';
+```
+
+### Type Definitions
+
+The package exports the following types:
+
+- **Classes**: `File`, `Group`, `Variable`, `Dimension`, `Attribute`
+- **Type Aliases**: `NetCDFDataType`, `FileMode`, `FileFormat`, `Endianness`, `ChecksumMode`, `ChunkMode`, `FillMode`
+
+### Example Usage
+
+```typescript
+import { File, NetCDFDataType } from 'nodenetcdf';
+
+// Create a new NetCDF file
+const file = new File('output.nc', 'c!', 'nodenetcdf');
+
+// Access the root group (fully typed)
+const root = file.root;
+
+// Add dimensions with type safety
+const timeDim = root.addDimension('time', 0);  // unlimited dimension
+const latDim = root.addDimension('lat', 180);
+const lonDim = root.addDimension('lon', 360);
+
+// Add variables with proper typing
+const tempVar = root.addVariable('temperature', 'float', [timeDim, latDim, lonDim]);
+
+// Set variable properties with autocomplete support
+tempVar.endianness = 'little';
+tempVar.compressionLevel = 6;
+tempVar.fillValue = -999.0;
+
+// Add attributes (type-checked)
+tempVar.addAttribute('units', 'string', 'degrees_C');
+tempVar.addAttribute('long_name', 'string', 'Air Temperature');
+
+// Write and read data with type safety
+tempVar.write(data);
+const retrievedData = tempVar.read();
+
+// Sync and close
+file.sync();
+file.close();
+```
+
+## Available Types
+
+### NetCDFDataType
+
+```typescript
+type NetCDFDataType = 
+  | 'byte'
+  | 'char'
+  | 'short'
+  | 'int'
+  | 'float'
+  | 'double'
+  | 'ubyte'
+  | 'ushort'
+  | 'uint'
+  | 'int64'
+  | 'string';
+```
+
+### FileMode
+
+```typescript
+type FileMode = 
+  | 'r'     // Read-only
+  | 'w'     // Read-write
+  | 'c'     // Create (no clobber)
+  | 'c!';   // Create (clobber/overwrite)
+```
+
+### FileFormat
+
+```typescript
+type FileFormat = 
+  | 'classic'           // Classic NetCDF format
+  | 'classic64'         // 64-bit offset format
+  | 'nodenetcdf'        // NetCDF-4 format
+  | 'nodenetcdfclassic'; // NetCDF-4 classic model
+```
+
+## API Documentation
+
+### File Class
+
+```typescript
+class File {
+  constructor(filename: string, mode: FileMode, format?: FileFormat);
+  readonly root: Group;
+  sync(): void;
+  close(): void;
+  inspect(): string;
+}
+```
+
+### Group Class
+
+```typescript
+class Group {
+  readonly id: number;
+  readonly variables: { [name: string]: Variable };
+  readonly dimensions: { [name: string]: Dimension };
+  readonly unlimited: Dimension | null;
+  readonly attributes: { [name: string]: Attribute };
+  readonly subgroups: { [name: string]: Group };
+  readonly name: string;
+  readonly fullname: string;
+  
+  addAttribute(name: string, type: NetCDFDataType, value: any): Attribute;
+  addDimension(name: string, length: number): Dimension;
+  addSubgroup(name: string): Group;
+  addVariable(name: string, type: NetCDFDataType, dimensions: (string | Dimension)[]): Variable;
+  inspect(): string;
+}
+```
+
+### Variable Class
+
+```typescript
+class Variable {
+  readonly id: number;
+  readonly type: NetCDFDataType;
+  readonly dimensions: Dimension[];
+  readonly attributes: { [name: string]: Attribute };
+  name: string;
+  endianness: Endianness;
+  checksumMode: ChecksumMode;
+  chunkMode: ChunkMode;
+  chunkSizes: number[];
+  fillMode: FillMode;
+  fillValue: any;
+  compressionShuffle: boolean;
+  compressionDeflate: boolean;
+  compressionLevel: number;
+  
+  read(): any;
+  readSlice(start: number[], count: number[]): any;
+  readStridedSlice(start: number[], count: number[], stride: number[]): any;
+  write(data: any): void;
+  writeSlice(start: number[], count: number[], data: any): void;
+  writeStridedSlice(start: number[], count: number[], stride: number[], data: any): void;
+  addAttribute(name: string, type: NetCDFDataType, value: any): Attribute;
+  inspect(): string;
+}
+```
+
+### Dimension Class
+
+```typescript
+class Dimension {
+  readonly id: number;
+  readonly length: number;
+  name: string;
+  inspect(): string;
+}
+```
+
+### Attribute Class
+
+```typescript
+class Attribute {
+  name: string;
+  value: any;
+  delete(): void;
+  inspect(): string;
+}
+```
+
+## Benefits of TypeScript Support
+
+1. **IntelliSense**: Get autocomplete suggestions for all methods and properties
+2. **Type Safety**: Catch type errors at compile time instead of runtime
+3. **Documentation**: Inline documentation available in your IDE
+4. **Refactoring**: Safely rename and refactor code with confidence
+5. **Error Prevention**: Prevent common mistakes like invalid file modes or data types
+
+## Testing
+
+The package includes a TypeScript test file to verify the type definitions:
+
+```bash
+npx tsc test/typescript-test.ts --noEmit --skipLibCheck
+```
+
+This ensures all type definitions are correct and complete.
+
+## Contributing
+
+If you find any issues with the type definitions or have suggestions for improvements, please open an issue on the GitHub repository.

package/index.d.ts

@@ -0,0 +1,389 @@
+// Type definitions for nodenetcdf
+// Project: https://github.com/pheonixfirewingz/netcdf4
+// Definitions by: Luke Shore <luke.a.shore@oliva.energy>
+
+/**
+ * NetCDF data types
+ */
+export type NetCDFDataType = 
+  | 'byte'
+  | 'char'
+  | 'short'
+  | 'int'
+  | 'float'
+  | 'double'
+  | 'ubyte'
+  | 'ushort'
+  | 'uint'
+  | 'int64'
+  | 'string';
+
+/**
+ * File open/create modes
+ */
+export type FileMode = 
+  | 'r'     // Read-only
+  | 'w'     // Read-write
+  | 'c'     // Create (no clobber)
+  | 'c!';   // Create (clobber/overwrite)
+
+/**
+ * NetCDF file formats
+ */
+export type FileFormat = 
+  | 'classic'           // Classic NetCDF format
+  | 'classic64'         // 64-bit offset format
+  | 'nodenetcdf'        // NetCDF-4 format
+  | 'nodenetcdfclassic'; // NetCDF-4 classic model
+
+/**
+ * Endianness options
+ */
+export type Endianness = 'little' | 'big' | 'native';
+
+/**
+ * Checksum modes
+ */
+export type ChecksumMode = 'none' | 'fletcher32';
+
+/**
+ * Chunk modes
+ */
+export type ChunkMode = 'contiguous' | 'chunked';
+
+/**
+ * Fill modes
+ */
+export type FillMode = 'fill' | 'nofill';
+
+/**
+ * Represents a NetCDF attribute
+ */
+export class Attribute {
+  /**
+   * The name of the attribute
+   */
+  name: string;
+
+  /**
+   * The value of the attribute
+   */
+  value: any;
+
+  /**
+   * Delete this attribute
+   */
+  delete(): void;
+
+  /**
+   * Inspect the attribute
+   */
+  inspect(): string;
+
+  /**
+   * Convert the attribute to a JSON-serializable object
+   */
+  toJSON(): { name: string; value: any };
+}
+
+/**
+ * Represents a NetCDF dimension
+ */
+export class Dimension {
+  /**
+   * The dimension ID
+   */
+  readonly id: number;
+
+  /**
+   * The length of the dimension
+   */
+  readonly length: number;
+
+  /**
+   * The name of the dimension
+   */
+  name: string;
+
+  /**
+   * Inspect the dimension
+   */
+  inspect(): string;
+
+  /**
+   * Convert the dimension to a JSON-serializable object
+   */
+  toJSON(): { id: number; name: string; length: number };
+}
+
+/**
+ * Represents a NetCDF variable
+ */
+export class Variable {
+  /**
+   * The variable ID
+   */
+  readonly id: number;
+
+  /**
+   * The data type of the variable
+   */
+  readonly type: NetCDFDataType;
+
+  /**
+   * The dimensions of the variable
+   */
+  readonly dimensions: Dimension[];
+
+  /**
+   * The attributes of the variable
+   */
+  readonly attributes: { [name: string]: Attribute };
+
+  /**
+   * The name of the variable
+   */
+  name: string;
+
+  /**
+   * The endianness of the variable
+   */
+  endianness: Endianness;
+
+  /**
+   * The checksum mode
+   */
+  checksumMode: ChecksumMode;
+
+  /**
+   * The chunk mode
+   */
+  chunkMode: ChunkMode;
+
+  /**
+   * The chunk sizes
+   */
+  chunkSizes: number[];
+
+  /**
+   * The fill mode
+   */
+  fillMode: FillMode;
+
+  /**
+   * The fill value
+   */
+  fillValue: any;
+
+  /**
+   * Whether compression shuffle is enabled
+   */
+  compressionShuffle: boolean;
+
+  /**
+   * Whether compression deflate is enabled
+   */
+  compressionDeflate: boolean;
+
+  /**
+   * The compression level (0-9)
+   */
+  compressionLevel: number;
+
+  /**
+   * Read the entire variable
+   */
+  read(): any;
+
+  /**
+   * Read a slice of the variable
+   * @param start - Starting indices for each dimension
+   * @param count - Number of elements to read in each dimension
+   */
+  readSlice(start: number[], count: number[]): any;
+
+  /**
+   * Read a strided slice of the variable
+   * @param start - Starting indices for each dimension
+   * @param count - Number of elements to read in each dimension
+   * @param stride - Stride for each dimension
+   */
+  readStridedSlice(start: number[], count: number[], stride: number[]): any;
+
+  /**
+   * Write data to the entire variable
+   * @param data - Data to write
+   */
+  write(data: any): void;
+
+  /**
+   * Write data to a slice of the variable
+   * @param start - Starting indices for each dimension
+   * @param count - Number of elements to write in each dimension
+   * @param data - Data to write
+   */
+  writeSlice(start: number[], count: number[], data: any): void;
+
+  /**
+   * Write data to a strided slice of the variable
+   * @param start - Starting indices for each dimension
+   * @param count - Number of elements to write in each dimension
+   * @param stride - Stride for each dimension
+   * @param data - Data to write
+   */
+  writeStridedSlice(start: number[], count: number[], stride: number[], data: any): void;
+
+  /**
+   * Add an attribute to the variable
+   * @param name - Attribute name
+   * @param type - Data type
+   * @param value - Attribute value
+   */
+  addAttribute(name: string, type: NetCDFDataType, value: any): Attribute;
+
+  /**
+   * Inspect the variable
+   */
+  inspect(): string;
+
+  /**
+   * Convert the variable to a JSON-serializable object (recursively serializes dimensions and attributes)
+   */
+  toJSON(): {
+    id: number;
+    name: string;
+    type: NetCDFDataType;
+    dimensions: Array<{ id: number; name: string; length: number }>;
+    attributes: { [name: string]: { name: string; value: any } };
+  };
+}
+
+/**
+ * Represents a NetCDF group
+ */
+export class Group {
+  /**
+   * The group ID
+   */
+  readonly id: number;
+
+  /**
+   * Variables in this group
+   */
+  readonly variables: { [name: string]: Variable };
+
+  /**
+   * Dimensions in this group
+   */
+  readonly dimensions: { [name: string]: Dimension };
+
+  /**
+   * The unlimited dimension in this group
+   */
+  readonly unlimited: Dimension | null;
+
+  /**
+   * Attributes in this group
+   */
+  readonly attributes: { [name: string]: Attribute };
+
+  /**
+   * Subgroups in this group
+   */
+  readonly subgroups: { [name: string]: Group };
+
+  /**
+   * The name of the group
+   */
+  readonly name: string;
+
+  /**
+   * The full name (path) of the group
+   */
+  readonly fullname: string;
+
+  /**
+   * Add an attribute to the group
+   * @param name - Attribute name
+   * @param type - Data type
+   * @param value - Attribute value
+   */
+  addAttribute(name: string, type: NetCDFDataType, value: any): Attribute;
+
+  /**
+   * Add a dimension to the group
+   * @param name - Dimension name
+   * @param length - Dimension length (0 for unlimited)
+   */
+  addDimension(name: string, length: number): Dimension;
+
+  /**
+   * Add a subgroup to the group
+   * @param name - Subgroup name
+   */
+  addSubgroup(name: string): Group;
+
+  /**
+   * Add a variable to the group
+   * @param name - Variable name
+   * @param type - Data type
+   * @param dimensions - Array of dimension names or Dimension objects
+   */
+  addVariable(name: string, type: NetCDFDataType, dimensions: (string | Dimension)[]): Variable;
+
+  /**
+   * Inspect the group
+   */
+  inspect(): string;
+
+  /**
+   * Convert the group to a JSON-serializable object (recursively serializes all children: dimensions, variables, attributes, subgroups)
+   */
+  toJSON(): {
+    id: number;
+    name: string;
+    fullname: string;
+    dimensions: { [name: string]: { id: number; name: string; length: number } };
+    variables: { [name: string]: any };
+    attributes: { [name: string]: { name: string; value: any } };
+    subgroups: { [name: string]: any };
+  };
+}
+
+/**
+ * Represents a NetCDF file
+ */
+export class File {
+  /**
+   * The root group of the file
+   */
+  readonly root: Group;
+
+  /**
+   * Open or create a NetCDF file
+   * @param filename - Path to the file
+   * @param mode - File mode ('r', 'w', 'c', 'c!')
+   * @param format - File format (optional, defaults to 'nodenetcdf')
+   */
+  constructor(filename: string, mode: FileMode, format?: FileFormat);
+
+  /**
+   * Synchronize the file to disk
+   */
+  sync(): void;
+
+  /**
+   * Close the file
+   */
+  close(): void;
+
+  /**
+   * Inspect the file
+   */
+  inspect(): string;
+
+  /**
+   * Convert the file to a JSON-serializable object (serializes the entire file structure via root group)
+   */
+  toJSON(): any;
+}

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "nodenetcdf",
-  "version": "4.9.3",
+  "version": "4.9.32",
   "description": "Read and write NodeNetCDF files",
   "main": "./build/Release/nodenetcdf.node",
+  "types": "./index.d.ts",
   "scripts": {
     "preinstall": "node scripts/setup-vcpkg.js",
     "install": "node scripts/verify-build-deps.js && node-gyp configure build",
     "postinstall": "node scripts/copy-deps.js",
-    "test": "mocha",
+    "test": "npm run test:types && mocha",
+    "test:types": "node scripts/test-types.js",
     "verify-deps": "node scripts/verify-build-deps.js"
   },
   "author": {
@@ -30,6 +32,8 @@
   },
   "devDependencies": {
     "chai": "^6.2.0",
-    "mocha": "^11.7.4"
+    "mocha": "^11.7.4",
+    "typescript": "^5.7.2",
+    "@types/node": "^22.10.5"
   }
 }

package/scripts/test-types.js

@@ -0,0 +1,15 @@
+const { execSync } = require('child_process');
+
+console.log('\nRunning TypeScript type checking...\n');
+
+try {
+  execSync('tsc test/typescript-test.ts --noEmit --skipLibCheck', { 
+    stdio: 'inherit',
+    cwd: process.cwd()
+  });
+  console.log('\n✅ TypeScript type checking passed!\n');
+  process.exit(0);
+} catch (error) {
+  console.log('\n❌ TypeScript type checking failed!\n');
+  process.exit(1);
+}

package/src/Attribute.cpp

@@ -46,6 +46,7 @@ void Attribute::Init(v8::Local<v8::Object> exports)
     tpl->InstanceTemplate()->SetInternalFieldCount(1);
     NODE_SET_PROTOTYPE_METHOD(tpl, "delete", Attribute::Delete);
     NODE_SET_PROTOTYPE_METHOD(tpl, "inspect", Attribute::Inspect);
+    NODE_SET_PROTOTYPE_METHOD(tpl, "toJSON", Attribute::ToJSON);
     tpl->InstanceTemplate()->SetAccessor(
         v8::String::NewFromUtf8(isolate, "name", v8::NewStringType::kNormal).ToLocalChecked(), Attribute::GetName,
         Attribute::SetName);
@@ -331,4 +332,57 @@ void Attribute::Inspect(const v8::FunctionCallbackInfo<v8::Value> &args)
     args.GetReturnValue().Set(
         v8::String::NewFromUtf8(isolate, "[object Attribute]", v8::NewStringType::kNormal).ToLocalChecked());
 }
+
+void Attribute::ToJSON(const v8::FunctionCallbackInfo<v8::Value> &args)
+{
+    v8::Isolate *isolate = args.GetIsolate();
+    v8::Local<v8::Context> context = isolate->GetCurrentContext();
+    const auto *obj = node::ObjectWrap::Unwrap<Attribute>(args.Holder());
+    
+    // Use internalized strings for better performance
+    v8::Local<v8::String> name_str = v8::String::NewFromUtf8Literal(isolate, "name");
+    v8::Local<v8::String> value_str = v8::String::NewFromUtf8Literal(isolate, "value");
+    
+    v8::Local<v8::Object> json = v8::Object::New(isolate);
+    
+    // Add name
+    (void)json->CreateDataProperty(context, name_str,
+              v8::String::NewFromUtf8(isolate, obj->name.c_str(), v8::NewStringType::kInternalized).ToLocalChecked());
+    
+    // Add value - get from the object's value property
+    // Use a TryCatch to handle errors when getting the value
+    v8::TryCatch try_catch(isolate);
+    v8::MaybeLocal<v8::Value> maybeValue = args.Holder()->Get(context, value_str);
+    v8::Local<v8::Value> value;
+    
+    if (!maybeValue.ToLocal(&value) || try_catch.HasCaught())
+    {
+        // If getting the value failed or threw an exception, clear the exception
+        // and set value to null instead of crashing
+        if (try_catch.HasCaught())
+        {
+            try_catch.Reset();
+        }
+        value = v8::Null(isolate);
+    }
+    else if (value->IsTypedArray())
+    {
+        // Convert TypedArray to regular array for JSON serialization
+        v8::Local<v8::TypedArray> typedArray = v8::Local<v8::TypedArray>::Cast(value);
+        uint32_t length = typedArray->Length();
+        v8::Local<v8::Array> array = v8::Array::New(isolate, length);
+        
+        for (uint32_t i = 0; i < length; i++)
+        {
+            v8::Local<v8::Value> element = typedArray->Get(context, i).ToLocalChecked();
+            (void)array->Set(context, i, element);
+        }
+        value = array;
+    }
+    // Don't wrap primitives - only convert TypedArrays to arrays
+    
+    (void)json->CreateDataProperty(context, value_str, value);
+    
+    args.GetReturnValue().Set(json);
+}
 } // namespace nodenetcdfjs

package/src/Attribute.h

@@ -34,6 +34,7 @@ class Attribute : public node::ObjectWrap
     static void SetValue(v8::Local<v8::String> property, v8::Local<v8::Value> val,
                          const v8::PropertyCallbackInfo<void> &info);
     static void Inspect(const v8::FunctionCallbackInfo<v8::Value> &args);
+    static void ToJSON(const v8::FunctionCallbackInfo<v8::Value> &args);
 
     std::string name{};
     int var_id{-1};