nodenetcdf 4.9.32 → 4.9.34

package/src/File.h

@@ -9,13 +9,43 @@ namespace nodenetcdfjs
 
 class Group;
 
+/**
+ * @brief Represents a NetCDF file wrapper for Node.js
+ * 
+ * This class provides a Node.js interface to NetCDF files, which are used for
+ * storing array-oriented scientific data. The File class handles opening, closing,
+ * and synchronizing NetCDF files, and serves as the entry point for accessing
+ * groups, variables, dimensions, and attributes within the file.
+ * 
+ * The class extends node::ObjectWrap to provide JavaScript binding capabilities,
+ * allowing NetCDF files to be manipulated from JavaScript code.
+ */
 class File : public node::ObjectWrap
 {
   public:
+    /**
+     * @brief Initialize the File class and register it with Node.js
+     * @param exports The exports object to attach the File constructor to
+     * 
+     * This static method sets up the File class for use in Node.js,
+     * defining its constructor and prototype methods.
+     */
     static void Init(v8::Local<v8::Object> exports);
 
   private:
+    /**
+     * @brief Construct a File object
+     * @param id_ The file ID from the NetCDF library
+     * 
+     * Creates a new file wrapper for an opened NetCDF file.
+     */
     explicit File(int id_) noexcept;
+    
+    /**
+     * @brief Destructor for File object
+     * 
+     * Ensures the NetCDF file is properly closed when the object is destroyed.
+     */
     ~File() override;
 
     // Delete copy and move operations for safety
@@ -24,17 +54,58 @@ class File : public node::ObjectWrap
     File(File &&) = delete;
     File &operator=(File &&) = delete;
 
+    /**
+     * @brief Open a NetCDF file
+     * @param filename Path to the NetCDF file to open
+     * @param mode Access mode (read-only, read-write, create, etc.)
+     * @param format NetCDF format (classic, 64-bit offset, NetCDF-4, etc.)
+     * @return true if successful, false otherwise
+     * 
+     * Opens a NetCDF file with the specified mode and format.
+     */
     [[nodiscard]] bool open(const char *filename, int mode, int format) noexcept;
 
+    /**
+     * @brief JavaScript constructor for creating new File objects
+     * @param args JavaScript function arguments containing filename, mode, and format
+     */
     static void New(const v8::FunctionCallbackInfo<v8::Value> &args);
+    
+    /**
+     * @brief Close the NetCDF file
+     * @param args JavaScript function arguments
+     * 
+     * Closes the file and releases associated resources.
+     */
     static void Close(const v8::FunctionCallbackInfo<v8::Value> &args);
+    
+    /**
+     * @brief Synchronize file to disk
+     * @param args JavaScript function arguments
+     * 
+     * Flushes any buffered data to disk, ensuring data persistence.
+     */
     static void Sync(const v8::FunctionCallbackInfo<v8::Value> &args);
+    
+    /**
+     * @brief Custom inspect method for Node.js console output
+     * @param args JavaScript function arguments
+     */
     static void Inspect(const v8::FunctionCallbackInfo<v8::Value> &args);
+    
+    /**
+     * @brief Convert file to JSON representation
+     * @param args JavaScript function arguments
+     */
     static void ToJSON(const v8::FunctionCallbackInfo<v8::Value> &args);
 
+    /// Persistent reference to the JavaScript constructor function
     static v8::Persistent<v8::Function> constructor;
 
+    /// The file ID from the NetCDF library
     int id{-1};
+    
+    /// Flag indicating whether the file has been closed
     bool closed{false};
 };
 

package/src/Group.cpp

@@ -5,7 +5,6 @@
 #include "nodenetcdfjs.h"
 #include <netcdf.h>
 
-
 namespace nodenetcdfjs
 {
 
@@ -136,9 +135,7 @@ void Group::AddDimension(const v8::FunctionCallbackInfo<v8::Value> &args)
 
     int len;
     if (const std::string len_str = *v8::String::Utf8Value(isolate, args[1]); len_str == "unlimited")
-    {
         len = NC_UNLIMITED;
-    }
     else
     {
         if (!args[1]->IsUint32())
@@ -152,9 +149,8 @@ void Group::AddDimension(const v8::FunctionCallbackInfo<v8::Value> &args)
     }
 
     int new_id = -1;
-    const int retval = nc_def_dim(obj->id, *v8::String::Utf8Value(isolate, args[0]), len, &new_id);
-
-    if (retval != NC_NOERR)
+    if (const int retval = nc_def_dim(obj->id, *v8::String::Utf8Value(isolate, args[0]), len, &new_id);
+        retval != NC_NOERR)
     {
         throw_netcdf_error(isolate, retval);
         return;
@@ -271,15 +267,12 @@ void Group::GetVariables(v8::Local<v8::String> property, const v8::PropertyCallb
     {
         auto *v = new Variable(var_ids[i], obj->id);
         if (v->get_name(name.data()))
-        {
-            (void)result->CreateDataProperty(context,
-                        v8::String::NewFromUtf8(isolate, name.data(), v8::NewStringType::kInternalized).ToLocalChecked(),
-                        v->handle());
-        }
+            (void)result->CreateDataProperty(
+                context,
+                v8::String::NewFromUtf8(isolate, name.data(), v8::NewStringType::kInternalized).ToLocalChecked(),
+                v->handle());
         else
-        {
             return;
-        }
     }
     info.GetReturnValue().Set(result);
 }
@@ -314,7 +307,8 @@ void Group::GetDimensions(v8::Local<v8::String> property, const v8::PropertyCall
         auto *d = new Dimension(dim_ids[i], obj->id);
         if (d->get_name(name.data()))
         {
-            (void)result->CreateDataProperty(context,
+            (void)result->CreateDataProperty(
+                context,
                 v8::String::NewFromUtf8(isolate, name.data(), v8::NewStringType::kInternalized).ToLocalChecked(),
                 d->handle());
         }
@@ -354,11 +348,13 @@ void Group::GetUnlimited(v8::Local<v8::String> property, const v8::PropertyCallb
         auto *d = new Dimension(dim_ids[i], obj->id);
         if (d->get_name(name.data()))
         {
-             (void)result->CreateDataProperty(context,
-                        v8::String::NewFromUtf8(isolate, name.data(), v8::NewStringType::kInternalized).ToLocalChecked(),
-                        d->handle());
+            (void)result->CreateDataProperty(
+                context,
+                v8::String::NewFromUtf8(isolate, name.data(), v8::NewStringType::kInternalized).ToLocalChecked(),
+                d->handle());
         }
-        else return;
+        else
+            return;
     }
     info.GetReturnValue().Set(result);
 }
@@ -389,9 +385,9 @@ void Group::GetAttributes(v8::Local<v8::String> property, const v8::PropertyCall
             return;
         }
         auto *a = new Attribute(name.data(), NC_GLOBAL, obj->id);
-        (void)result->CreateDataProperty(context,
-                    v8::String::NewFromUtf8(isolate, name.data(), v8::NewStringType::kInternalized).ToLocalChecked(),
-                    a->handle());
+        (void)result->CreateDataProperty(
+            context, v8::String::NewFromUtf8(isolate, name.data(), v8::NewStringType::kInternalized).ToLocalChecked(),
+            a->handle());
     }
     info.GetReturnValue().Set(result);
 }
@@ -426,14 +422,13 @@ void Group::GetSubgroups(v8::Local<v8::String> property, const v8::PropertyCallb
         auto *g = new Group(grp_ids[i]);
         if (g->get_name(name.data()))
         {
-             (void)result->CreateDataProperty(context,
-                        v8::String::NewFromUtf8(isolate, name.data(), v8::NewStringType::kInternalized).ToLocalChecked(),
-                        g->handle());
+            (void)result->CreateDataProperty(
+                context,
+                v8::String::NewFromUtf8(isolate, name.data(), v8::NewStringType::kInternalized).ToLocalChecked(),
+                g->handle());
         }
         else
-        {
             return;
-        }
     }
     info.GetReturnValue().Set(result);
 }
@@ -488,8 +483,7 @@ void Group::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<Group>(args.Holder());
-    
-    // Use internalized strings for better performance
+
     v8::Local<v8::String> id_str = v8::String::NewFromUtf8Literal(isolate, "id");
     v8::Local<v8::String> name_str = v8::String::NewFromUtf8Literal(isolate, "name");
     v8::Local<v8::String> fullname_str = v8::String::NewFromUtf8Literal(isolate, "fullname");
@@ -497,21 +491,17 @@ void Group::ToJSON(const v8::FunctionCallbackInfo<v8::Value> &args)
     v8::Local<v8::String> variables_str = v8::String::NewFromUtf8Literal(isolate, "variables");
     v8::Local<v8::String> attributes_str = v8::String::NewFromUtf8Literal(isolate, "attributes");
     v8::Local<v8::String> subgroups_str = v8::String::NewFromUtf8Literal(isolate, "subgroups");
-    
+
     v8::Local<v8::Object> json = v8::Object::New(isolate);
-    
-    // Add id
+
     (void)json->CreateDataProperty(context, id_str, v8::Integer::New(isolate, obj->id));
-    
-    // Add name
+
     std::array<char, NC_MAX_NAME + 1> name{};
     if (obj->get_name(name.data()))
-    {
-        (void)json->CreateDataProperty(context, name_str,
-                  v8::String::NewFromUtf8(isolate, name.data(), v8::NewStringType::kInternalized).ToLocalChecked());
-    }
-    
-    // Add fullname
+        (void)json->CreateDataProperty(
+            context, name_str,
+            v8::String::NewFromUtf8(isolate, name.data(), v8::NewStringType::kInternalized).ToLocalChecked());
+
     size_t len = 0;
     int retval = nc_inq_grpname_len(obj->id, &len);
     if (retval == NC_NOERR)
@@ -519,80 +509,123 @@ void Group::ToJSON(const v8::FunctionCallbackInfo<v8::Value> &args)
         std::vector<char> fullname(len + 1, '\0');
         retval = nc_inq_grpname_full(obj->id, nullptr, fullname.data());
         if (retval == NC_NOERR)
-        {
-            (void)json->CreateDataProperty(context, fullname_str,
-                      v8::String::NewFromUtf8(isolate, fullname.data(), v8::NewStringType::kInternalized).ToLocalChecked());
-        }
+            (void)json->CreateDataProperty(
+                context, fullname_str,
+                v8::String::NewFromUtf8(isolate, fullname.data(), v8::NewStringType::kInternalized).ToLocalChecked());
     }
-    
-    // Convert dimensions object to array
+
     v8::Local<v8::Value> dimensions = args.Holder()->Get(context, dimensions_str).ToLocalChecked();
     if (dimensions->IsObject() && !dimensions->IsNull())
     {
         v8::Local<v8::Object> dimsObj = dimensions->ToObject(context).ToLocalChecked();
         v8::Local<v8::Array> propNames = dimsObj->GetOwnPropertyNames(context).ToLocalChecked();
         v8::Local<v8::Array> dimsArray = v8::Array::New(isolate, propNames->Length());
-        
+        v8::Local<v8::String> toJSONStr = v8::String::NewFromUtf8Literal(isolate, "toJSON");
+
         for (uint32_t i = 0; i < propNames->Length(); i++)
         {
             v8::Local<v8::Value> key = propNames->Get(context, i).ToLocalChecked();
             v8::Local<v8::Value> value = dimsObj->Get(context, key).ToLocalChecked();
+
+            if (value->IsObject())
+            {
+                v8::Local<v8::Object> valueObj = value->ToObject(context).ToLocalChecked();
+                v8::Local<v8::Value> toJSON = valueObj->Get(context, toJSONStr).ToLocalChecked();
+                if (toJSON->IsFunction())
+                {
+                    v8::Local<v8::Function> toJSONFunc = v8::Local<v8::Function>::Cast(toJSON);
+                    value = toJSONFunc->Call(context, valueObj, 0, nullptr).ToLocalChecked();
+                }
+            }
             (void)dimsArray->Set(context, i, value);
         }
         (void)json->CreateDataProperty(context, dimensions_str, dimsArray);
     }
-    
-    // Convert variables object to array
+
     v8::Local<v8::Value> variables = args.Holder()->Get(context, variables_str).ToLocalChecked();
     if (variables->IsObject() && !variables->IsNull())
     {
         v8::Local<v8::Object> varsObj = variables->ToObject(context).ToLocalChecked();
         v8::Local<v8::Array> propNames = varsObj->GetOwnPropertyNames(context).ToLocalChecked();
         v8::Local<v8::Array> varsArray = v8::Array::New(isolate, propNames->Length());
-        
+        v8::Local<v8::String> toJSONStr = v8::String::NewFromUtf8Literal(isolate, "toJSON");
+
         for (uint32_t i = 0; i < propNames->Length(); i++)
         {
             v8::Local<v8::Value> key = propNames->Get(context, i).ToLocalChecked();
             v8::Local<v8::Value> value = varsObj->Get(context, key).ToLocalChecked();
+
+            if (value->IsObject())
+            {
+                v8::Local<v8::Object> valueObj = value->ToObject(context).ToLocalChecked();
+                v8::Local<v8::Value> toJSON = valueObj->Get(context, toJSONStr).ToLocalChecked();
+                if (toJSON->IsFunction())
+                {
+                    v8::Local<v8::Function> toJSONFunc = v8::Local<v8::Function>::Cast(toJSON);
+                    value = toJSONFunc->Call(context, valueObj, 0, nullptr).ToLocalChecked();
+                }
+            }
             (void)varsArray->Set(context, i, value);
         }
         (void)json->CreateDataProperty(context, variables_str, varsArray);
     }
-    
-    // Convert attributes object to array
+
     v8::Local<v8::Value> attributes = args.Holder()->Get(context, attributes_str).ToLocalChecked();
     if (attributes->IsObject() && !attributes->IsNull())
     {
         v8::Local<v8::Object> attrsObj = attributes->ToObject(context).ToLocalChecked();
         v8::Local<v8::Array> propNames = attrsObj->GetOwnPropertyNames(context).ToLocalChecked();
         v8::Local<v8::Array> attrsArray = v8::Array::New(isolate, propNames->Length());
-        
+        v8::Local<v8::String> toJSONStr = v8::String::NewFromUtf8Literal(isolate, "toJSON");
+
         for (uint32_t i = 0; i < propNames->Length(); i++)
         {
             v8::Local<v8::Value> key = propNames->Get(context, i).ToLocalChecked();
             v8::Local<v8::Value> value = attrsObj->Get(context, key).ToLocalChecked();
+
+            if (value->IsObject())
+            {
+                v8::Local<v8::Object> valueObj = value->ToObject(context).ToLocalChecked();
+                v8::Local<v8::Value> toJSON = valueObj->Get(context, toJSONStr).ToLocalChecked();
+                if (toJSON->IsFunction())
+                {
+                    v8::Local<v8::Function> toJSONFunc = v8::Local<v8::Function>::Cast(toJSON);
+                    value = toJSONFunc->Call(context, valueObj, 0, nullptr).ToLocalChecked();
+                }
+            }
             (void)attrsArray->Set(context, i, value);
         }
         (void)json->CreateDataProperty(context, attributes_str, attrsArray);
     }
-    
-    // Convert subgroups object to array
+
     v8::Local<v8::Value> subgroups = args.Holder()->Get(context, subgroups_str).ToLocalChecked();
     if (subgroups->IsObject() && !subgroups->IsNull())
     {
         v8::Local<v8::Object> subgrpsObj = subgroups->ToObject(context).ToLocalChecked();
         v8::Local<v8::Array> propNames = subgrpsObj->GetOwnPropertyNames(context).ToLocalChecked();
         v8::Local<v8::Array> subgrpsArray = v8::Array::New(isolate, propNames->Length());
-        
+        v8::Local<v8::String> toJSONStr = v8::String::NewFromUtf8Literal(isolate, "toJSON");
+
         for (uint32_t i = 0; i < propNames->Length(); i++)
         {
             v8::Local<v8::Value> key = propNames->Get(context, i).ToLocalChecked();
             v8::Local<v8::Value> value = subgrpsObj->Get(context, key).ToLocalChecked();
+
+            if (value->IsObject())
+            {
+                v8::Local<v8::Object> valueObj = value->ToObject(context).ToLocalChecked();
+                v8::Local<v8::Value> toJSON = valueObj->Get(context, toJSONStr).ToLocalChecked();
+                if (toJSON->IsFunction())
+                {
+                    v8::Local<v8::Function> toJSONFunc = v8::Local<v8::Function>::Cast(toJSON);
+                    value = toJSONFunc->Call(context, valueObj, 0, nullptr).ToLocalChecked();
+                }
+            }
             (void)subgrpsArray->Set(context, i, value);
         }
         (void)json->CreateDataProperty(context, subgroups_str, subgrpsArray);
     }
-    
+
     args.GetReturnValue().Set(json);
 }
 } // namespace nodenetcdfjs

package/src/Group.h

@@ -9,12 +9,44 @@ namespace nodenetcdfjs
 
 class Variable;
 
+/**
+ * @brief Represents a NetCDF group wrapper for Node.js
+ * 
+ * This class provides a Node.js interface to NetCDF groups, which are hierarchical
+ * containers for organizing variables, dimensions, attributes, and subgroups within
+ * a NetCDF file. Groups enable logical organization of related data items.
+ * 
+ * The class extends node::ObjectWrap to provide JavaScript binding capabilities,
+ * allowing groups to be navigated and manipulated from JavaScript code.
+ */
 class Group : public node::ObjectWrap
 {
   public:
+    /**
+     * @brief Construct a Group object
+     * @param id The group ID in the NetCDF file
+     * 
+     * Creates a new group wrapper for an existing NetCDF group.
+     */
     explicit Group(int id) noexcept;
+    
+    /**
+     * @brief Initialize the Group class and register it with Node.js
+     * @param exports The exports object to attach the Group constructor to
+     * 
+     * This static method sets up the Group class for use in Node.js,
+     * defining its constructor and prototype methods.
+     */
     static void Init(v8::Local<v8::Object> exports);
 
+    /**
+     * @brief Get the name of this group
+     * @param name Buffer to store the group name
+     * @return true if successful, false otherwise
+     * 
+     * Retrieves the group name from the NetCDF file and stores it
+     * in the provided buffer.
+     */
     [[nodiscard]] bool get_name(char *name) const noexcept;
 
   private:
@@ -24,24 +56,123 @@ class Group : public node::ObjectWrap
     Group(Group &&) = delete;
     Group &operator=(Group &&) = delete;
 
+    /// Persistent reference to the JavaScript constructor function
     static v8::Persistent<v8::Function> constructor;
 
+    /**
+     * @brief Getter for the group ID property
+     * @param property The property name being accessed
+     * @param info Callback info containing the return value
+     */
     static void GetId(v8::Local<v8::String> property, const v8::PropertyCallbackInfo<v8::Value> &info);
+    
+    /**
+     * @brief Getter for the variables property
+     * @param property The property name being accessed
+     * @param info Callback info containing the return value
+     * 
+     * Returns an object containing all variables in this group.
+     */
     static void GetVariables(v8::Local<v8::String> property, const v8::PropertyCallbackInfo<v8::Value> &info);
+    
+    /**
+     * @brief Getter for the dimensions property
+     * @param property The property name being accessed
+     * @param info Callback info containing the return value
+     * 
+     * Returns an object containing all dimensions in this group.
+     */
     static void GetDimensions(v8::Local<v8::String> property, const v8::PropertyCallbackInfo<v8::Value> &info);
+    
+    /**
+     * @brief Getter for the unlimited dimensions property
+     * @param property The property name being accessed
+     * @param info Callback info containing the return value
+     * 
+     * Returns an array of unlimited dimension IDs in this group.
+     */
     static void GetUnlimited(v8::Local<v8::String> property, const v8::PropertyCallbackInfo<v8::Value> &info);
+    
+    /**
+     * @brief Getter for the attributes property
+     * @param property The property name being accessed
+     * @param info Callback info containing the return value
+     * 
+     * Returns an object containing all attributes in this group.
+     */
     static void GetAttributes(v8::Local<v8::String> property, const v8::PropertyCallbackInfo<v8::Value> &info);
+    
+    /**
+     * @brief Getter for the subgroups property
+     * @param property The property name being accessed
+     * @param info Callback info containing the return value
+     * 
+     * Returns an object containing all subgroups in this group.
+     */
     static void GetSubgroups(v8::Local<v8::String> property, const v8::PropertyCallbackInfo<v8::Value> &info);
+    
+    /**
+     * @brief Getter for the group name property
+     * @param property The property name being accessed
+     * @param info Callback info containing the return value
+     */
     static void GetName(v8::Local<v8::String> property, const v8::PropertyCallbackInfo<v8::Value> &info);
+    
+    /**
+     * @brief Getter for the full group name property
+     * @param property The property name being accessed
+     * @param info Callback info containing the return value
+     * 
+     * Returns the full path to this group from the root.
+     */
     static void GetFullname(v8::Local<v8::String> property, const v8::PropertyCallbackInfo<v8::Value> &info);
 
+    /**
+     * @brief Add a new attribute to this group
+     * @param args JavaScript function arguments (name, type, value)
+     * 
+     * Creates a new attribute with the specified name, type, and value.
+     */
     static void AddAttribute(const v8::FunctionCallbackInfo<v8::Value> &args);
+    
+    /**
+     * @brief Add a new dimension to this group
+     * @param args JavaScript function arguments (name, length)
+     * 
+     * Creates a new dimension with the specified name and length.
+     * Use 0 or NC_UNLIMITED for an unlimited dimension.
+     */
     static void AddDimension(const v8::FunctionCallbackInfo<v8::Value> &args);
+    
+    /**
+     * @brief Add a new subgroup to this group
+     * @param args JavaScript function arguments (name)
+     * 
+     * Creates a new subgroup with the specified name.
+     */
     static void AddSubgroup(const v8::FunctionCallbackInfo<v8::Value> &args);
+    
+    /**
+     * @brief Add a new variable to this group
+     * @param args JavaScript function arguments (name, type, dimensions)
+     * 
+     * Creates a new variable with the specified name, data type, and dimensions.
+     */
     static void AddVariable(const v8::FunctionCallbackInfo<v8::Value> &args);
+    
+    /**
+     * @brief Custom inspect method for Node.js console output
+     * @param args JavaScript function arguments
+     */
     static void Inspect(const v8::FunctionCallbackInfo<v8::Value> &args);
+    
+    /**
+     * @brief Convert group to JSON representation
+     * @param args JavaScript function arguments
+     */
     static void ToJSON(const v8::FunctionCallbackInfo<v8::Value> &args);
 
+    /// The group ID in the NetCDF file
     int id{-1};
 };