swarpc 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,107 @@
+<div align=center>
+<h1>sw&rpc</h1>
+
+RPC for Service Workers -- move that heavy computation off of your UI thread!
+
+</div>
+ 
+* * *
+
+## Installation
+
+```bash
+npm add swarpc arktype
+```
+
+## Usage
+
+### 1. Declare your procedures in a shared file
+
+```typescript
+import type { ProceduresMap } from "swarpc"
+import { type } from "arktype"
+
+export const procedures = {
+  searchIMDb: {
+    // Input for the procedure
+    input: type({ query: "string", "pageSize?": "number" }),
+    // Function to be called whenever you can update progress while the procedure is running -- long computations are a first-class concern here. Examples include using the fetch-progress NPM package.
+    progress: type({ transferred: "number", total: "number" }),
+    // Output of a successful procedure call
+    success: type({
+      id: "string",
+      primary_title: "string",
+      genres: "string[]",
+    }).array(),
+  },
+} as const satisfies ProceduresMap
+```
+
+### 2. Register your procedures in the service worker
+
+In your service worker file:
+
+```javascript
+import fetchProgress from "fetch-progress"
+import { Server } from "swarpc"
+import { procedures } from "./procedures.js"
+
+// 1. Give yourself a server instance
+const swarpc = Server(procedures)
+
+// 2. Implement your procedures
+swarpc.searchIMDb(async ({ query, pageSize = 10 }, onProgress) => {
+  const queryParams = new URLSearchParams({
+    page_size: pageSize.toString(),
+    query,
+  })
+
+  return fetch(`https://rest.imdbapi.dev/v2/search/titles?${queryParams}`)
+    .then(fetchProgress({ onProgress }))
+    .then((response) => response.json())
+    .then(({ titles } => titles)
+})
+
+// ...
+
+// 3. Start the event listener
+swarpc.start(self)
+```
+
+### 3. Call your procedures from the client
+
+Here's a Svelte example!
+
+```svelte
+<script>
+    import { Client } from "swarpc"
+    import { procedures } from "./procedures.js"
+
+    const swarpc = Client(procedures)
+
+    let query = $state("")
+    let results = $state([])
+    let progress = $state(0)
+</script>
+
+<search>
+    <input type="text" bind:value={query} placeholder="Search IMDb" />
+    <button onclick={async () => {
+        results = await swarpc.searchIMDb({ query }, (p) => {
+            progress = p.transferred / p.total
+        })
+    }}>
+        Search
+    </button>
+</search>
+
+{#if progress > 0 && progress < 1}
+    <progress value={progress} max="1" />
+{/if}
+
+<ul>
+    {#each results as { id, primary_title, genres } (id)}
+        <li>{primary_title} - {genres.join(", ")}</li>
+    {/each}
+</ul>
+```

package/dist/swarpc.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @import { ProceduresMap, SwarpcClient, SwarpcServer } from './typings.js'
+ */
+/**
+ * @template {ProceduresMap} Procedures
+ * @param {Procedures} procedures
+ * @returns {SwarpcServer<Procedures>}
+ */
+export function Server<Procedures extends ProceduresMap>(procedures: Procedures): SwarpcServer<Procedures>;
+/**
+ * @template {ProceduresMap} Procedures
+ * @param {Procedures} procedures
+ * @returns {SwarpcClient<Procedures>}
+ */
+export function Client<Procedures extends ProceduresMap>(procedures: Procedures): SwarpcClient<Procedures>;
+import type { ProceduresMap } from './typings.js';
+import type { SwarpcServer } from './typings.js';
+import type { SwarpcClient } from './typings.js';
+//# sourceMappingURL=swarpc.d.ts.map

package/dist/swarpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swarpc.d.ts","sourceRoot":"","sources":["../src/swarpc.js"],"names":[],"mappings":"AAEA;;GAEG;AAEH;;;;GAIG;AACH,uBAJ6B,UAAU,SAA1B,aAAe,cACjB,UAAU,GACR,aAAa,UAAU,CAAC,CAgFpC;AAED;;;;GAIG;AACH,uBAJ6B,UAAU,SAA1B,aAAe,cACjB,UAAU,GACR,aAAa,UAAU,CAAC,CA+BpC;mCA1H6D,cAAc;kCAAd,cAAc;kCAAd,cAAc"}

package/dist/typings.d.ts

@@ -0,0 +1,18 @@
+export type Procedure<I extends Type, P extends Type, S extends Type> = {
+    input: I;
+    progress: P;
+    success: S;
+};
+export type ProcedureImplementation<I extends Type, P extends Type, S extends Type> = (input: I["inferOut"], onProgress: (progress: P["inferOut"]) => void) => Promise<NoInfer<S>["inferOut"] | NoInfer<S>["inferOut"]>;
+export type ProceduresMap = Record<string, Procedure<Type, Type, Type>>;
+export type ClientMethod<P extends Procedure<Type, Type, Type>> = (input: P["input"]["inferOut"], onProgress?: (progress: P["progress"]["inferOut"]) => void) => Promise<P["success"]["inferOut"]>;
+export type SwarpcClient<Procedures extends ProceduresMap> = {
+    procedures: Procedures;
+} & { [F in keyof Procedures]: ClientMethod<Procedures[F]>; };
+export type SwarpcServer<Procedures extends ProceduresMap> = {
+    procedures: Procedures;
+    implementations: { [F in keyof Procedures]: ProcedureImplementation<Procedures[F]["input"], Procedures[F]["progress"], Procedures[F]["success"]>; };
+    start: (self: Window) => void;
+} & { [F in keyof Procedures]: (impl: NoInfer<ProcedureImplementation<Procedures[F]["input"], Procedures[F]["progress"], Procedures[F]["success"]>>) => void; };
+import type { Type } from 'arktype';
+//# sourceMappingURL=typings.d.ts.map

package/dist/typings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typings.d.ts","sourceRoot":"","sources":["../src/typings.js"],"names":[],"mappings":"sBAKoB,CAAC,SAAR,IAAM,EACC,CAAC,SAAR,IAAM,EACC,CAAC,SAAR,IAAM;WAEL,CAAC;cACD,CAAC;aACD,CAAC;;oCAIK,CAAC,SAAR,IAAM,EACC,CAAC,SAAR,IAAM,EACC,CAAC,SAAR,IAAM,IACN,CAAC,KAAK,EAAE,CAAC,CAAC,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,UAAU,CAAC,KAAK,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;4BAIjI,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;yBAIb,CAAC,SAA9B,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAE,IAC7B,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC,KAAK,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,CAAC,CAAC;yBAIhH,UAAU,SAAzB,aAAc,IACf;IAAE,UAAU,EAAE,UAAU,CAAA;CAAE,GAAG,GAAG,CAAC,IAAI,MAAM,UAAU,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAE;yBAIrE,UAAU,SAAzB,aAAc,IACf;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,eAAe,EAAE,GAAE,CAAC,IAAI,MAAM,UAAU,GAAG,uBAAuB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,GAAE,CAAC;IAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAG,GAAG,GAAG,CAAC,IAAI,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAE,CAAC,KAAK,IAAI,GAAE;0BApC/V,SAAS"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarpc",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Full type-safe RPC library for service worker -- move things off of the UI thread with ease!",
   "keywords": [
     "service-workers",
@@ -20,11 +20,20 @@
   "license": "MIT",
   "author": "Gwenn Le Bihan <gwenn.lebihan7@gmail.com>",
   "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
   "main": "src/swarpc.js",
+  "types": "dist/swarpc.d.ts",
   "scripts": {
+    "build": "tsc",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
     "arktype": "^2.1.20"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
   }
 }

package/src/{swarp.js → swarpc.js}

@@ -1,41 +1,16 @@
 import { type } from "arktype"
-/**
- * @import { Type } from 'arktype';
- */
-
-/**
- * @template {Type} I
- * @template {Type} P
- * @template {Type} S
- * @typedef {Object} Procedure
- * @property {I} input
- * @property {P} progress
- * @property {S} success
- */
 
 /**
- * @template {Type} I
- * @template {Type} P
- * @template {Type} S
- * @typedef {(input: I['inferOut'], onProgress: (progress: P['inferOut']) => void) => Promise<NoInfer<S>['inferOut'] | NoInfer<S>['inferOut']>} ProcedureImplementation
- */
-
-/**
- * @typedef {Record<string, Procedure<any, any, any>>} ProceduresMap
- */
-
-/**
- * @template {ProceduresMap} Procedures
- * @typedef {{ procedures: Procedures, implementations: {[F in keyof Procedures]: ProcedureImplementation<Procedures[F]['input'], Procedures[F]['progress'], Procedures[F]['success']> }, start: (self: Window) => void  } & { [F in keyof Procedures]: (impl: NoInfer<ProcedureImplementation<Procedures[F]['input'], Procedures[F]['progress'], Procedures[F]['success'] >>) => void }} SwarpServer
+ * @import { ProceduresMap, SwarpcClient, SwarpcServer } from './typings.js'
  */
 
 /**
  * @template {ProceduresMap} Procedures
  * @param {Procedures} procedures
- * @returns {SwarpServer<Procedures>}
+ * @returns {SwarpcServer<Procedures>}
  */
 export function Server(procedures) {
-  /** @type {SwarpServer<Procedures>}  */
+  /** @type {SwarpcServer<Procedures>}  */
   // @ts-expect-error
   const instance = {
     procedures,
@@ -114,23 +89,13 @@ export function Server(procedures) {
   return instance
 }
 
-/**
- * @template {Procedure<Type, Type, Type>} P
- * @typedef {(input: P['input']['inferOut'], onProgress?: (progress: P['progress']['inferOut']) => void) => Promise<P['success']['inferOut']>} ClientMethod
- */
-
-/**
- * @template {ProceduresMap} Procedures
- * @typedef {{ procedures: Procedures } & { [F in keyof Procedures]: ClientMethod<Procedures[F]> }} SwarpClient
- */
-
 /**
  * @template {ProceduresMap} Procedures
  * @param {Procedures} procedures
- * @returns {SwarpClient<Procedures>}
+ * @returns {SwarpcClient<Procedures>}
  */
 export function Client(procedures) {
-  /** @type {SwarpClient<Procedures>} */
+  /** @type {SwarpcClient<Procedures>} */
   // @ts-expect-error
   const instance = { procedures }
 

package/src/typings.js

@@ -0,0 +1,42 @@
+/**
+ * @import { Type } from 'arktype';
+ */
+
+/**
+ * @template {Type} I
+ * @template {Type} P
+ * @template {Type} S
+ * @typedef {Object} Procedure
+ * @property {I} input
+ * @property {P} progress
+ * @property {S} success
+ */
+
+/**
+ * @template {Type} I
+ * @template {Type} P
+ * @template {Type} S
+ * @typedef {(input: I['inferOut'], onProgress: (progress: P['inferOut']) => void) => Promise<NoInfer<S>['inferOut'] | NoInfer<S>['inferOut']>} ProcedureImplementation
+ */
+
+/**
+ * @typedef {Record<string, Procedure<Type, Type, Type>>} ProceduresMap
+ */
+
+/**
+ * @template {Procedure<Type, Type, Type>} P
+ * @typedef {(input: P['input']['inferOut'], onProgress?: (progress: P['progress']['inferOut']) => void) => Promise<P['success']['inferOut']>} ClientMethod
+ */
+
+/**
+ * @template {ProceduresMap} Procedures
+ * @typedef {{ procedures: Procedures } & { [F in keyof Procedures]: ClientMethod<Procedures[F]> }} SwarpcClient
+ */
+
+/**
+ * @template {ProceduresMap} Procedures
+ * @typedef {{ procedures: Procedures, implementations: {[F in keyof Procedures]: ProcedureImplementation<Procedures[F]['input'], Procedures[F]['progress'], Procedures[F]['success']> }, start: (self: Window) => void  } & { [F in keyof Procedures]: (impl: NoInfer<ProcedureImplementation<Procedures[F]['input'], Procedures[F]['progress'], Procedures[F]['success'] >>) => void }} SwarpcServer
+ */
+
+// Required, otherwise nothing can be imported from this file
+export {}