@on-the-ground/proxxy-js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 on-the-ground
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @on-the-ground/proxxy-js
+
+Async proxies that shard an object across N independently-constructed instances and dispatch
+method calls onto per-shard [`@on-the-ground/daemonizer`](https://github.com/on-the-ground/daemonizer)
+`Daemon` queues — a JS/TS counterpart to [proxxy](https://github.com/on-the-ground/proxxy) (JVM).
+
+## 📁 Directory Structure
+
+```
+src/
+├── index.ts   # Entry point
+└── proxxy.ts  # startProxy
+```
+
+## ✅ Features
+
+- Wraps a `constructor` — not a live instance — and builds one independent instance per shard (via `new constructor()`), so shards never share mutable state
+- A caller-supplied `keyExtractor` routes each call to a shard; calls routed to the same shard are strictly ordered, calls on different shards run concurrently
+- Every call returns `Promise<Awaited<R>>`, propagating the method's result or thrown error straight back to the caller — proxxy never swallows or redirects errors, that's the caller's call
+- Cancellation via `AbortSignal`; `close()` returns a `Promise<void>` that resolves once every shard has fully drained
+- Only methods are proxied — plain property access (get and set) throws, since a single field has no coherent value once state is sharded
+- Proxied methods must use regular method syntax (`method() {}`), not arrow-function class fields (`method = () => {}`) — see [Method syntax](#method-syntax) below
+
+## Usage
+
+```ts
+import { startProxy } from "@on-the-ground/proxxy-js";
+
+class Account {
+  private balance = 0;
+  // first arg is only used for routing below, the method itself doesn't need it
+  async deposit(_accountId: string, amount: number) {
+    return (this.balance += amount);
+  }
+}
+
+const controller = new AbortController();
+const { proxy, close } = startProxy(Account, controller.signal, {
+  partitionCount: 4,
+  // calls for the same accountId must land on the same shard to observe each other
+  keyExtractor: (_method, args) => hashOf(args[0] as string),
+});
+
+await proxy.deposit("acct-1", 100); // 100
+await proxy.deposit("acct-1", 50);  // 150 — same shard, ordered after the first call
+await proxy.deposit("acct-2", 10);  // runs concurrently with acct-1's calls, different shard
+
+await close();
+```
+
+Wrapping a single object with no sharding at all is just the default: omit `partitionCount`
+(defaults to `1`) and `keyExtractor` (defaults to always routing to shard 0).
+
+## Method syntax
+
+Define proxied methods with regular method syntax:
+
+```ts
+class Account {
+  async deposit(id: string, amount: number) { /* ... */ } // ✅ visible to startProxy
+}
+```
+
+Not as arrow-function class fields:
+
+```ts
+class Account {
+  deposit = async (id: string, amount: number) => { /* ... */ }; // ❌ not recognized
+}
+```
+
+`startProxy` tells methods apart from plain properties by checking `constructor.prototype`,
+without constructing a throwaway instance just to inspect its shape. Regular methods live on
+the prototype; arrow-function class fields are assigned per-instance in the constructor, so
+they're invisible until an instance already exists. This costs nothing in practice — proxxy
+always invokes methods via `fn.apply(instance, args)`, so the usual reason to reach for an
+arrow field (auto-bound `this`) doesn't apply here.
+
+## 🔧 Build
+
+```bash
+yarn build
+```
+
+## 🧪 Testing
+
+```bash
+yarn test       # vitest
+yarn typecheck  # tsc --noEmit, covers src/ and test/
+```

package/dist/index.cjs

@@ -0,0 +1,72 @@
+'use strict';
+
+var daemonizer = require('@on-the-ground/daemonizer');
+
+/**
+ * Wraps `partitionCount` independent instances (one per shard, built via `constructor`) behind a
+ * single proxy. Method calls are routed to a shard by `keyExtractor`; calls on the same shard
+ * are strictly ordered, calls on different shards run concurrently. Every call returns a
+ * Promise that resolves with the method's result or rejects with whatever it threw.
+ *
+ * `constructor`'s methods must be defined with regular method syntax (`method() {}`), not as
+ * arrow-function class fields (`method = () => {}`) — only the former is visible on
+ * `constructor.prototype`, which is how proxied methods are told apart from plain properties
+ * without needing a throwaway instance. This isn't a functional loss here: every call is
+ * dispatched via `fn.apply(instance, args)` regardless of method style, so arrow fields'
+ * usual benefit (auto-bound `this`) is moot inside proxxy.
+ */
+function startProxy(constructor, signal, options = {}) {
+    const partitionCount = options.partitionCount ?? 1;
+    const keyExtractor = options.keyExtractor ?? (() => 0);
+    const router = new daemonizer.PartitionedDaemon(() => {
+        // Built once per partition, not per call — calls routed to this shard must observe
+        // each other's effects on the same instance, not start over from scratch every time.
+        const instance = new constructor();
+        return new daemonizer.Daemon(signal, async (_ctx, call) => {
+            const fn = instance[call.method];
+            if (typeof fn !== "function") {
+                call.reject(new TypeError(`'${String(call.method)}' is not a method`));
+                return;
+            }
+            try {
+                call.resolve(await fn.apply(instance, call.args));
+            }
+            catch (e) {
+                call.reject(e);
+            }
+        }, options.bufferSizePerPartition);
+    }, partitionCount, (call) => keyExtractor(call.method, call.args));
+    const dispatch = (method, args) => new Promise((resolve, reject) => {
+        router.pushEvent({ method, args, resolve, reject }).then((accepted) => {
+            if (!accepted)
+                reject(new Error(`proxxy: cannot dispatch '${String(method)}', proxy is closed`));
+        }, reject);
+    });
+    const proxy = new Proxy({}, {
+        get(_target, method) {
+            // State lives per-shard now, so there's no single coherent value to hand back for a
+            // plain field read — only methods (routed and queued per shard) are supported. The
+            // shape comes straight from the class prototype, so no throwaway instance is needed
+            // just to answer "is this a method". This only sees conventional prototype methods —
+            // arrow-function class fields live on the instance, not the prototype, and won't be
+            // recognized here.
+            const shape = constructor.prototype[method];
+            if (typeof shape !== "function") {
+                throw new TypeError(`proxxy: '${String(method)}' is not a method — direct property access isn't supported on a sharded proxy`);
+            }
+            return (...args) => dispatch(method, args);
+        },
+        set(_target, prop) {
+            // Without a `set` trap, an unhandled writing would silently succeed against the
+            // internal dummy target instead of touching any real shard — worse than a no-op,
+            // since it looks like it worked. Fail loudly instead, same as get().
+            throw new TypeError(`proxxy: '${String(prop)}' cannot be set — direct property access isn't supported on a sharded proxy`);
+        },
+    });
+    return {
+        proxy,
+        close: () => router.close(),
+    };
+}
+
+exports.startProxy = startProxy;

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+type KeyExtractor = (method: string | symbol, args: unknown[]) => number;
+type Proxied<T> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<Awaited<R>> : never;
+};
+type ProxyHandle<T> = {
+    proxy: T;
+    close: () => Promise<void>;
+};
+type ProxyOptions = {
+    /** Number of independent shards, each backed by its own instance of `constructor`. Defaults to 1 (no sharding). */
+    partitionCount?: number;
+    /**
+     * Routes a call to a shard by hashing a key derived from it (e.g. an entity id in `args`).
+     * Calls that must observe each other's effects (same underlying entity) need to map to the
+     * same shard — otherwise they land on independently constructed, mutually invisible instances.
+     * Defaults to always routing to shard 0, which is only correct when `partitionCount` is 1.
+     */
+    keyExtractor?: KeyExtractor;
+    /** Queue capacity per shard. Defaults to the underlying daemon's default (10). */
+    bufferSizePerPartition?: number;
+};
+/**
+ * Wraps `partitionCount` independent instances (one per shard, built via `constructor`) behind a
+ * single proxy. Method calls are routed to a shard by `keyExtractor`; calls on the same shard
+ * are strictly ordered, calls on different shards run concurrently. Every call returns a
+ * Promise that resolves with the method's result or rejects with whatever it threw.
+ *
+ * `constructor`'s methods must be defined with regular method syntax (`method() {}`), not as
+ * arrow-function class fields (`method = () => {}`) — only the former is visible on
+ * `constructor.prototype`, which is how proxied methods are told apart from plain properties
+ * without needing a throwaway instance. This isn't a functional loss here: every call is
+ * dispatched via `fn.apply(instance, args)` regardless of method style, so arrow fields'
+ * usual benefit (auto-bound `this`) is moot inside proxxy.
+ */
+declare function startProxy<T extends object>(constructor: new () => T, signal: AbortSignal, options?: ProxyOptions): ProxyHandle<Proxied<T>>;
+
+export { startProxy };
+export type { KeyExtractor, Proxied, ProxyHandle, ProxyOptions };

package/dist/index.mjs

@@ -0,0 +1,70 @@
+import { PartitionedDaemon, Daemon } from '@on-the-ground/daemonizer';
+
+/**
+ * Wraps `partitionCount` independent instances (one per shard, built via `constructor`) behind a
+ * single proxy. Method calls are routed to a shard by `keyExtractor`; calls on the same shard
+ * are strictly ordered, calls on different shards run concurrently. Every call returns a
+ * Promise that resolves with the method's result or rejects with whatever it threw.
+ *
+ * `constructor`'s methods must be defined with regular method syntax (`method() {}`), not as
+ * arrow-function class fields (`method = () => {}`) — only the former is visible on
+ * `constructor.prototype`, which is how proxied methods are told apart from plain properties
+ * without needing a throwaway instance. This isn't a functional loss here: every call is
+ * dispatched via `fn.apply(instance, args)` regardless of method style, so arrow fields'
+ * usual benefit (auto-bound `this`) is moot inside proxxy.
+ */
+function startProxy(constructor, signal, options = {}) {
+    const partitionCount = options.partitionCount ?? 1;
+    const keyExtractor = options.keyExtractor ?? (() => 0);
+    const router = new PartitionedDaemon(() => {
+        // Built once per partition, not per call — calls routed to this shard must observe
+        // each other's effects on the same instance, not start over from scratch every time.
+        const instance = new constructor();
+        return new Daemon(signal, async (_ctx, call) => {
+            const fn = instance[call.method];
+            if (typeof fn !== "function") {
+                call.reject(new TypeError(`'${String(call.method)}' is not a method`));
+                return;
+            }
+            try {
+                call.resolve(await fn.apply(instance, call.args));
+            }
+            catch (e) {
+                call.reject(e);
+            }
+        }, options.bufferSizePerPartition);
+    }, partitionCount, (call) => keyExtractor(call.method, call.args));
+    const dispatch = (method, args) => new Promise((resolve, reject) => {
+        router.pushEvent({ method, args, resolve, reject }).then((accepted) => {
+            if (!accepted)
+                reject(new Error(`proxxy: cannot dispatch '${String(method)}', proxy is closed`));
+        }, reject);
+    });
+    const proxy = new Proxy({}, {
+        get(_target, method) {
+            // State lives per-shard now, so there's no single coherent value to hand back for a
+            // plain field read — only methods (routed and queued per shard) are supported. The
+            // shape comes straight from the class prototype, so no throwaway instance is needed
+            // just to answer "is this a method". This only sees conventional prototype methods —
+            // arrow-function class fields live on the instance, not the prototype, and won't be
+            // recognized here.
+            const shape = constructor.prototype[method];
+            if (typeof shape !== "function") {
+                throw new TypeError(`proxxy: '${String(method)}' is not a method — direct property access isn't supported on a sharded proxy`);
+            }
+            return (...args) => dispatch(method, args);
+        },
+        set(_target, prop) {
+            // Without a `set` trap, an unhandled writing would silently succeed against the
+            // internal dummy target instead of touching any real shard — worse than a no-op,
+            // since it looks like it worked. Fail loudly instead, same as get().
+            throw new TypeError(`proxxy: '${String(prop)}' cannot be set — direct property access isn't supported on a sharded proxy`);
+        },
+    });
+    return {
+        proxy,
+        close: () => router.close(),
+    };
+}
+
+export { startProxy };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@on-the-ground/proxxy-js",
+  "version": "0.1.0",
+  "description": "Async proxies that route method calls through partitioned daemon queues, with per-key ordering and cross-key concurrency.",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "./dist/index.d.ts",
+    "./dist/index.cjs",
+    "./dist/index.mjs",
+    "./LICENSE"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "yarn clean && rollup -c",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json",
+    "prepublishOnly": "yarn typecheck && yarn test && yarn build"
+  },
+  "keywords": [
+    "proxy",
+    "daemon",
+    "async",
+    "partitioned",
+    "actor",
+    "queue"
+  ],
+  "dependencies": {
+    "@on-the-ground/daemonizer": "^0.2.1"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.1.4",
+    "rollup": "^4.46.0",
+    "rollup-plugin-dts": "^6.2.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/on-the-ground/proxxy-js"
+  }
+}