@camjn/getargv 0.0.4 → 0.0.7

package/LICENSE.txt

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, 2023
+Camden Narzt <getargv@narzt.cam>. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -5,11 +5,24 @@
 
 This module allows you to query the arguments of other processes on macOS.
 
-## Installation
+## Module Installation
 
-Install the module and add to the application's package.json by executing:
+ - Install `libgetargv` to your system (see below).
+ - Install the module and add to the application's package.json by executing:
 
-    $ npm i @camjn/getargv
+    $ npm install --save-optional @camjn/getargv
+
+Saving this module as optional is important because it can only build on macOS, so npm needs to be able to exclude it on other OSs.
+
+## Library Installation
+
+ - To get access to `libgetargv`, sign up for an appropriate [sponsorship tier](https://github.com/sponsors/CamJN).
+ - Clone the `libgetargv` repo: `git clone https://github.com/getargv/getargv.git`.
+ - Running `make install_dylib`, installs the library to the `/usr/local/` prefix by default; you can change the install location with the `PREFIX` `make` variable: `make PREFIX=/opt install_dylib`.
+
+## Building `libgetargv`
+
+I've built `libgetargv` on macOS 10.7-13, using only the <abbr title="Command Line Tools">CLT</abbr> package, not the full Xcode install. If you need to override variables, do so inside the `make` command, eg: `make EXTRA_CPPFLAGS=-DMACRO EXTRA_CFLAGS=-std=c17 dylib`.
 
 ## Usage
 

package/dist/binding.d.ts

@@ -1,8 +1,3 @@
-interface GetArgv {
-    readonly PID_MAX: number;
-    readonly ARG_MAX: number;
-    get_argv_of_pid(pid: number, nuls: boolean, skip: number): string;
-    get_argv_and_argc_of_pid(pid: number): Array<string>;
-}
+import { GetArgv } from './types';
 declare const addon: GetArgv;
 export = addon;

package/dist/binding.js

@@ -1,7 +1,47 @@
 "use strict";
 const addon = require('../build/Release/getargv_native');
+addon.as_string = function as_string(pid, encoding, nuls, skip, options) {
+    switch (arguments.length) {
+        case 0: throw new TypeError('The "pid" argument must be specified');
+        case 1: throw new TypeError('The "encoding" argument must be specified');
+        case 2:
+        case 3:
+        case 4:
+        case 5: break;
+        default: throw new TypeError('Too many arguments were specified');
+    }
+    if (typeof pid !== "number") {
+        throw new TypeError('The "pid" argument must be a number');
+    }
+    if (typeof encoding !== "string") {
+        throw new TypeError(`The "encoding" argument must be a string, is a: ${typeof encoding}`);
+    }
+    const decoder = new TextDecoder(encoding, options);
+    const array = addon.get_argv_of_pid(pid, nuls !== null && nuls !== void 0 ? nuls : false, skip !== null && skip !== void 0 ? skip : 0);
+    return decoder.decode(array);
+};
+addon.as_array = function as_array(pid, encoding, options) {
+    switch (arguments.length) {
+        case 0: throw new TypeError('The "pid" argument must be specified');
+        case 1: throw new TypeError('The "encoding" argument must be specified');
+        case 2:
+        case 3: break;
+        default: throw new TypeError('Too many arguments were specified');
+    }
+    if (typeof pid !== "number") {
+        throw new TypeError('The "pid" argument must be a number');
+    }
+    if (typeof encoding !== "string") {
+        throw new TypeError(`The "encoding" argument must be a string, is a: ${typeof encoding}`);
+    }
+    const decoder = new TextDecoder(encoding, options);
+    const array = addon.get_argv_and_argc_of_pid(pid);
+    return array.map(b => decoder.decode(b));
+};
 exports.PID_MAX = addon.PID_MAX;
 exports.ARG_MAX = addon.ARG_MAX;
 exports.get_argv_of_pid = addon.get_argv_of_pid;
+exports.as_string = addon.as_string;
 exports.get_argv_and_argc_of_pid = addon.get_argv_and_argc_of_pid;
+exports.as_array = addon.as_array;
 module.exports = addon;

package/dist/types.d.ts

@@ -0,0 +1,100 @@
+/// <reference types="node" />
+type utf_8 = "unicode-1-1-utf-8" | "utf-8" | "utf8";
+type ibm866 = "866" | "cp866" | "csibm866" | "ibm866";
+type iso_8859_2 = "csisolatin2" | "iso-8859-2" | "iso-ir-101" | "iso8859-2" | "iso88592" | "iso_8859-2" | "iso_8859-2:1987" | "l2" | "latin2";
+type iso_8859_3 = "csisolatin3" | "iso-8859-3" | "iso-ir-109" | "iso8859-3" | "iso88593" | "iso_8859-3" | "iso_8859-3:1988" | "l3" | "latin3";
+type iso_8859_4 = "csisolatin4" | "iso-8859-4" | "iso-ir-110" | "iso8859-4" | "iso88594" | "iso_8859-4" | "iso_8859-4:1988" | "l4" | "latin4";
+type iso_8859_5 = "csisolatincyrillic" | "cyrillic" | "iso-8859-5" | "iso-ir-144" | "iso88595" | "iso_8859-5" | "iso_8859-5:1988";
+type iso_8859_6 = "arabic" | "asmo-708" | "csiso88596e" | "csiso88596i" | "csisolatinarabic" | "ecma-114" | "iso-8859-6" | "iso-8859-6-e" | "iso-8859-6-i" | "iso-ir-127" | "iso8859-6" | "iso88596" | "iso_8859-6" | "iso_8859-6:1987";
+type iso_8859_7 = "csisolatingreek" | "ecma-118" | "elot_928" | "greek" | "greek8" | "iso-8859-7" | "iso-ir-126" | "iso8859-7" | "iso88597" | "iso_8859-7" | "iso_8859-7:1987" | "sun_eu_greek";
+type iso_8859_8 = "csiso88598e" | "csisolatinhebrew" | "hebrew" | "iso-8859-8" | "iso-8859-8-e" | "iso-ir-138" | "iso8859-8" | "iso88598" | "iso_8859-8" | "iso_8859-8:1988" | "visual";
+type iso_8859_8i = "csiso88598i" | "iso-8859-8-i" | "logical";
+type iso_8859_10 = "csisolatin6" | "iso-8859-10" | "iso-ir-157" | "iso8859-10" | "iso885910" | "l6" | "latin6";
+type iso_8859_13 = "iso-8859-13" | "iso8859-13" | "iso885913";
+type iso_8859_14 = "iso-8859-14" | "iso8859-14" | "iso885914";
+type iso_8859_15 = "csisolatin9" | "iso-8859-15" | "iso8859-15" | "iso885915" | "l9" | "latin9";
+type iso_8859_16 = "iso-8859-16";
+type koi8_r = "cskoi8r" | "koi" | "koi8" | "koi8-r" | "koi8_r";
+type koi8_u = "koi8-u";
+type macintosh = "csmacintosh" | "mac" | "macintosh" | "x-mac-roman";
+type windows_874 = "dos-874" | "iso-8859-11" | "iso8859-11" | "iso885911" | "tis-620" | "windows-874";
+type windows_1250 = "cp1250" | "windows-1250" | "x-cp1250";
+type windows_1251 = "cp1251" | "windows-1251" | "x-cp1251";
+type windows_1252 = "ansi_x3.4-1968" | "ascii" | "cp1252" | "cp819" | "csisolatin1" | "ibm819" | "iso-8859-1" | "iso-ir-100" | "iso8859-1" | "iso88591" | "iso_8859-1" | "iso_8859-1:1987" | "l1" | "latin1" | "us-ascii" | "windows-1252" | "x-cp1252";
+type windows_1253 = "cp1253" | "windows-1253" | "x-cp1253";
+type windows_1254 = "cp1254" | "csisolatin5" | "iso-8859-9" | "iso-ir-148" | "iso8859-9" | "iso88599" | "iso_8859-9" | "iso_8859-9:1989" | "l5" | "latin5" | "windows-1254" | "x-cp1254";
+type windows_1255 = "cp1255" | "windows-1255" | "x-cp1255";
+type windows_1256 = "cp1256" | "windows-1256" | "x-cp1256";
+type windows_1257 = "cp1257" | "windows-1257" | "x-cp1257";
+type windows_1258 = "cp1258" | "windows-1258" | "x-cp1258";
+type x_mac_cyrillic = "x-mac-cyrillic" | "x-mac-ukrainian";
+type gbk = "chinese" | "csgb2312" | "csiso58gb231280" | "gb2312" | "gb_2312" | "gb_2312-80" | "gbk" | "iso-ir-58" | "x-gbk";
+type gb18030 = "gb18030";
+type hz_gb_2312 = "hz-gb-2312";
+type big5 = "big5" | "big5-hkscs" | "cn-big5" | "csbig5" | "x-x-big5";
+type euc_jp = "cseucpkdfmtjapanese" | "euc-jp" | "x-euc-jp";
+type iso_2022_jp = "csiso2022jp" | "iso-2022-jp";
+type shift_jis = "csshiftjis" | "ms_kanji" | "shift-jis" | "shift_jis" | "sjis" | "windows-31j" | "x-sjis";
+type euc_kr = "cseuckr" | "csksc56011987" | "euc-kr" | "iso-ir-149" | "korean" | "ks_c_5601-1987" | "ks_c_5601-1989" | "ksc5601" | "ksc_5601" | "windows-949";
+type iso_2022_kr = "csiso2022kr" | "iso-2022-kr";
+type utf_16be = "utf-16be";
+type utf_16le = "utf-16" | "utf-16le";
+type x_user_defined = "x-user-defined";
+type replacement = "iso-2022-cn" | "iso-2022-cn-ext";
+export type TextEncoding = utf_8 | ibm866 | iso_8859_2 | iso_8859_3 | iso_8859_4 | iso_8859_5 | iso_8859_6 | iso_8859_7 | iso_8859_8 | iso_8859_8i | iso_8859_10 | iso_8859_13 | iso_8859_14 | iso_8859_15 | iso_8859_16 | koi8_r | koi8_u | macintosh | windows_874 | windows_1250 | windows_1251 | windows_1252 | windows_1253 | windows_1254 | windows_1255 | windows_1256 | windows_1257 | windows_1258 | x_mac_cyrillic | gbk | gb18030 | hz_gb_2312 | big5 | euc_jp | iso_2022_jp | shift_jis | euc_kr | iso_2022_kr | utf_16be | utf_16le | x_user_defined | replacement;
+export type TextDecoderOptions = ConstructorParameters<typeof TextDecoder>[1];
+export interface GetArgv {
+    /** @constant
+      * @description the maximum value a pid may have on the system
+      */
+    readonly PID_MAX: number;
+    /** @constant
+      * @description the maximum number of bytes that can be passed as args to a process (including env vars, etc)
+      */
+    readonly ARG_MAX: number;
+    /**
+     * Gets the arguments of a process as an ArrayBuffer
+     * @param pid - The pid of the process whose arguments you want, must be between 0..{@link PID_MAX} inclusive.
+     * @param nuls - Whether to replace nul bytes with spaces for human consumption.
+     * @param skip - The number of leading args to skip past.
+     * @returns An ArrayBuffer representing the arguments of pid, formatted as requested.
+     * @throws {@link TypeError} if called with: missing pid argument, invalid number as pid, invalid number as skip.
+     * @throws {@link RangeError} if called with pid outside valid range: 0..{@link PID_MAX} inclusive.
+     * @throws {@link SystemError} if the underlying sysctl or parsing fails.
+     */
+    get_argv_of_pid(pid: number, nuls: boolean, skip: number): ArrayBuffer;
+    /**
+     * Gets the arguments of a process as a string
+     * @param pid - The pid of the process whose arguments you want, must be between 0..{@link PID_MAX} inclusive.
+     * @param encoding - The encoding to attempt to apply to the arguments. Must be an enumerated value of {@link TextEncoding}.
+     * @param nuls - Whether to replace nul bytes with spaces for human consumption.
+     * @param skip - The number of leading args to skip past.
+     * @param options - The options to use when decoding the process' arguments' bytes into a string.
+     * @returns A string representing the arguments of pid, formatted as requested.
+     * @throws {@link TypeError} if called with: missing pid, missing encoding argument, invalid number as pid, invalid number as skip, or if `options.fatal` is true and it encounters malformed data while decoding.
+     * @throws {@link RangeError} if called with invalid encoding argument or pid outside valid range: 0..{@link PID_MAX} inclusive.
+     * @throws {@link SystemError} if the underlying sysctl or parsing fails.
+     */
+    as_string(pid: number, encoding: TextEncoding, nuls?: boolean, skip?: number, options?: TextDecoderOptions): string;
+    /**
+     * Gets the arguments of a process as an array of ArrayBuffers
+     * @param pid - The pid of the process whose arguments you want, must be between 0..{@link PID_MAX} inclusive.
+     * @returns An array of ArrayBuffers representing the arguments of pid.
+     * @throws {@link TypeError} if called with: missing pid, too many arguments, invalid number as pid.
+     * @throws {@link RangeError} if called with pid outside valid range: 0..{@link PID_MAX} inclusive.
+     * @throws {@link SystemError} if the underlying sysctl or parsing fails.
+     */
+    get_argv_and_argc_of_pid(pid: number): Array<ArrayBuffer>;
+    /**
+     * Gets the arguments of a process as an array of strings
+     * @param pid - The pid of the process whose arguments you want, must be between 0..{@link PID_MAX} inclusive.
+     * @param encoding - The encoding to attempt to apply to the arguments. Must be an enumerated value of {@link TextEncoding}.
+     * @param options - The options to use when decoding the process' arguments' bytes into strings.
+     * @returns An array of strings representing the arguments of pid.
+     * @throws {@link TypeError} if called with: missing pid, missing encoding argument, too many arguments, invalid number as pid, or if `options.fatal` is true and it encounters malformed data while decoding.
+     * @throws {@link RangeError} if called with: invalid encoding argument, pid outside valid range: 0..{@link PID_MAX} inclusive.
+     * @throws {@link SystemError} if the underlying sysctl or parsing fails.
+     */
+    as_array(pid: number, encoding: TextEncoding, options?: TextDecoderOptions): Array<string>;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -3,8 +3,10 @@
         "getargv": "lib/cli.js"
     },
     "devDependencies": {
-        "@types/node": "^18.11.18",
-        "typescript": "^4.9.4"
+        "@types/node": "^18.15.5",
+        "typedoc": "^0.23.28",
+        "typedoc-plugin-missing-exports": "^1.0.0",
+        "typescript": "^5.0.2"
     },
     "os": [
         "darwin"
@@ -16,17 +18,21 @@
     "name": "@camjn/getargv",
     "homepage": "https://getargv.narzt.cam/",
     "author": "Camden Narzt <getargv@narzt.cam>",
-    "version": "0.0.4",
+    "version": "0.0.7",
     "description": "This library allows you to query the arguments of other processes on macOS.",
     "main": "dist/binding.js",
     "scripts": {
+        "prebuild": "tsc",
         "build": "node-gyp configure build",
-        "pretest": "tsc",
+        "pretest": "npm run build",
         "test": "node --napi-modules ./test/test_binding.js",
-        "precli": "tsc",
-        "prepack": "tsc",
+        "prepack": "npm run build",
+        "precli": "npm run build",
         "cli": "node dist/cli.js",
-        "console": "node --napi-modules -r ./build/Release/getargv_native -e 'const GetArgv = require.cache[Object.keys(require.cache)[0]].exports;' -i"
+        "preconsole": "npm run build",
+        "console": "node --napi-modules -r ./dist/binding.js -e 'const GetArgv = require.cache[Object.keys(require.cache)[0]].exports;' -i",
+        "docs": "typedoc --tsconfig $PWD/tsconfig.json lib/types.ts",
+        "start": "npm run console"
     },
     "files": [
         "/README.md",

package/src/getargv.c

@@ -19,7 +19,7 @@ napi_value get_undefined(napi_env env) {
 }
 
 napi_value create_system_error(napi_env env, errno_t err) {
-  //we skip checking status in here because we already have a failure
+  // we skip checking status in here because we already have a failure
   napi_value code;
   napi_create_string_utf8(env, "ERR_SYSTEM_ERROR", NAPI_AUTO_LENGTH, &code);
 
@@ -129,15 +129,16 @@ napi_value GetArgvOfPid(napi_env env, napi_callback_info info) {
 
     napi_throw(env, error);
   } else {
-    if (napi_create_string_utf8(env, result.start_pointer,
+    char *innerbuff = NULL;
+    if (napi_create_arraybuffer(env,
                                 result.end_pointer - result.start_pointer + 1,
-                                &args) != napi_ok) {
-      // args not guaranteed to be utf8 or even latin1/ascii, but ruby, swift,
-      // and node all want strings to be properly encoded
+                                (void **)&innerbuff, &args) != napi_ok) {
       napi_throw_error(env, "ERR_INTERNAL_ASSERTION",
                        "Unable to create return value");
+    } else {
+      memcpy(innerbuff, result.start_pointer, result.end_pointer - result.start_pointer + 1);
     }
-    free(result.buffer);
+    free_ArgvResult(&result);
   }
 
   return args;
@@ -158,24 +159,24 @@ napi_value GetArgvAndArgcOfPid(napi_env env, napi_callback_info info) {
                        "Unable to create return value");
     } else {
       for (size_t i = 0; i < result.argc; i++) {
-        napi_value string;
-        // args not guaranteed to be utf8 or even latin1/ascii, but ruby, swift,
-        // and node all want strings to be properly encoded...
-        if (napi_ok != napi_create_string_utf8(env, result.argv[i],
-                                               NAPI_AUTO_LENGTH, &string)) {
+        napi_value buffer;
+        char *innerbuff = NULL;
+        size_t len = strlen(result.argv[i]) + 1;
+        if (napi_create_arraybuffer(env, len, (void **)&innerbuff, &buffer) !=
+            napi_ok) {
           napi_throw_error(env, "ERR_INTERNAL_ASSERTION",
-                           "Unable to create string");
+                           "Unable to create ArrayBuffer");
           break;
         }
-        if (napi_ok != napi_set_element(env, args, i, string)) {
+        memcpy(innerbuff, result.argv[i], len);
+        if (napi_ok != napi_set_element(env, args, i, buffer)) {
           napi_throw_error(env, "ERR_INTERNAL_ASSERTION",
                            "Unable to populate array");
           break;
         }
       }
     }
-    free(result.argv);
-    free(result.buffer);
+    free_ArgvArgcResult(&result);
   }
 
   return args;