@shahwali/archangel 0.0.3 → 0.0.4

package/README.md

@@ -1,171 +1,195 @@
-# Archangel
-
-A small library for building web-based desktop applications in Zig.
-
-## Creating an Archangel Application
-
-### Prerequisites
-
-- Zig compiler, version **0.15.2** or higher
-- Platform specific dependencies
-  - Windows
-    - WebView2
-  - Linux
-    - webkit2gtk-4.1
-  - MacOS
-    - WebKit
-
-There is currently no CLI or similar tooling for bootstrapping an Archangel application. You will need to do the following steps manually.
-
-### Initialize a New Project
-
-You can bring your own frontend setup for your Archangel application, but below steps will assume you are using Vite as your build tool.
-
-Create your Vite project
-
-```sh
-# or npm, yarn, pnpm e.t.c
-$ bun create vite
-$ cd <app-name>
-$ bun add @shahwali/archangel
-```
-
-Create your archangel source directory inside the project
-
-```sh
-$ mkdir src-archangel
-$ cd src-archangel
-$ zig init --minimal
-$ zig fetch --save git+https://codeberg.org/shahwali/archangel.git
-```
-
-Archangel is quite flexible in how you want to use it, but an `archangel.conf.zon` file is required to configure the application. Place it in src-archangel with the following content.
-
-```
-.{
-    .app_name = "My Example App",
-    .dev_url = "http://localhost:5173/", // Must be the same as the url your are hosting your frontend on locally.
-    .frontend_build_path = "../dist", // Must be the same as the path your frontend is built to.
-    .window = .{
-        .width = 1280,
-        .height = 720,
-        .title = "My App",
-    },
-}
-```
-
-For a simple minimal Archangel application, you can create the following `main.zig` file in the `src-archangel/src`.
-
-```zig
-const std = @import("std");
-const archangel = @import("archangel");
-
-const HelloResponse = struct {
-    message: []const u8,
-    timestamp: i64,
-};
-
-fn helloHandler(name: []const u8) !HelloResponse {
-    if (std.mem.eql(u8, name, "John")) {
-        return error.InvalidName;
-    }
-
-    return HelloResponse{
-        .message = try std.fmt.allocPrint(std.heap.page_allocator, "Hello, {s}!", .{name}),
-        .timestamp = std.time.timestamp(),
-    };
-}
-
-pub fn main() !void {
-    // Use whatever allocator you want.
-    var gpa = std.heap.DebugAllocator(.{ .safety = true }).init;
-    const allocator = gpa.allocator();
-
-    defer {
-        if (gpa.deinit() == .leak) {
-            @panic("memory leak detected!");
-        }
-    }
-
-    var app = try archangel.App.init(
-        allocator,
-        .{
-            .{ "hello", archangel.handler.create(helloHandler) },
-        },
-    );
-    defer app.deinit();
-
-    try app.run();
-}
-```
-
-And then you can build it with the following `build.zig`
-
-```zig
-const std = @import("std");
-const archangel = @import("archangel");
-
-pub fn build(b: *std.Build) void {
-    const target = b.standardTargetOptions(.{
-        .default_target = .{
-            .cpu_model = .baseline,
-        },
-    });
-    const optimize = b.standardOptimizeOption(.{});
-
-    const exe, const archangel_dep = archangel.createApp(b, .{
-        .exe_name = "testapp",
-        .exe_create_options = .{
-            .target = target,
-            .optimize = optimize,
-            .root_source_file = b.path("src/main.zig"),
-        },
-    });
-
-    exe.root_module.addImport("archangel", archangel_dep.module("archangel"));
-}
-```
-
-The `archangel.createApp` function will create an executable with the given config, and create a `run` step that you can use to run the application. It also creates an option `dev` which can be passed to enable development mode. In development mode, the webview will navigate to the `dev_url` you specified in the archange.conf.zon file, rather than embedding the frontend in the binary, thus allowing you to take advantage of HMR-like features with a tool like Vite for example.
-
-For a more advanced example, you can look at [the testapp example](examples/testapp/src-archangel). This example shows a more realistic use case of archangel, where your app is contained to a Zig module which is then imported in your executable entry point. The module can then have its own tests and be self contained.
-
-### Run the application in development mode
-
-In the frontend root, start the dev server
-
-```sh
-$ bun dev
-```
-
-In the archangel root (src-archangel), start the application.
-
-```sh
-$ zig build run -Ddev
-```
-
-### Build the application for production
-
-In the frontend root, build the production version of the frontend
-
-```sh
-$ bun run build
-```
-
-In the archangel root (src-archangel), build the application.
-
-```sh
-$ zig build
-```
-
-You will find the executable in the `zig-out/bin` directory.
-
-You can also run the application to test it in production mode
-
-```sh
-$ zig build run
-```
-
-### Bundling
-
-Archangel does not come with a bundler, although it is planned to add one in the future. For now, you will have to manually bundle your application using whatever tool your prefer for your designated platform. Luckily, the Zig build system is quite powerful and one can easily modify the `build.zig` to do all kinds of things, such as installing additional binaries, libraries, assets and resources alongside your application executable. You can then use a tool like WiX on Windows or hdiutil on macOS to create an installer for your application.
+# Archangel
+
+A small library for building web-based desktop applications in Zig.
+
+## Creating an Archangel Application
+
+### Prerequisites
+
+- Zig compiler, version **0.15.2** or higher
+- Platform specific dependencies
+  - Windows
+    - WebView2
+  - Linux
+    - webkit2gtk-4.1
+  - MacOS
+    - WebKit
+
+There is currently no CLI or similar tooling for bootstrapping an Archangel application. You will need to do the following steps manually.
+
+### Initialize a New Project
+
+You can bring your own frontend setup for your Archangel application, but below steps will assume you are using Vite as your build tool.
+
+Create your Vite project
+
+```sh
+# or npm, yarn, pnpm e.t.c
+$ bun create vite
+$ cd <app-name>
+$ bun add @shahwali/archangel
+```
+
+Create your archangel source directory inside the project
+
+```sh
+$ mkdir src-archangel
+$ cd src-archangel
+$ zig init --minimal
+$ zig fetch --save git+https://codeberg.org/shahwali/archangel.git
+```
+
+Archangel is quite flexible in how you want to use it, but an `archangel.conf.zon` file is required to configure the application. Place it in src-archangel with the following content.
+
+```
+.{
+    .app_name = "My Example App",
+    .dev_url = "http://localhost:5173/", // Must be the same as the url your are hosting your frontend on locally.
+    .frontend_build_path = "../dist", // Must be the same as the path your frontend is built to.
+    .bindings_path = "../src/generated",
+    .window = .{
+        .width = 1280,
+        .height = 720,
+        .title = "My App",
+    },
+}
+```
+
+For a simple minimal Archangel application, you can create the following `main.zig` file in the `src-archangel/src`.
+
+```zig
+const std = @import("std");
+const archangel = @import("archangel");
+
+const HelloResponse = struct {
+    message: []const u8,
+    timestamp: i64,
+};
+
+fn helloHandler(name: []const u8) !HelloResponse {
+    if (std.mem.eql(u8, name, "John")) {
+        return error.InvalidName;
+    }
+
+    return HelloResponse{
+        .message = try std.fmt.allocPrint(std.heap.page_allocator, "Hello, {s}!", .{name}),
+        .timestamp = std.time.timestamp(),
+    };
+}
+
+pub fn main() !void {
+    // Use whatever allocator you want.
+    var gpa = std.heap.DebugAllocator(.{ .safety = true }).init;
+    const allocator = gpa.allocator();
+
+    defer {
+        if (gpa.deinit() == .leak) {
+            @panic("memory leak detected!");
+        }
+    }
+
+    var app = try archangel.App.init(
+        allocator,
+        .{
+            .{ "hello", archangel.handler.create(helloHandler) },
+        },
+    );
+    defer app.deinit();
+
+    try app.run();
+}
+```
+
+And then you can build it with the following `build.zig`
+
+```zig
+const std = @import("std");
+const archangel = @import("archangel");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{
+        .default_target = .{
+            .cpu_model = .baseline,
+        },
+    });
+    const optimize = b.standardOptimizeOption(.{});
+
+    const exe, const archangel_dep = archangel.createApp(b, .{
+        .exe_name = "testapp",
+        .exe_create_options = .{
+            .target = target,
+            .optimize = optimize,
+            .root_source_file = b.path("src/main.zig"),
+        },
+    });
+
+    exe.root_module.addImport("archangel", archangel_dep.module("archangel"));
+}
+```
+
+The `archangel.createApp` function will create an executable with the given config, and create a `run` step that you can use to run the application. It also creates an option `dev` which can be passed to enable development mode. In development mode, the webview will navigate to the `dev_url` you specified in the archange.conf.zon file, rather than embedding the frontend in the binary, thus allowing you to take advantage of HMR-like features with a tool like Vite for example.
+
+For a more advanced example, you can look at [the testapp example](examples/testapp/src-archangel). This example shows a more realistic use case of archangel, where your app is contained to a Zig module which is then imported in your executable entry point. The module can then have its own tests and be self contained.
+
+### Run the application in development mode
+
+In the frontend root, start the dev server
+
+```sh
+$ bun dev
+```
+
+In the archangel root (src-archangel), start the application.
+
+```sh
+$ zig build run -Ddev
+```
+
+### Build the application for production
+
+In the frontend root, build the production version of the frontend
+
+```sh
+$ bun run build
+```
+
+In the archangel root (src-archangel), build the application.
+
+```sh
+$ zig build
+```
+
+You will find the executable in the `zig-out/bin` directory.
+
+You can also run the application to test it in production mode
+
+```sh
+$ zig build run
+```
+
+## Bundling
+
+Archangel does not come with a bundler, although it is planned to add one in the future. For now, you will have to manually bundle your application using whatever tool your prefer for your designated platform. Luckily, the Zig build system is quite powerful and one can easily modify the `build.zig` to do all kinds of things, such as installing additional binaries, libraries, assets and resources alongside your application executable. You can then use a tool like WiX on Windows or hdiutil on macOS to create an installer for your application.
+
+## Experimental Features
+
+### Generate typescript bindings
+
+You can generate typescript bindings for your handlers using the bindings step. To do this you must create an `archangel_options` declaration in your entry point file.
+
+```zig
+const testapp = @import("testapp");
+const archangel = @import("archangel");
+
+pub const archangel_options: archangel.Options(testapp.handlers) = .{
+    .skip_binding = .initComptime(.{.{"hello"}}), // You can also specify handlers to skip/ignore.
+};
+
+pub fn main() !void ....
+```
+
+```sh
+$ zig build bindings
+```
+
+This will place the bindings in the `bindings_path` specified in your `archangel.conf.zon`.

package/dist/index.cjs.map

@@ -3,9 +3,9 @@
   "sources": ["..\\src\\internal\\binding.ts", "..\\src\\index.ts"],
   "sourcesContent": [
     "export interface BindingError {\n  __archangel_error: string;\n  __archangel_error_trace?: string;\n}\n\nexport function isBindingError(result: any): result is BindingError {\n  if (result === null || typeof result !== \"object\") {\n    return false;\n  }\n\n  return \"__archangel_error\" in result && typeof result.__archangel_error === \"string\";\n}\n\nexport function throwBindingError(error: BindingError): never {\n  throw new Error(error.__archangel_error, {\n    cause:\n      error.__archangel_error_trace ?? new Error(\"Error trace only available in debug builds.\"),\n  });\n}\n\nexport function handleBindingResult<T>(result: any): T {\n  if (isBindingError(result)) {\n    throwBindingError(result);\n  }\n  return result as T;\n}\n\ntype BindingFn<TArgs = any, TResult = any> = (args: TArgs) => Promise<TResult>;\n\nexport function createBinding<TArgs, TResult>(windowKey: string): BindingFn<TArgs, TResult> {\n  const fn = (window as any)[windowKey];\n\n  if (!fn) {\n    console.warn(`Backend binding not available: ${windowKey}`);\n  }\n\n  return async (args: TArgs) => {\n    if (!fn) {\n      throw new Error(`Backend binding not available: ${windowKey}`);\n    }\n\n    const result = await fn(args);\n    return handleBindingResult(result);\n  };\n}\n",
-    "import { createBinding } from \"./internal/binding\";\n\ntype InvokeRequest = {\n  function: string;\n  args: string;\n};\n\nexport type InvokeArgs = Record<string, any>;\n\nconst _invoke = createBinding<InvokeRequest, any>(\"__invoke__\");\n\nexport interface InvokeHandlers {}\n\n// Helper type to check if args is empty object, null, undefined, or void\ntype IsEmptyArgs<T> =\n  T extends Record<string, never> ? true : T extends null | undefined | void ? true : false;\n\n/**\n * Type-safe invoke method for calling backend functions\n */\nexport async function invoke<K extends keyof InvokeHandlers>(\n  functionName: K,\n  ...args: IsEmptyArgs<InvokeHandlers[K][\"args\"]> extends true\n    ? [args?: InvokeHandlers[K][\"args\"]]\n    : [args: InvokeHandlers[K][\"args\"]]\n): Promise<InvokeHandlers[K][\"result\"]>;\n\n// Fallback overload for when InvokeHandlers is empty or for dynamic usage\nexport async function invoke<T = any>(functionName: string, args?: any): Promise<T>;\n\nexport async function invoke(functionName: string, args: any = {}): Promise<any> {\n  return _invoke({\n    function: functionName,\n    args: JSON.stringify(args),\n  });\n}\n\ntype Listener<T = any> = (payload: T) => void;\n\nconst listeners = new Map<string, Set<Listener>>();\n\n/**\n * Subscribe to events emitted from the backend\n * @param event - Name of the event to listen for\n * @param cb - Callback function to execute when the event is emitted\n * @returns Unsubscribe function to stop listening to the event\n */\nexport function on<T = any>(event: string, cb: Listener<T>) {\n  let set = listeners.get(event);\n  if (!set) {\n    set = new Set();\n    listeners.set(event, set);\n  }\n\n  set.add(cb);\n\n  return () => {\n    set!.delete(cb);\n    if (set!.size === 0) listeners.delete(event);\n  };\n}\n\n/**\n * Subscribe to events emitted from the backend (fires only once)\n * @param event - Name of the event to listen for\n * @param cb - Callback function to execute when the event is emitted\n * @returns Unsubscribe function to stop listening to the event\n */\nexport function once<T = any>(event: string, cb: Listener<T>) {\n  const wrappedCallback: Listener<T> = (payload) => {\n    cb(payload);\n    unsubscribe();\n  };\n\n  const unsubscribe = on(event, wrappedCallback);\n\n  return unsubscribe;\n}\n\nfunction emit<T = any>(event: string, payload: T) {\n  const set = listeners.get(event);\n  if (!set) return;\n  for (const cb of set) cb(payload);\n}\n\nObject.defineProperty(window, \"__emit__\", {\n  value: emit,\n  writable: false,\n  configurable: false,\n});\n\nexport type { InvokeRequest, Listener };\n"
+    "import { createBinding } from \"./internal/binding\";\n\ntype InvokeRequest = {\n  function: string;\n  args: string;\n};\n\nexport type InvokeArgs = Record<string, any>;\n\nconst _invoke = createBinding<InvokeRequest, any>(\"__invoke__\");\n\nexport interface InvokeHandlers {}\n\ntype IsEmptyArgs<T> =\n  T extends Record<string, never> ? true : T extends null | undefined | void ? true : false;\n\n/**\n * Generic invoke method for calling backend functions\n * @param functionName - Name of the backend function to call\n * @param args - Arguments to pass to the function\n * @returns Promise resolving to the result\n * Type-safe invoke method for calling backend functions\n */\nexport async function invoke<K extends keyof InvokeHandlers>(\n  functionName: K,\n  ...args: IsEmptyArgs<InvokeHandlers[K][\"args\"]> extends true\n    ? [args?: InvokeHandlers[K][\"args\"]]\n    : [args: InvokeHandlers[K][\"args\"]]\n): Promise<InvokeHandlers[K][\"result\"]>;\n\n// Fallback overload for when InvokeHandlers is empty or for dynamic usage\nexport async function invoke<T = any>(functionName: string, args?: any): Promise<T>;\n\nexport async function invoke(functionName: string, args: any = {}): Promise<any> {\n  return _invoke({\n    function: functionName,\n    args: JSON.stringify(args),\n  });\n}\n\ntype Listener<T = any> = (payload: T) => void;\n\nconst listeners = new Map<string, Set<Listener>>();\n\n/**\n * Subscribe to events emitted from the backend\n * @param event - Name of the event to listen for\n * @param cb - Callback function to execute when the event is emitted\n * @returns Unsubscribe function to stop listening to the event\n */\nexport function on<T = any>(event: string, cb: Listener<T>) {\n  let set = listeners.get(event);\n  if (!set) {\n    set = new Set();\n    listeners.set(event, set);\n  }\n\n  set.add(cb);\n\n  return () => {\n    set!.delete(cb);\n    if (set!.size === 0) listeners.delete(event);\n  };\n}\n\n/**\n * Subscribe to events emitted from the backend (fires only once)\n * @param event - Name of the event to listen for\n * @param cb - Callback function to execute when the event is emitted\n * @returns Unsubscribe function to stop listening to the event\n */\nexport function once<T = any>(event: string, cb: Listener<T>) {\n  const wrappedCallback: Listener<T> = (payload) => {\n    cb(payload);\n    unsubscribe();\n  };\n\n  const unsubscribe = on(event, wrappedCallback);\n\n  return unsubscribe;\n}\n\nfunction emit<T = any>(event: string, payload: T) {\n  const set = listeners.get(event);\n  if (!set) return;\n  for (const cb of set) cb(payload);\n}\n\nObject.defineProperty(window, \"__emit__\", {\n  value: emit,\n  writable: false,\n  configurable: false,\n});\n\nexport type { InvokeRequest, Listener };\n"
   ],
-  "mappings": ";0kBAKO,SAAS,CAAc,CAAC,EAAqC,CAClE,GAAI,IAAW,MAAQ,OAAO,IAAW,SACvC,MAAO,GAGT,MAAO,sBAAuB,GAAU,OAAO,EAAO,oBAAsB,SAGvE,SAAS,CAAiB,CAAC,EAA4B,CAC5D,MAAU,MAAM,EAAM,kBAAmB,CACvC,MACE,EAAM,yBAA+B,MAAM,6CAA6C,CAC5F,CAAC,EAGI,SAAS,CAAsB,CAAC,EAAgB,CACrD,GAAI,EAAe,CAAM,EACvB,EAAkB,CAAM,EAE1B,OAAO,EAKF,SAAS,CAA6B,CAAC,EAA8C,CAC1F,IAAM,EAAM,OAAe,GAE3B,GAAI,CAAC,EACH,QAAQ,KAAK,kCAAkC,GAAW,EAG5D,MAAO,OAAO,IAAgB,CAC5B,GAAI,CAAC,EACH,MAAU,MAAM,kCAAkC,GAAW,EAG/D,IAAM,EAAS,MAAM,EAAG,CAAI,EAC5B,OAAO,EAAoB,CAAM,GCjCrC,IAAM,EAAU,EAAkC,YAAY,EAqB9D,eAAsB,CAAM,CAAC,EAAsB,EAAY,CAAC,EAAiB,CAC/E,OAAO,EAAQ,CACb,SAAU,EACV,KAAM,KAAK,UAAU,CAAI,CAC3B,CAAC,EAKH,IAAM,EAAY,IAAI,IAQf,SAAS,CAAW,CAAC,EAAe,EAAiB,CAC1D,IAAI,EAAM,EAAU,IAAI,CAAK,EAC7B,GAAI,CAAC,EACH,EAAM,IAAI,IACV,EAAU,IAAI,EAAO,CAAG,EAK1B,OAFA,EAAI,IAAI,CAAE,EAEH,IAAM,CAEX,GADA,EAAK,OAAO,CAAE,EACV,EAAK,OAAS,EAAG,EAAU,OAAO,CAAK,GAUxC,SAAS,CAAa,CAAC,EAAe,EAAiB,CAM5D,IAAM,EAAc,EAAG,EALc,CAAC,IAAY,CAChD,EAAG,CAAO,EACV,EAAY,EAG+B,EAE7C,OAAO,EAGT,SAAS,CAAa,CAAC,EAAe,EAAY,CAChD,IAAM,EAAM,EAAU,IAAI,CAAK,EAC/B,GAAI,CAAC,EAAK,OACV,QAAW,KAAM,EAAK,EAAG,CAAO,EAGlC,OAAO,eAAe,OAAQ,WAAY,CACxC,MAAO,EACP,SAAU,GACV,aAAc,EAChB,CAAC",
+  "mappings": ";0kBAKO,SAAS,CAAc,CAAC,EAAqC,CAClE,GAAI,IAAW,MAAQ,OAAO,IAAW,SACvC,MAAO,GAGT,MAAO,sBAAuB,GAAU,OAAO,EAAO,oBAAsB,SAGvE,SAAS,CAAiB,CAAC,EAA4B,CAC5D,MAAU,MAAM,EAAM,kBAAmB,CACvC,MACE,EAAM,yBAA+B,MAAM,6CAA6C,CAC5F,CAAC,EAGI,SAAS,CAAsB,CAAC,EAAgB,CACrD,GAAI,EAAe,CAAM,EACvB,EAAkB,CAAM,EAE1B,OAAO,EAKF,SAAS,CAA6B,CAAC,EAA8C,CAC1F,IAAM,EAAM,OAAe,GAE3B,GAAI,CAAC,EACH,QAAQ,KAAK,kCAAkC,GAAW,EAG5D,MAAO,OAAO,IAAgB,CAC5B,GAAI,CAAC,EACH,MAAU,MAAM,kCAAkC,GAAW,EAG/D,IAAM,EAAS,MAAM,EAAG,CAAI,EAC5B,OAAO,EAAoB,CAAM,GCjCrC,IAAM,EAAU,EAAkC,YAAY,EAwB9D,eAAsB,CAAM,CAAC,EAAsB,EAAY,CAAC,EAAiB,CAC/E,OAAO,EAAQ,CACb,SAAU,EACV,KAAM,KAAK,UAAU,CAAI,CAC3B,CAAC,EAKH,IAAM,EAAY,IAAI,IAQf,SAAS,CAAW,CAAC,EAAe,EAAiB,CAC1D,IAAI,EAAM,EAAU,IAAI,CAAK,EAC7B,GAAI,CAAC,EACH,EAAM,IAAI,IACV,EAAU,IAAI,EAAO,CAAG,EAK1B,OAFA,EAAI,IAAI,CAAE,EAEH,IAAM,CAEX,GADA,EAAK,OAAO,CAAE,EACV,EAAK,OAAS,EAAG,EAAU,OAAO,CAAK,GAUxC,SAAS,CAAa,CAAC,EAAe,EAAiB,CAM5D,IAAM,EAAc,EAAG,EALc,CAAC,IAAY,CAChD,EAAG,CAAO,EACV,EAAY,EAG+B,EAE7C,OAAO,EAGT,SAAS,CAAa,CAAC,EAAe,EAAY,CAChD,IAAM,EAAM,EAAU,IAAI,CAAK,EAC/B,GAAI,CAAC,EAAK,OACV,QAAW,KAAM,EAAK,EAAG,CAAO,EAGlC,OAAO,eAAe,OAAQ,WAAY,CACxC,MAAO,EACP,SAAU,GACV,aAAc,EAChB,CAAC",
   "debugId": "A5594DDE138E4E6D64756E2164756E21",
   "names": []
 }

package/dist/index.d.ts

@@ -7,6 +7,10 @@ export interface InvokeHandlers {
 }
 type IsEmptyArgs<T> = T extends Record<string, never> ? true : T extends null | undefined | void ? true : false;
 /**
+ * Generic invoke method for calling backend functions
+ * @param functionName - Name of the backend function to call
+ * @param args - Arguments to pass to the function
+ * @returns Promise resolving to the result
  * Type-safe invoke method for calling backend functions
  */
 export declare function invoke<K extends keyof InvokeHandlers>(functionName: K, ...args: IsEmptyArgs<InvokeHandlers[K]["args"]> extends true ? [args?: InvokeHandlers[K]["args"]] : [args: InvokeHandlers[K]["args"]]): Promise<InvokeHandlers[K]["result"]>;

package/dist/index.js.map

@@ -3,9 +3,9 @@
   "sources": ["..\\src\\internal\\binding.ts", "..\\src\\index.ts"],
   "sourcesContent": [
     "export interface BindingError {\n  __archangel_error: string;\n  __archangel_error_trace?: string;\n}\n\nexport function isBindingError(result: any): result is BindingError {\n  if (result === null || typeof result !== \"object\") {\n    return false;\n  }\n\n  return \"__archangel_error\" in result && typeof result.__archangel_error === \"string\";\n}\n\nexport function throwBindingError(error: BindingError): never {\n  throw new Error(error.__archangel_error, {\n    cause:\n      error.__archangel_error_trace ?? new Error(\"Error trace only available in debug builds.\"),\n  });\n}\n\nexport function handleBindingResult<T>(result: any): T {\n  if (isBindingError(result)) {\n    throwBindingError(result);\n  }\n  return result as T;\n}\n\ntype BindingFn<TArgs = any, TResult = any> = (args: TArgs) => Promise<TResult>;\n\nexport function createBinding<TArgs, TResult>(windowKey: string): BindingFn<TArgs, TResult> {\n  const fn = (window as any)[windowKey];\n\n  if (!fn) {\n    console.warn(`Backend binding not available: ${windowKey}`);\n  }\n\n  return async (args: TArgs) => {\n    if (!fn) {\n      throw new Error(`Backend binding not available: ${windowKey}`);\n    }\n\n    const result = await fn(args);\n    return handleBindingResult(result);\n  };\n}\n",
-    "import { createBinding } from \"./internal/binding\";\n\ntype InvokeRequest = {\n  function: string;\n  args: string;\n};\n\nexport type InvokeArgs = Record<string, any>;\n\nconst _invoke = createBinding<InvokeRequest, any>(\"__invoke__\");\n\nexport interface InvokeHandlers {}\n\n// Helper type to check if args is empty object, null, undefined, or void\ntype IsEmptyArgs<T> =\n  T extends Record<string, never> ? true : T extends null | undefined | void ? true : false;\n\n/**\n * Type-safe invoke method for calling backend functions\n */\nexport async function invoke<K extends keyof InvokeHandlers>(\n  functionName: K,\n  ...args: IsEmptyArgs<InvokeHandlers[K][\"args\"]> extends true\n    ? [args?: InvokeHandlers[K][\"args\"]]\n    : [args: InvokeHandlers[K][\"args\"]]\n): Promise<InvokeHandlers[K][\"result\"]>;\n\n// Fallback overload for when InvokeHandlers is empty or for dynamic usage\nexport async function invoke<T = any>(functionName: string, args?: any): Promise<T>;\n\nexport async function invoke(functionName: string, args: any = {}): Promise<any> {\n  return _invoke({\n    function: functionName,\n    args: JSON.stringify(args),\n  });\n}\n\ntype Listener<T = any> = (payload: T) => void;\n\nconst listeners = new Map<string, Set<Listener>>();\n\n/**\n * Subscribe to events emitted from the backend\n * @param event - Name of the event to listen for\n * @param cb - Callback function to execute when the event is emitted\n * @returns Unsubscribe function to stop listening to the event\n */\nexport function on<T = any>(event: string, cb: Listener<T>) {\n  let set = listeners.get(event);\n  if (!set) {\n    set = new Set();\n    listeners.set(event, set);\n  }\n\n  set.add(cb);\n\n  return () => {\n    set!.delete(cb);\n    if (set!.size === 0) listeners.delete(event);\n  };\n}\n\n/**\n * Subscribe to events emitted from the backend (fires only once)\n * @param event - Name of the event to listen for\n * @param cb - Callback function to execute when the event is emitted\n * @returns Unsubscribe function to stop listening to the event\n */\nexport function once<T = any>(event: string, cb: Listener<T>) {\n  const wrappedCallback: Listener<T> = (payload) => {\n    cb(payload);\n    unsubscribe();\n  };\n\n  const unsubscribe = on(event, wrappedCallback);\n\n  return unsubscribe;\n}\n\nfunction emit<T = any>(event: string, payload: T) {\n  const set = listeners.get(event);\n  if (!set) return;\n  for (const cb of set) cb(payload);\n}\n\nObject.defineProperty(window, \"__emit__\", {\n  value: emit,\n  writable: false,\n  configurable: false,\n});\n\nexport type { InvokeRequest, Listener };\n"
+    "import { createBinding } from \"./internal/binding\";\n\ntype InvokeRequest = {\n  function: string;\n  args: string;\n};\n\nexport type InvokeArgs = Record<string, any>;\n\nconst _invoke = createBinding<InvokeRequest, any>(\"__invoke__\");\n\nexport interface InvokeHandlers {}\n\ntype IsEmptyArgs<T> =\n  T extends Record<string, never> ? true : T extends null | undefined | void ? true : false;\n\n/**\n * Generic invoke method for calling backend functions\n * @param functionName - Name of the backend function to call\n * @param args - Arguments to pass to the function\n * @returns Promise resolving to the result\n * Type-safe invoke method for calling backend functions\n */\nexport async function invoke<K extends keyof InvokeHandlers>(\n  functionName: K,\n  ...args: IsEmptyArgs<InvokeHandlers[K][\"args\"]> extends true\n    ? [args?: InvokeHandlers[K][\"args\"]]\n    : [args: InvokeHandlers[K][\"args\"]]\n): Promise<InvokeHandlers[K][\"result\"]>;\n\n// Fallback overload for when InvokeHandlers is empty or for dynamic usage\nexport async function invoke<T = any>(functionName: string, args?: any): Promise<T>;\n\nexport async function invoke(functionName: string, args: any = {}): Promise<any> {\n  return _invoke({\n    function: functionName,\n    args: JSON.stringify(args),\n  });\n}\n\ntype Listener<T = any> = (payload: T) => void;\n\nconst listeners = new Map<string, Set<Listener>>();\n\n/**\n * Subscribe to events emitted from the backend\n * @param event - Name of the event to listen for\n * @param cb - Callback function to execute when the event is emitted\n * @returns Unsubscribe function to stop listening to the event\n */\nexport function on<T = any>(event: string, cb: Listener<T>) {\n  let set = listeners.get(event);\n  if (!set) {\n    set = new Set();\n    listeners.set(event, set);\n  }\n\n  set.add(cb);\n\n  return () => {\n    set!.delete(cb);\n    if (set!.size === 0) listeners.delete(event);\n  };\n}\n\n/**\n * Subscribe to events emitted from the backend (fires only once)\n * @param event - Name of the event to listen for\n * @param cb - Callback function to execute when the event is emitted\n * @returns Unsubscribe function to stop listening to the event\n */\nexport function once<T = any>(event: string, cb: Listener<T>) {\n  const wrappedCallback: Listener<T> = (payload) => {\n    cb(payload);\n    unsubscribe();\n  };\n\n  const unsubscribe = on(event, wrappedCallback);\n\n  return unsubscribe;\n}\n\nfunction emit<T = any>(event: string, payload: T) {\n  const set = listeners.get(event);\n  if (!set) return;\n  for (const cb of set) cb(payload);\n}\n\nObject.defineProperty(window, \"__emit__\", {\n  value: emit,\n  writable: false,\n  configurable: false,\n});\n\nexport type { InvokeRequest, Listener };\n"
   ],
-  "mappings": ";AAKO,SAAS,CAAc,CAAC,EAAqC,CAClE,GAAI,IAAW,MAAQ,OAAO,IAAW,SACvC,MAAO,GAGT,MAAO,sBAAuB,GAAU,OAAO,EAAO,oBAAsB,SAGvE,SAAS,CAAiB,CAAC,EAA4B,CAC5D,MAAU,MAAM,EAAM,kBAAmB,CACvC,MACE,EAAM,yBAA+B,MAAM,6CAA6C,CAC5F,CAAC,EAGI,SAAS,CAAsB,CAAC,EAAgB,CACrD,GAAI,EAAe,CAAM,EACvB,EAAkB,CAAM,EAE1B,OAAO,EAKF,SAAS,CAA6B,CAAC,EAA8C,CAC1F,IAAM,EAAM,OAAe,GAE3B,GAAI,CAAC,EACH,QAAQ,KAAK,kCAAkC,GAAW,EAG5D,MAAO,OAAO,IAAgB,CAC5B,GAAI,CAAC,EACH,MAAU,MAAM,kCAAkC,GAAW,EAG/D,IAAM,EAAS,MAAM,EAAG,CAAI,EAC5B,OAAO,EAAoB,CAAM,GCjCrC,IAAM,EAAU,EAAkC,YAAY,EAqB9D,eAAsB,CAAM,CAAC,EAAsB,EAAY,CAAC,EAAiB,CAC/E,OAAO,EAAQ,CACb,SAAU,EACV,KAAM,KAAK,UAAU,CAAI,CAC3B,CAAC,EAKH,IAAM,EAAY,IAAI,IAQf,SAAS,CAAW,CAAC,EAAe,EAAiB,CAC1D,IAAI,EAAM,EAAU,IAAI,CAAK,EAC7B,GAAI,CAAC,EACH,EAAM,IAAI,IACV,EAAU,IAAI,EAAO,CAAG,EAK1B,OAFA,EAAI,IAAI,CAAE,EAEH,IAAM,CAEX,GADA,EAAK,OAAO,CAAE,EACV,EAAK,OAAS,EAAG,EAAU,OAAO,CAAK,GAUxC,SAAS,CAAa,CAAC,EAAe,EAAiB,CAM5D,IAAM,EAAc,EAAG,EALc,CAAC,IAAY,CAChD,EAAG,CAAO,EACV,EAAY,EAG+B,EAE7C,OAAO,EAGT,SAAS,CAAa,CAAC,EAAe,EAAY,CAChD,IAAM,EAAM,EAAU,IAAI,CAAK,EAC/B,GAAI,CAAC,EAAK,OACV,QAAW,KAAM,EAAK,EAAG,CAAO,EAGlC,OAAO,eAAe,OAAQ,WAAY,CACxC,MAAO,EACP,SAAU,GACV,aAAc,EAChB,CAAC",
+  "mappings": ";AAKO,SAAS,CAAc,CAAC,EAAqC,CAClE,GAAI,IAAW,MAAQ,OAAO,IAAW,SACvC,MAAO,GAGT,MAAO,sBAAuB,GAAU,OAAO,EAAO,oBAAsB,SAGvE,SAAS,CAAiB,CAAC,EAA4B,CAC5D,MAAU,MAAM,EAAM,kBAAmB,CACvC,MACE,EAAM,yBAA+B,MAAM,6CAA6C,CAC5F,CAAC,EAGI,SAAS,CAAsB,CAAC,EAAgB,CACrD,GAAI,EAAe,CAAM,EACvB,EAAkB,CAAM,EAE1B,OAAO,EAKF,SAAS,CAA6B,CAAC,EAA8C,CAC1F,IAAM,EAAM,OAAe,GAE3B,GAAI,CAAC,EACH,QAAQ,KAAK,kCAAkC,GAAW,EAG5D,MAAO,OAAO,IAAgB,CAC5B,GAAI,CAAC,EACH,MAAU,MAAM,kCAAkC,GAAW,EAG/D,IAAM,EAAS,MAAM,EAAG,CAAI,EAC5B,OAAO,EAAoB,CAAM,GCjCrC,IAAM,EAAU,EAAkC,YAAY,EAwB9D,eAAsB,CAAM,CAAC,EAAsB,EAAY,CAAC,EAAiB,CAC/E,OAAO,EAAQ,CACb,SAAU,EACV,KAAM,KAAK,UAAU,CAAI,CAC3B,CAAC,EAKH,IAAM,EAAY,IAAI,IAQf,SAAS,CAAW,CAAC,EAAe,EAAiB,CAC1D,IAAI,EAAM,EAAU,IAAI,CAAK,EAC7B,GAAI,CAAC,EACH,EAAM,IAAI,IACV,EAAU,IAAI,EAAO,CAAG,EAK1B,OAFA,EAAI,IAAI,CAAE,EAEH,IAAM,CAEX,GADA,EAAK,OAAO,CAAE,EACV,EAAK,OAAS,EAAG,EAAU,OAAO,CAAK,GAUxC,SAAS,CAAa,CAAC,EAAe,EAAiB,CAM5D,IAAM,EAAc,EAAG,EALc,CAAC,IAAY,CAChD,EAAG,CAAO,EACV,EAAY,EAG+B,EAE7C,OAAO,EAGT,SAAS,CAAa,CAAC,EAAe,EAAY,CAChD,IAAM,EAAM,EAAU,IAAI,CAAK,EAC/B,GAAI,CAAC,EAAK,OACV,QAAW,KAAM,EAAK,EAAG,CAAO,EAGlC,OAAO,eAAe,OAAQ,WAAY,CACxC,MAAO,EACP,SAAU,GACV,aAAc,EAChB,CAAC",
   "debugId": "4D4982FD20E292DC64756E2164756E21",
   "names": []
 }

package/dist/plugins/process/index.cjs

@@ -0,0 +1,5 @@
+// @bun @bun-cjs
+(function(exports, require, module, __filename, __dirname) {var{defineProperty:o,getOwnPropertyNames:e,getOwnPropertyDescriptor:g}=Object,c=Object.prototype.hasOwnProperty;var t=new WeakMap,l=(r)=>{var n=t.get(r),i;if(n)return n;if(n=o({},"__esModule",{value:!0}),r&&typeof r==="object"||typeof r==="function")e(r).map((a)=>!c.call(n,a)&&o(n,a,{get:()=>r[a],enumerable:!(i=g(r,a))||i.enumerable}));return t.set(r,n),n};var s=(r,n)=>{for(var i in n)o(r,i,{get:n[i],enumerable:!0,configurable:!0,set:(a)=>n[i]=()=>a})};var h={};s(h,{run:()=>d});module.exports=l(h);function f(r){if(r===null||typeof r!=="object")return!1;return"__archangel_error"in r&&typeof r.__archangel_error==="string"}function T(r){throw Error(r.__archangel_error,{cause:r.__archangel_error_trace??Error("Error trace only available in debug builds.")})}function B(r){if(f(r))T(r);return r}function _(r){let n=window[r];if(!n)console.warn(`Backend binding not available: ${r}`);return async(i)=>{if(!n)throw Error(`Backend binding not available: ${r}`);let a=await n(i);return B(a)}}var E=_("__plugin_process_run__"),d=(r,n)=>E({argv:r,...n?{cwd:n.cwd,env:n.env?Object.entries(n.env).map(([i,a])=>({key:i,value:a})):void 0}:{}});})
+
+//# debugId=76A3F262EB1AF98F64756E2164756E21
+//# sourceMappingURL=index.cjs.map

package/dist/plugins/process/index.cjs.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["..\\src\\internal\\binding.ts", "..\\src\\plugins\\process\\index.ts"],
+  "sourcesContent": [
+    "export interface BindingError {\n  __archangel_error: string;\n  __archangel_error_trace?: string;\n}\n\nexport function isBindingError(result: any): result is BindingError {\n  if (result === null || typeof result !== \"object\") {\n    return false;\n  }\n\n  return \"__archangel_error\" in result && typeof result.__archangel_error === \"string\";\n}\n\nexport function throwBindingError(error: BindingError): never {\n  throw new Error(error.__archangel_error, {\n    cause:\n      error.__archangel_error_trace ?? new Error(\"Error trace only available in debug builds.\"),\n  });\n}\n\nexport function handleBindingResult<T>(result: any): T {\n  if (isBindingError(result)) {\n    throwBindingError(result);\n  }\n  return result as T;\n}\n\ntype BindingFn<TArgs = any, TResult = any> = (args: TArgs) => Promise<TResult>;\n\nexport function createBinding<TArgs, TResult>(windowKey: string): BindingFn<TArgs, TResult> {\n  const fn = (window as any)[windowKey];\n\n  if (!fn) {\n    console.warn(`Backend binding not available: ${windowKey}`);\n  }\n\n  return async (args: TArgs) => {\n    if (!fn) {\n      throw new Error(`Backend binding not available: ${windowKey}`);\n    }\n\n    const result = await fn(args);\n    return handleBindingResult(result);\n  };\n}\n",
+    "import { createBinding } from \"../../internal/binding\";\r\n\r\ntype EnvMapping = {\r\n  key: string;\r\n  value: string;\r\n};\r\n\r\ntype RunRequestBinding = {\r\n  argv: string[];\r\n  cwd?: string;\r\n  env?: EnvMapping[];\r\n};\r\n\r\n\r\nexport type RunRequest = {\r\n  cwd?: string;\r\n  env?: Record<string, string>;\r\n};\r\n\r\nexport type RunResponse = {\r\n  stdout: string;\r\n  stderr: string;\r\n  term: number;\r\n};\r\n\r\nconst runBinding = createBinding<RunRequestBinding, RunResponse>(\"__plugin_process_run__\");\r\n\r\n/**\r\n * Run a command\r\n * @param args - Object containing the command arguments, current working directory, and environment variables\r\n * @returns Promise resolving to the run response\r\n */\r\nexport const run = (argv: string[], req?: RunRequest) => runBinding({\r\n  argv: argv,\r\n  ...req ? {\r\n    cwd: req.cwd,\r\n    env: req.env ? Object.entries(req.env).map(([key, value]) => ({ key, value })) : undefined,\r\n  } : {},\r\n});\r\n"
+  ],
+  "mappings": ";mjBAKO,SAAS,CAAc,CAAC,EAAqC,CAClE,GAAI,IAAW,MAAQ,OAAO,IAAW,SACvC,MAAO,GAGT,MAAO,sBAAuB,GAAU,OAAO,EAAO,oBAAsB,SAGvE,SAAS,CAAiB,CAAC,EAA4B,CAC5D,MAAU,MAAM,EAAM,kBAAmB,CACvC,MACE,EAAM,yBAA+B,MAAM,6CAA6C,CAC5F,CAAC,EAGI,SAAS,CAAsB,CAAC,EAAgB,CACrD,GAAI,EAAe,CAAM,EACvB,EAAkB,CAAM,EAE1B,OAAO,EAKF,SAAS,CAA6B,CAAC,EAA8C,CAC1F,IAAM,EAAM,OAAe,GAE3B,GAAI,CAAC,EACH,QAAQ,KAAK,kCAAkC,GAAW,EAG5D,MAAO,OAAO,IAAgB,CAC5B,GAAI,CAAC,EACH,MAAU,MAAM,kCAAkC,GAAW,EAG/D,IAAM,EAAS,MAAM,EAAG,CAAI,EAC5B,OAAO,EAAoB,CAAM,GCjBrC,IAAM,EAAa,EAA8C,wBAAwB,EAO5E,EAAM,CAAC,EAAgB,IAAqB,EAAW,CAClE,KAAM,KACH,EAAM,CACP,IAAK,EAAI,IACT,IAAK,EAAI,IAAM,OAAO,QAAQ,EAAI,GAAG,EAAE,IAAI,EAAE,EAAK,MAAY,CAAE,MAAK,OAAM,EAAE,EAAI,MACnF,EAAI,CAAC,CACP,CAAC",
+  "debugId": "76A3F262EB1AF98F64756E2164756E21",
+  "names": []
+}

package/dist/plugins/process/index.d.ts

@@ -0,0 +1,19 @@
+export type RunRequest = {
+  cwd?: string;
+  env?: Record<string, string>;
+};
+export type RunResponse = {
+  stdout: string;
+  stderr: string;
+  term: number;
+};
+/**
+ * Run a command
+ * @param argv: Array of command arguments
+ * @param req: Optional request object containing the current working directory and environment variables
+ * @returns Promise resolving to the run response
+ */
+export declare const run: (
+  argv: string[],
+  req?: RunRequest,
+) => Promise<RunResponse>;

package/dist/plugins/process/index.js

@@ -0,0 +1,5 @@
+// @bun
+function t(r){if(r===null||typeof r!=="object")return!1;return"__archangel_error"in r&&typeof r.__archangel_error==="string"}function _(r){throw Error(r.__archangel_error,{cause:r.__archangel_error_trace??Error("Error trace only available in debug builds.")})}function e(r){if(t(r))_(r);return r}function o(r){let n=window[r];if(!n)console.warn(`Backend binding not available: ${r}`);return async(i)=>{if(!n)throw Error(`Backend binding not available: ${r}`);let a=await n(i);return e(a)}}var g=o("__plugin_process_run__"),s=(r,n)=>g({argv:r,...n?{cwd:n.cwd,env:n.env?Object.entries(n.env).map(([i,a])=>({key:i,value:a})):void 0}:{}});export{s as run};
+
+//# debugId=1D349BCE5AF1D93464756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/plugins/process/index.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["..\\src\\internal\\binding.ts", "..\\src\\plugins\\process\\index.ts"],
+  "sourcesContent": [
+    "export interface BindingError {\n  __archangel_error: string;\n  __archangel_error_trace?: string;\n}\n\nexport function isBindingError(result: any): result is BindingError {\n  if (result === null || typeof result !== \"object\") {\n    return false;\n  }\n\n  return \"__archangel_error\" in result && typeof result.__archangel_error === \"string\";\n}\n\nexport function throwBindingError(error: BindingError): never {\n  throw new Error(error.__archangel_error, {\n    cause:\n      error.__archangel_error_trace ?? new Error(\"Error trace only available in debug builds.\"),\n  });\n}\n\nexport function handleBindingResult<T>(result: any): T {\n  if (isBindingError(result)) {\n    throwBindingError(result);\n  }\n  return result as T;\n}\n\ntype BindingFn<TArgs = any, TResult = any> = (args: TArgs) => Promise<TResult>;\n\nexport function createBinding<TArgs, TResult>(windowKey: string): BindingFn<TArgs, TResult> {\n  const fn = (window as any)[windowKey];\n\n  if (!fn) {\n    console.warn(`Backend binding not available: ${windowKey}`);\n  }\n\n  return async (args: TArgs) => {\n    if (!fn) {\n      throw new Error(`Backend binding not available: ${windowKey}`);\n    }\n\n    const result = await fn(args);\n    return handleBindingResult(result);\n  };\n}\n",
+    "import { createBinding } from \"../../internal/binding\";\r\n\r\ntype EnvMapping = {\r\n  key: string;\r\n  value: string;\r\n};\r\n\r\ntype RunRequestBinding = {\r\n  argv: string[];\r\n  cwd?: string;\r\n  env?: EnvMapping[];\r\n};\r\n\r\n\r\nexport type RunRequest = {\r\n  cwd?: string;\r\n  env?: Record<string, string>;\r\n};\r\n\r\nexport type RunResponse = {\r\n  stdout: string;\r\n  stderr: string;\r\n  term: number;\r\n};\r\n\r\nconst runBinding = createBinding<RunRequestBinding, RunResponse>(\"__plugin_process_run__\");\r\n\r\n/**\r\n * Run a command\r\n * @param args - Object containing the command arguments, current working directory, and environment variables\r\n * @returns Promise resolving to the run response\r\n */\r\nexport const run = (argv: string[], req?: RunRequest) => runBinding({\r\n  argv: argv,\r\n  ...req ? {\r\n    cwd: req.cwd,\r\n    env: req.env ? Object.entries(req.env).map(([key, value]) => ({ key, value })) : undefined,\r\n  } : {},\r\n});\r\n"
+  ],
+  "mappings": ";AAKO,SAAS,CAAc,CAAC,EAAqC,CAClE,GAAI,IAAW,MAAQ,OAAO,IAAW,SACvC,MAAO,GAGT,MAAO,sBAAuB,GAAU,OAAO,EAAO,oBAAsB,SAGvE,SAAS,CAAiB,CAAC,EAA4B,CAC5D,MAAU,MAAM,EAAM,kBAAmB,CACvC,MACE,EAAM,yBAA+B,MAAM,6CAA6C,CAC5F,CAAC,EAGI,SAAS,CAAsB,CAAC,EAAgB,CACrD,GAAI,EAAe,CAAM,EACvB,EAAkB,CAAM,EAE1B,OAAO,EAKF,SAAS,CAA6B,CAAC,EAA8C,CAC1F,IAAM,EAAM,OAAe,GAE3B,GAAI,CAAC,EACH,QAAQ,KAAK,kCAAkC,GAAW,EAG5D,MAAO,OAAO,IAAgB,CAC5B,GAAI,CAAC,EACH,MAAU,MAAM,kCAAkC,GAAW,EAG/D,IAAM,EAAS,MAAM,EAAG,CAAI,EAC5B,OAAO,EAAoB,CAAM,GCjBrC,IAAM,EAAa,EAA8C,wBAAwB,EAO5E,EAAM,CAAC,EAAgB,IAAqB,EAAW,CAClE,KAAM,KACH,EAAM,CACP,IAAK,EAAI,IACT,IAAK,EAAI,IAAM,OAAO,QAAQ,EAAI,GAAG,EAAE,IAAI,EAAE,EAAK,MAAY,CAAE,MAAK,OAAM,EAAE,EAAI,MACnF,EAAI,CAAC,CACP,CAAC",
+  "debugId": "1D349BCE5AF1D93464756E2164756E21",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shahwali/archangel",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "files": [
     "dist"
   ],