osra 0.1.2 → 0.2.0

package/README.md

@@ -1,60 +1,55 @@
 # osra
-what that? https://github.com/GoogleChromeLabs/comlink but nicer to use.
+whats that? A powerful communication library that's really easy to use.
 thats about it
 
-how to?
+how?
 register your functions in the other context like so
 ```ts
-import { makeCallListener, registerListener } from 'osra'
+import { expose } from 'osra'
 
 const resolvers = {
-  'test': makeCallListener(async (myData) => {
+  test: async (myData) => {
     // do work...
     return {
       foo: 1,
       bar: 'bar',
       baz: () => true
     }
-  })
+  }
 }
 
-registerListener({ target: globalThis, resolvers })
+export type Resolvers = typeof resolvers
+
+expose(resolvers, { local: globalThis, remote: globalThis })
 ```
 
-and on your current context you can call it easily like
+and on your current context with full typescript support you can call it easily like
 ```ts
-import { call } from 'osra'
+import type { Resolvers } from './worker.ts'
 
-const worker = new Worker('/worker.js', { type: 'module' })
+import { expose } from 'osra'
 
-call(worker)('test', { theDataThatWillBeSentToTheOtherContext: 1 })
-      .then(({ foo, bar, baz }) => {
-        // foo === 1
-        // bar === 'bar'
-        // baz === callable function that will return a promise with its response
-      })
-```
+const worker = new Worker('/worker.js', { type: 'module' })
 
-all types of data supported by osra that will be correctly proxied/sent to the other context in addition of functions:
+const { test } = await expose<Resolvers>({}, { local: worker, remote: worker })
 
-```ts
-export type TransferableObject =
-  ArrayBuffer | MessagePort | ReadableStream | WritableStream |
-  TransformStream | /* AudioData | */ ImageBitmap /* | VideoFrame | OffscreenCanvas */
+const { foo, bar, baz } = test()
+// foo === 1
+// bar === 'bar'
+// baz === callable function that will return a promise with its response
+```
 
-export interface StructuredCloneObject {
-  [key: string | number | symbol]: StructuredCloneType
-}
+Supports almost any JS types like Promises, Functions, Streams, ect... and plans to support plugins for custom types.
+From efficient transferable messaging transport to JSON only, it always works.
 
-export type StructuredCloneType =
-  boolean | null | undefined | number | BigInt | string | Date | RegExp | Blob | File | FileList | ArrayBuffer | ArrayBufferView |
-  ImageBitmap | ImageData | Array<StructuredCloneType> | StructuredCloneObject | Map<StructuredCloneType, StructuredCloneType> | Set<StructuredCloneType>
+Todo:
 
-export interface StructuredCloneTransferableObject {
-  [key: string | number | symbol]: StructuredCloneTransferableType
-}
+docs about:
 
-export type StructuredCloneTransferableType =
-  StructuredCloneType | TransferableObject | Array<StructuredCloneTransferableType> | StructuredCloneTransferableObject |
-  Map<StructuredCloneTransferableType, StructuredCloneTransferableType> | Set<StructuredCloneTransferableType>
-```
+* Protocol mode:
+* - Bidirectional mode
+* - Unidirectional mode
+* Transport modes:
+* - Capable mode
+* - Jsonable mode
+* Revivables

package/build/index.d.ts

@@ -1,8 +1,155 @@
-import type { RemoteTarget, LocalTarget, OsraMessage, StructuredCloneTransferableProxiableType } from './types';
-export * from './utils';
-export declare const expose: <T extends StructuredCloneTransferableProxiableType>(value: StructuredCloneTransferableProxiableType, { remote: _remote, local: _local, key, origin }: {
-    remote: RemoteTarget | ((osraMessage: OsraMessage, transferables: Transferable[]) => void);
-    local: LocalTarget | ((listener: (event: MessageEvent<OsraMessage>) => void) => void);
-    key?: string;
-    origin?: string;
-}) => Promise<T>;
+declare type BidirectionalConnectionMessage = {
+    type: 'init';
+    remoteUuid: Uuid;
+    data: Capable;
+}
+/** message not needed if transferring MessagePort is supported */
+| {
+    type: 'message';
+    remoteUuid: Uuid;
+    data: Capable;
+    /** uuid of the messagePort that the message was sent through */
+    portId: Uuid;
+}
+/** message not needed if transferring MessagePort is supported */
+| {
+    type: 'message-port-close';
+    remoteUuid: Uuid;
+    /** uuid of the messagePort that closed */
+    portId: string;
+};
+
+declare type Capable = Structurable | TransferBox | Transferable | Revivable | {
+    [key: string]: Capable;
+} | Array<Capable> | Map<Capable, Capable> | Set<Capable>;
+
+declare type ConnectionMessage = BidirectionalConnectionMessage | UnidirectionalConnectionMessage;
+
+declare type CustomTransport = {
+    isJson?: boolean;
+} & ({
+    receive: ReceivePlatformTransport | ((listener: (event: Message, messageContext: MessageContext) => void) => void);
+    emit: EmitPlatformTransport | ((message: Message, transferables?: Transferable[]) => void);
+} | {
+    receive: ReceivePlatformTransport | ((listener: (event: Message, messageContext: MessageContext) => void) => void);
+} | {
+    emit: EmitPlatformTransport | ((message: Message, transferables?: Transferable[]) => void);
+});
+
+declare type EmitJsonPlatformTransport = WebSocket | WebExtPort;
+
+declare type EmitPlatformTransport = EmitJsonPlatformTransport | Window | ServiceWorker | Worker | SharedWorker | MessagePort;
+
+/**
+ * Protocol mode:
+ * - Bidirectional mode
+ * - Unidirectional mode
+ *
+ * Transport modes:
+ * - Capable mode
+ * - Jsonable mode
+ */
+export declare const expose: <T extends Capable>(value: Capable, { transport: _transport, name, remoteName, key, origin, unregisterSignal, platformCapabilities: _platformCapabilities, transferAll, logger }: {
+    transport: Transport;
+    name?: string;
+    remoteName?: string;
+    key?: string;
+    origin?: string;
+    unregisterSignal?: AbortSignal;
+    platformCapabilities?: PlatformCapabilities;
+    transferAll?: boolean;
+    logger?: {};
+}) => Promise<T>;
+
+declare type Jsonable = boolean | null | number | string | {
+    [key: string]: Jsonable;
+} | Array<Jsonable>;
+
+declare type Message = MessageBase & MessageVariant;
+
+declare type MessageBase = {
+    [OSRA_KEY]: string;
+    /** UUID of the client that sent the message */
+    uuid: Uuid;
+    name?: string;
+};
+
+declare type MessageContext = {
+    port?: MessagePort | WebExtPort;
+    sender?: WebExtSender;
+    receiveTransport?: ReceivePlatformTransport;
+    source?: MessageEventSource | null;
+};
+
+declare type MessageVariant = ProtocolMessage | ConnectionMessage;
+
+declare const OSRA_BOX: "__OSRA_BOX__";
+
+declare const OSRA_KEY: "__OSRA_KEY__";
+
+declare type PlatformCapabilities = {
+    jsonOnly: boolean;
+    messagePort: boolean;
+    arrayBuffer: boolean;
+    transferable: boolean;
+    transferableStream: boolean;
+};
+
+declare type PlatformTransport = EmitPlatformTransport | ReceivePlatformTransport;
+
+declare type ProtocolMessage = {
+    type: 'announce';
+    /** Only set when acknowledging a remote announcement */
+    remoteUuid?: Uuid;
+} | {
+    /** uuid already taken, try announcing with another one */
+    type: 'reject-uuid-taken';
+    remoteUuid: Uuid;
+} | {
+    type: 'close';
+    remoteUuid: Uuid;
+};
+
+declare type ReceiveJsonPlatformTransport = WebSocket | WebExtPort | WebExtOnConnect | WebExtOnMessage;
+
+declare type ReceivePlatformTransport = ReceiveJsonPlatformTransport | Window | ServiceWorker | Worker | SharedWorker | MessagePort;
+
+declare type Revivable = MessagePort | Promise<Capable> | TypedArray | ArrayBuffer | ReadableStream | Date | Error | ((...args: Capable[]) => Promise<Capable>);
+
+declare type Structurable = Jsonable
+/** not really structureable but here for convenience */
+| void | undefined | BigInt | Date | RegExp | Blob | File | FileList | ArrayBuffer | ArrayBufferView | ImageBitmap | ImageData | {
+    [key: string]: Structurable;
+} | Array<Structurable> | Map<Structurable, Structurable> | Set<Structurable>;
+
+declare type TransferBox<T extends Transferable = Transferable> = {
+    [OSRA_BOX]: 'transferable';
+    value: T;
+};
+
+declare type Transport = PlatformTransport | CustomTransport;
+
+declare type TypedArray = typeof typedArrays[number];
+
+declare const typedArrays: (BigInt64Array<ArrayBuffer> | BigUint64Array<ArrayBuffer> | Int8Array<ArrayBuffer> | Float64Array<ArrayBuffer> | Uint8Array<ArrayBuffer> | Uint8ClampedArray<ArrayBuffer> | Int16Array<ArrayBuffer> | Uint16Array<ArrayBuffer> | Int32Array<ArrayBuffer> | Uint32Array<ArrayBuffer> | Float16Array<ArrayBuffer> | Float32Array<ArrayBuffer>)[];
+
+declare type UnidirectionalConnectionMessage = {
+    type: 'message';
+    remoteUuid: Uuid;
+    data: Capable;
+    portId: Uuid;
+};
+
+declare type Uuid = `${string}-${string}-${string}-${string}-${string}`;
+
+declare type WebExtOnConnect = WebExtRuntime['onConnect'];
+
+declare type WebExtOnMessage = WebExtRuntime['onMessage'];
+
+declare type WebExtPort = ReturnType<WebExtRuntime['connect']>;
+
+declare type WebExtRuntime = typeof browser.runtime;
+
+declare type WebExtSender = NonNullable<WebExtPort['sender']>;
+
+export { }