groove-dev 0.26.14 → 0.26.16

package/pitch-deck-groove/node_modules/nan/doc/persistent.md

@@ -0,0 +1,296 @@
+## Persistent references
+
+An object reference that is independent of any `HandleScope` is a _persistent_ reference. Where a `Local` handle only lives as long as the `HandleScope` in which it was allocated, a `Persistent` handle remains valid until it is explicitly disposed.
+
+Due to the evolution of the V8 API, it is necessary for NAN to provide a wrapper implementation of the `Persistent` classes to supply compatibility across the V8 versions supported.
+
+ - <a href="#api_nan_persistent_base"><b><code>Nan::PersistentBase & v8::PersistentBase</code></b></a>
+ - <a href="#api_nan_non_copyable_persistent_traits"><b><code>Nan::NonCopyablePersistentTraits & v8::NonCopyablePersistentTraits</code></b></a>
+ - <a href="#api_nan_copyable_persistent_traits"><b><code>Nan::CopyablePersistentTraits & v8::CopyablePersistentTraits</code></b></a>
+ - <a href="#api_nan_persistent"><b><code>Nan::Persistent</code></b></a>
+ - <a href="#api_nan_global"><b><code>Nan::Global</code></b></a>
+ - <a href="#api_nan_weak_callback_info"><b><code>Nan::WeakCallbackInfo</code></b></a>
+ - <a href="#api_nan_weak_callback_type"><b><code>Nan::WeakCallbackType</code></b></a>
+
+Also see the V8 Embedders Guide section on [Handles and Garbage Collection](https://v8.dev/docs/embed#handles-and-garbage-collection).
+
+<a name="api_nan_persistent_base"></a>
+### Nan::PersistentBase & v8::PersistentBase
+
+A persistent handle contains a reference to a storage cell in V8 which holds an object value and which is updated by the garbage collector whenever the object is moved. A new storage cell can be created using the constructor or `Nan::PersistentBase::Reset()`. Existing handles can be disposed using an argument-less `Nan::PersistentBase::Reset()`.
+
+Definition:
+
+_(note: this is implemented as `Nan::PersistentBase` for older versions of V8 and the native `v8::PersistentBase` is used for newer versions of V8)_
+
+```c++
+template<typename T> class PersistentBase {
+ public:
+  /**
+   * If non-empty, destroy the underlying storage cell
+   */
+  void Reset();
+
+  /**
+   * If non-empty, destroy the underlying storage cell and create a new one with
+   * the contents of another if it is also non-empty
+   */
+  template<typename S> void Reset(const v8::Local<S> &other);
+
+  /**
+   * If non-empty, destroy the underlying storage cell and create a new one with
+   * the contents of another if it is also non-empty
+   */
+  template<typename S> void Reset(const PersistentBase<S> &other);
+
+  /** Returns true if the handle is empty. */
+  bool IsEmpty() const;
+
+  /**
+   * If non-empty, destroy the underlying storage cell
+   * IsEmpty() will return true after this call.
+   */
+  void Empty();
+
+  template<typename S> bool operator==(const PersistentBase<S> &that);
+
+  template<typename S> bool operator==(const v8::Local<S> &that);
+
+  template<typename S> bool operator!=(const PersistentBase<S> &that);
+
+  template<typename S> bool operator!=(const v8::Local<S> &that);
+
+   /**
+   *  Install a finalization callback on this object.
+   *  NOTE: There is no guarantee as to *when* or even *if* the callback is
+   *  invoked. The invocation is performed solely on a best effort basis.
+   *  As always, GC-based finalization should *not* be relied upon for any
+   *  critical form of resource management! At the moment you can either
+   *  specify a parameter for the callback or the location of two internal
+   *  fields in the dying object.
+   */
+  template<typename P>
+  void SetWeak(P *parameter,
+               typename WeakCallbackInfo<P>::Callback callback,
+               WeakCallbackType type);
+
+  void ClearWeak();
+
+  /**
+   * Marks the reference to this object independent. Garbage collector is free
+   * to ignore any object groups containing this object. Weak callback for an
+   * independent handle should not assume that it will be preceded by a global
+   * GC prologue callback or followed by a global GC epilogue callback.
+   */
+  void MarkIndependent() const;
+
+  bool IsIndependent() const;
+
+  /** Checks if the handle holds the only reference to an object. */
+  bool IsNearDeath() const;
+
+  /** Returns true if the handle's reference is weak.  */
+  bool IsWeak() const
+};
+```
+
+See the V8 documentation for [`PersistentBase`](https://v8docs.nodesource.com/node-8.16/d4/dca/classv8_1_1_persistent_base.html) for further information.
+
+**Tip:** To get a `v8::Local` reference to the original object back from a `PersistentBase` or `Persistent` object:
+
+```c++
+v8::Local<v8::Object> object = Nan::New(persistent);
+```
+
+<a name="api_nan_non_copyable_persistent_traits"></a>
+### Nan::NonCopyablePersistentTraits & v8::NonCopyablePersistentTraits
+
+Default traits for `Nan::Persistent`. This class does not allow use of the a copy constructor or assignment operator. At present `kResetInDestructor` is not set, but that will change in a future version.
+
+Definition:
+
+_(note: this is implemented as `Nan::NonCopyablePersistentTraits` for older versions of V8 and the native `v8::NonCopyablePersistentTraits` is used for newer versions of V8)_
+
+```c++
+template<typename T> class NonCopyablePersistentTraits {
+ public:
+  typedef Persistent<T, NonCopyablePersistentTraits<T> > NonCopyablePersistent;
+
+  static const bool kResetInDestructor = false;
+
+  template<typename S, typename M>
+  static void Copy(const Persistent<S, M> &source,
+                   NonCopyablePersistent *dest);
+
+  template<typename O> static void Uncompilable();
+};
+```
+
+See the V8 documentation for [`NonCopyablePersistentTraits`](https://v8docs.nodesource.com/node-8.16/de/d73/classv8_1_1_non_copyable_persistent_traits.html) for further information.
+
+<a name="api_nan_copyable_persistent_traits"></a>
+### Nan::CopyablePersistentTraits & v8::CopyablePersistentTraits
+
+A helper class of traits to allow copying and assignment of `Persistent`. This will clone the contents of storage cell, but not any of the flags, etc..
+
+Definition:
+
+_(note: this is implemented as `Nan::CopyablePersistentTraits` for older versions of V8 and the native `v8::NonCopyablePersistentTraits` is used for newer versions of V8)_
+
+```c++
+template<typename T>
+class CopyablePersistentTraits {
+ public:
+  typedef Persistent<T, CopyablePersistentTraits<T> > CopyablePersistent;
+
+  static const bool kResetInDestructor = true;
+
+  template<typename S, typename M>
+  static void Copy(const Persistent<S, M> &source,
+                   CopyablePersistent *dest);
+};
+```
+
+See the V8 documentation for [`CopyablePersistentTraits`](https://v8docs.nodesource.com/node-8.16/da/d5c/structv8_1_1_copyable_persistent_traits.html) for further information.
+
+<a name="api_nan_persistent"></a>
+### Nan::Persistent
+
+A type of `PersistentBase` which allows copy and assignment. Copy, assignment and destructor behavior is controlled by the traits class `M`.
+
+Definition:
+
+```c++
+template<typename T, typename M = NonCopyablePersistentTraits<T> >
+class Persistent;
+
+template<typename T, typename M> class Persistent : public PersistentBase<T> {
+ public:
+ /**
+  * A Persistent with no storage cell.
+  */
+  Persistent();
+
+  /**
+   * Construct a Persistent from a v8::Local. When the v8::Local is non-empty, a
+   * new storage cell is created pointing to the same object, and no flags are
+   * set.
+   */
+  template<typename S> Persistent(v8::Local<S> that);
+
+  /**
+   * Construct a Persistent from a Persistent. When the Persistent is non-empty,
+   * a new storage cell is created pointing to the same object, and no flags are
+   * set.
+   */
+  Persistent(const Persistent &that);
+
+  /**
+   * The copy constructors and assignment operator create a Persistent exactly
+   * as the Persistent constructor, but the Copy function from the traits class
+   * is called, allowing the setting of flags based on the copied Persistent.
+   */
+  Persistent &operator=(const Persistent &that);
+
+  template <typename S, typename M2>
+  Persistent &operator=(const Persistent<S, M2> &that);
+
+  /**
+   * The destructor will dispose the Persistent based on the kResetInDestructor
+   * flags in the traits class.  Since not calling dispose can result in a
+   * memory leak, it is recommended to always set this flag.
+   */
+  ~Persistent();
+};
+```
+
+See the V8 documentation for [`Persistent`](https://v8docs.nodesource.com/node-8.16/d2/d78/classv8_1_1_persistent.html) for further information.
+
+<a name="api_nan_global"></a>
+### Nan::Global
+
+A type of `PersistentBase` which has move semantics.
+
+```c++
+template<typename T> class Global : public PersistentBase<T> {
+ public:
+  /**
+   * A Global with no storage cell.
+   */
+  Global();
+
+  /**
+   * Construct a Global from a v8::Local. When the v8::Local is non-empty, a new
+   * storage cell is created pointing to the same object, and no flags are set.
+   */
+  template<typename S> Global(v8::Local<S> that);
+  /**
+   * Construct a Global from a PersistentBase. When the Persistent is non-empty,
+   * a new storage cell is created pointing to the same object, and no flags are
+   * set.
+   */
+  template<typename S> Global(const PersistentBase<S> &that);
+
+  /**
+   * Pass allows returning globals from functions, etc.
+   */
+  Global Pass();
+};
+```
+
+See the V8 documentation for [`Global`](https://v8docs.nodesource.com/node-8.16/d5/d40/classv8_1_1_global.html) for further information.
+
+<a name="api_nan_weak_callback_info"></a>
+### Nan::WeakCallbackInfo
+
+`Nan::WeakCallbackInfo` is used as an argument when setting a persistent reference as weak. You may need to free any external resources attached to the object. It is a mirror of `v8:WeakCallbackInfo` as found in newer versions of V8.
+
+Definition:
+
+```c++
+template<typename T> class WeakCallbackInfo {
+ public:
+  typedef void (*Callback)(const WeakCallbackInfo<T>& data);
+
+  v8::Isolate *GetIsolate() const;
+
+  /**
+   * Get the parameter that was associated with the weak handle.
+   */
+  T *GetParameter() const;
+
+  /**
+   * Get pointer from internal field, index can be 0 or 1.
+   */
+  void *GetInternalField(int index) const;
+};
+```
+
+Example usage:
+
+```c++
+void weakCallback(const WeakCallbackInfo<int> &data) {
+  int *parameter = data.GetParameter();
+  delete parameter;
+}
+
+Persistent<v8::Object> obj;
+int *data = new int(0);
+obj.SetWeak(data, callback, WeakCallbackType::kParameter);
+```
+
+See the V8 documentation for [`WeakCallbackInfo`](https://v8docs.nodesource.com/node-8.16/d8/d06/classv8_1_1_weak_callback_info.html) for further information.
+
+<a name="api_nan_weak_callback_type"></a>
+### Nan::WeakCallbackType
+
+Represents the type of a weak callback.
+A weak callback of type `kParameter` makes the supplied parameter to `Nan::PersistentBase::SetWeak` available through `WeakCallbackInfo::GetParameter`.
+A weak callback of type `kInternalFields` uses up to two internal fields at indices 0 and 1 on the `Nan::PersistentBase<v8::Object>` being made weak.
+Note that only `v8::Object`s and derivatives can have internal fields.
+
+Definition:
+
+```c++
+enum class WeakCallbackType { kParameter, kInternalFields };
+```

package/pitch-deck-groove/node_modules/nan/doc/scopes.md

@@ -0,0 +1,73 @@
+## Scopes
+
+A _local handle_ is a pointer to an object. All V8 objects are accessed using handles, they are necessary because of the way the V8 garbage collector works.
+
+A handle scope can be thought of as a container for any number of handles. When you've finished with your handles, instead of deleting each one individually you can simply delete their scope.
+
+The creation of `HandleScope` objects is different across the supported versions of V8. Therefore, NAN provides its own implementations that can be used safely across these.
+
+ - <a href="#api_nan_handle_scope"><b><code>Nan::HandleScope</code></b></a>
+ - <a href="#api_nan_escapable_handle_scope"><b><code>Nan::EscapableHandleScope</code></b></a>
+
+Also see the V8 Embedders Guide section on [Handles and Garbage Collection](https://github.com/v8/v8/wiki/Embedder%27s%20Guide#handles-and-garbage-collection).
+
+<a name="api_nan_handle_scope"></a>
+### Nan::HandleScope
+
+A simple wrapper around [`v8::HandleScope`](https://v8docs.nodesource.com/node-8.16/d3/d95/classv8_1_1_handle_scope.html).
+
+Definition:
+
+```c++
+class Nan::HandleScope {
+ public:
+  Nan::HandleScope();
+  static int NumberOfHandles();
+};
+```
+
+Allocate a new `Nan::HandleScope` whenever you are creating new V8 JavaScript objects. Note that an implicit `HandleScope` is created for you on JavaScript-accessible methods so you do not need to insert one yourself.
+
+Example:
+
+```c++
+// new object is created, it needs a new scope:
+void Pointless() {
+  Nan::HandleScope scope;
+  v8::Local<v8::Object> obj = Nan::New<v8::Object>();
+}
+
+// JavaScript-accessible method already has a HandleScope
+NAN_METHOD(Pointless2) {
+  v8::Local<v8::Object> obj = Nan::New<v8::Object>();
+}
+```
+
+<a name="api_nan_escapable_handle_scope"></a>
+### Nan::EscapableHandleScope
+
+Similar to [`Nan::HandleScope`](#api_nan_handle_scope) but should be used in cases where a function needs to return a V8 JavaScript type that has been created within it.
+
+Definition:
+
+```c++
+class Nan::EscapableHandleScope {
+ public:
+  Nan::EscapableHandleScope();
+  static int NumberOfHandles();
+  template<typename T> v8::Local<T> Escape(v8::Local<T> value);
+}
+```
+
+Use `Escape(value)` to return the object.
+
+Example:
+
+```c++
+v8::Local<v8::Object> EmptyObj() {
+  Nan::EscapableHandleScope scope;
+  v8::Local<v8::Object> obj = Nan::New<v8::Object>();
+  return scope.Escape(obj);
+}
+```
+

package/pitch-deck-groove/node_modules/nan/doc/script.md

@@ -0,0 +1,58 @@
+## Script
+
+NAN provides `v8::Script` helpers as the API has changed over the supported versions of V8.
+
+ - <a href="#api_nan_compile_script"><b><code>Nan::CompileScript()</code></b></a>
+ - <a href="#api_nan_run_script"><b><code>Nan::RunScript()</code></b></a>
+ - <a href="#api_nan_script_origin"><b><code>Nan::ScriptOrigin</code></b></a>
+
+
+<a name="api_nan_compile_script"></a>
+### Nan::CompileScript()
+
+A wrapper around [`v8::ScriptCompiler::Compile()`](https://v8docs.nodesource.com/node-8.16/da/da5/classv8_1_1_script_compiler.html#a93f5072a0db55d881b969e9fc98e564b).
+
+Note that `Nan::BoundScript` is an alias for `v8::Script`.
+
+Signature:
+
+```c++
+Nan::MaybeLocal<Nan::BoundScript> Nan::CompileScript(
+    v8::Local<v8::String> s,
+    const v8::ScriptOrigin& origin);
+Nan::MaybeLocal<Nan::BoundScript> Nan::CompileScript(v8::Local<v8::String> s);
+```
+
+
+<a name="api_nan_run_script"></a>
+### Nan::RunScript()
+
+Calls `script->Run()` or `script->BindToCurrentContext()->Run(Nan::GetCurrentContext())`.
+
+Note that `Nan::BoundScript` is an alias for `v8::Script` and `Nan::UnboundScript` is an alias for `v8::UnboundScript` where available and `v8::Script` on older versions of V8.
+
+Signature:
+
+```c++
+Nan::MaybeLocal<v8::Value> Nan::RunScript(v8::Local<Nan::UnboundScript> script)
+Nan::MaybeLocal<v8::Value> Nan::RunScript(v8::Local<Nan::BoundScript> script)
+```
+
+<a name="api_nan_script_origin"></a>
+### Nan::ScriptOrigin
+
+A class transparently extending [`v8::ScriptOrigin`](https://v8docs.nodesource.com/node-16.0/db/d84/classv8_1_1_script_origin.html#pub-methods)
+to provide backwards compatibility. Only the listed methods are guaranteed to
+be available on all versions of Node.
+
+Declaration:
+
+```c++
+class Nan::ScriptOrigin : public v8::ScriptOrigin {
+ public:
+  ScriptOrigin(v8::Local<v8::Value> name, v8::Local<v8::Integer> line = v8::Local<v8::Integer>(), v8::Local<v8::Integer> column = v8::Local<v8::Integer>())
+  v8::Local<v8::Value> ResourceName() const;
+  v8::Local<v8::Integer> ResourceLineOffset() const;
+  v8::Local<v8::Integer> ResourceColumnOffset() const;
+}
+```

package/pitch-deck-groove/node_modules/nan/doc/string_bytes.md

@@ -0,0 +1,81 @@
+## Strings & Bytes
+
+Miscellaneous string & byte encoding and decoding functionality provided for compatibility across supported versions of V8 and Node. Implemented by NAN to ensure that all encoding types are supported, even for older versions of Node where they are missing.
+
+ - <a href="#api_nan_encoding"><b><code>Nan::Encoding</code></b></a>
+ - <a href="#api_nan_encode"><b><code>Nan::Encode()</code></b></a>
+ - <a href="#api_nan_try_encode"><b><code>Nan::TryEncode()</code></b></a>
+ - <a href="#api_nan_decode_bytes"><b><code>Nan::DecodeBytes()</code></b></a>
+ - <a href="#api_nan_decode_write"><b><code>Nan::DecodeWrite()</code></b></a>
+
+
+<a name="api_nan_encoding"></a>
+### Nan::Encoding
+
+An enum representing the supported encoding types. A copy of `node::encoding` that is consistent across versions of Node.
+
+Definition:
+
+```c++
+enum Nan::Encoding { ASCII, UTF8, BASE64, UCS2, BINARY, HEX, BUFFER }
+```
+
+
+<a name="api_nan_encode"></a>
+### Nan::Encode()
+
+A wrapper around `node::Encode()` that provides a consistent implementation across supported versions of Node.
+
+**Note** `node::Encode()` was deprecated in Node 24 but will remain to maintain backwards compatibility. For Node 24 and higher consider using [`Nan::TryEncode()`](#api_nan_try_encode).
+
+Signature:
+
+```c++
+v8::Local<v8::Value> Nan::Encode(const void *buf,
+                                 size_t len,
+                                 enum Nan::Encoding encoding = BINARY);
+```
+
+
+<a name="api_nan_try_encode"></a>
+### Nan::TryEncode()
+
+A wrapper around `node::TryEncode()` that provides a consistent implementation across supported versions of Node.
+
+**Note** Only available in Node 24 and higher. For earlier versions use  [`Nan::Encode()`](#api_nan_encode).
+
+Signature:
+
+```c++
+Nan::MaybeLocal<v8::Value> Nan::TryEncode(const void *buf,
+                                 size_t len,
+                                 enum Nan::Encoding encoding = BINARY);
+```
+
+
+<a name="api_nan_decode_bytes"></a>
+### Nan::DecodeBytes()
+
+A wrapper around `node::DecodeBytes()` that provides a consistent implementation across supported versions of Node.
+
+Signature:
+
+```c++
+ssize_t Nan::DecodeBytes(v8::Local<v8::Value> val,
+                         enum Nan::Encoding encoding = BINARY);
+```
+
+
+<a name="api_nan_decode_write"></a>
+### Nan::DecodeWrite()
+
+A wrapper around `node::DecodeWrite()` that provides a consistent implementation across supported versions of Node.
+
+Signature:
+
+```c++
+ssize_t Nan::DecodeWrite(char *buf,
+                         size_t len,
+                         v8::Local<v8::Value> val,
+                         enum Nan::Encoding encoding = BINARY);
+```