@holo-js/flux 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+import { GeneratedBroadcastManifest, BroadcastJsonObject } from '@holo-js/broadcast';
+
+type FluxConnectionStatus = 'idle' | 'connecting' | 'connected' | 'disconnected';
+type FluxChannelKind = 'public' | 'private' | 'presence';
+type ManifestEventName<TManifest extends GeneratedBroadcastManifest> = TManifest['events'][number]['name'] & string;
+type ManifestChannelPattern<TManifest extends GeneratedBroadcastManifest> = TManifest['channels'][number]['pattern'] & string;
+type ManifestChannelEntryByPattern<TManifest extends GeneratedBroadcastManifest, TPattern extends string> = Extract<TManifest['channels'][number], {
+    pattern: TPattern;
+}>;
+type ManifestPresenceMember<TManifest extends GeneratedBroadcastManifest, TPattern extends string> = Extract<ManifestChannelEntryByPattern<TManifest, TPattern>, {
+    member: unknown;
+}> extends {
+    member: infer TMember;
+} ? TMember : BroadcastJsonObject;
+type ManifestWhisperName<TManifest extends GeneratedBroadcastManifest, TPattern extends string> = ManifestChannelEntryByPattern<TManifest, TPattern>['whispers'][number] & string;
+type ManifestEventNamesForPattern<TManifest extends GeneratedBroadcastManifest, TPattern extends string> = Extract<TManifest['events'][number], {
+    channels: readonly {
+        pattern: TPattern;
+    }[];
+}>['name'] & string;
+interface FluxClientOptions<TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest> {
+    readonly manifest?: TManifest;
+    readonly connection?: string;
+    readonly connector?: FluxConnector;
+    readonly connectorFactory?: (options: FluxClientOptions<TManifest>) => FluxConnector;
+}
+interface FluxListenerControls {
+    leaveChannel(): void;
+    leave(): void;
+    stopListening(): void;
+    listen(): FluxListenerControls;
+}
+interface FluxPresenceState<TMember = unknown> {
+    readonly members: readonly TMember[];
+}
+interface FluxConnectionControls {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getStatus(): FluxConnectionStatus;
+    onStatusChange(callback: (status: FluxConnectionStatus) => void): () => void;
+}
+interface FluxConnectorChannel {
+    readonly name: string;
+    readonly kind: FluxChannelKind;
+    readonly members: readonly BroadcastJsonObject[];
+    onEvent(event: string, callback: (payload: BroadcastJsonObject) => void): () => void;
+    onMembersChange(callback: (members: readonly BroadcastJsonObject[]) => void): () => void;
+    onNotification(callback: (payload: BroadcastJsonObject) => void): () => void;
+    onWhisper(name: string, callback: (payload: BroadcastJsonObject) => void): () => void;
+    sendWhisper(name: string, payload: BroadcastJsonObject): Promise<void>;
+    leave(): void;
+}
+interface FluxConnector {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getStatus(): FluxConnectionStatus;
+    onStatusChange(callback: (status: FluxConnectionStatus) => void): () => void;
+    subscribe(channel: string, kind: FluxChannelKind): FluxConnectorChannel;
+}
+interface FluxSubscription<TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest, TChannel extends string = string> extends FluxListenerControls {
+    readonly name: TChannel;
+    readonly type: FluxChannelKind;
+    listen<TEvent extends ManifestEventNamesForPattern<TManifest, TChannel> | ManifestEventName<TManifest>>(event?: TEvent | readonly TEvent[], callback?: (payload: BroadcastJsonObject) => void): FluxSubscription<TManifest, TChannel>;
+    notification(callback: (payload: BroadcastJsonObject) => void): FluxSubscription<TManifest, TChannel>;
+    listenForWhisper<TWhisper extends ManifestWhisperName<TManifest, TChannel>>(name: TWhisper, callback: (payload: BroadcastJsonObject) => void): FluxSubscription<TManifest, TChannel>;
+    whisper<TWhisper extends ManifestWhisperName<TManifest, TChannel>>(name: TWhisper, payload: BroadcastJsonObject): Promise<void>;
+}
+interface FluxPresenceSubscription<TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest, TChannel extends string = string> extends FluxSubscription<TManifest, TChannel>, FluxPresenceState<ManifestPresenceMember<TManifest, TChannel>> {
+}
+interface FluxClient<TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest> extends FluxConnectionControls {
+    readonly options: Readonly<FluxClientOptions<TManifest>>;
+    readonly status: FluxConnectionStatus;
+    channel<TChannel extends ManifestChannelPattern<TManifest> | (string & {})>(name: TChannel): FluxSubscription<TManifest, TChannel>;
+    private<TChannel extends ManifestChannelPattern<TManifest> | (string & {})>(name: TChannel): FluxSubscription<TManifest, TChannel>;
+    presence<TChannel extends ManifestChannelPattern<TManifest> | (string & {})>(name: TChannel): FluxPresenceSubscription<TManifest, TChannel>;
+}
+type PusherConnectorOptions = {
+    readonly transport?: 'mock';
+};
+type PusherConnectorDebug = {
+    emitEvent(channel: string, event: string, payload: BroadcastJsonObject): void;
+    emitNotification(channel: string, payload: BroadcastJsonObject): void;
+    updatePresenceMembers(channel: string, members: readonly BroadcastJsonObject[]): void;
+    getJoinedChannels(): readonly string[];
+};
+type ConnectorDebugCarrier = {
+    readonly __debug?: PusherConnectorDebug;
+};
+type SubscriptionRegistry = Map<string, Set<() => void>>;
+declare function createUnavailableConnector(): FluxConnector;
+declare function createPusherConnector(options?: PusherConnectorOptions): FluxConnector & ConnectorDebugCarrier;
+declare function createSubscription<TManifest extends GeneratedBroadcastManifest, TChannel extends string>(channelName: TChannel, kind: FluxChannelKind, connector: FluxConnector, registry: SubscriptionRegistry): FluxSubscription<TManifest, TChannel> & {
+    readonly __presenceMembers: () => readonly BroadcastJsonObject[];
+    readonly __onPresenceChange: (callback: (members: readonly BroadcastJsonObject[]) => void) => () => void;
+};
+declare function createPresenceSubscription<TManifest extends GeneratedBroadcastManifest, TChannel extends string>(name: TChannel, connector: FluxConnector, registry: SubscriptionRegistry): FluxPresenceSubscription<TManifest, TChannel>;
+declare function createFluxClient<TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest>(options?: FluxClientOptions<TManifest>): FluxClient<TManifest> & ConnectorDebugCarrier;
+declare function configureFluxClient(options: FluxClientOptions | FluxClient): FluxClient;
+declare function getFluxClient(): FluxClient;
+declare function resetFluxClient(): void;
+declare const flux: FluxClient<GeneratedBroadcastManifest>;
+declare const fluxInternals: {
+    createUnavailableConnector: typeof createUnavailableConnector;
+    createPusherConnector: typeof createPusherConnector;
+    createPresenceSubscription: typeof createPresenceSubscription;
+    createSubscription: typeof createSubscription;
+};
+
+export { type FluxChannelKind, type FluxClient, type FluxClientOptions, type FluxConnectionControls, type FluxConnectionStatus, type FluxConnector, type FluxConnectorChannel, type FluxListenerControls, type FluxPresenceState, type FluxPresenceSubscription, type FluxSubscription, configureFluxClient, createFluxClient, flux as default, flux, fluxInternals, getFluxClient, resetFluxClient };

package/dist/index.mjs

@@ -0,0 +1,383 @@
+// src/index.ts
+function normalizeRequiredString(value, label) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`[@holo-js/flux] ${label} must be a non-empty string.`);
+  }
+  return normalized;
+}
+function toReadonlyArray(value) {
+  return Array.isArray(value) ? [...value] : [value];
+}
+function addCallback(map, event, callback) {
+  const listeners = map.get(event) ?? /* @__PURE__ */ new Set();
+  listeners.add(callback);
+  map.set(event, listeners);
+  return () => {
+    listeners.delete(callback);
+    if (listeners.size === 0) {
+      map.delete(event);
+    }
+  };
+}
+function notifyStatusListeners(listeners, status) {
+  for (const listener of listeners) {
+    listener(status);
+  }
+}
+function createUnavailableConnector() {
+  const statusListeners = /* @__PURE__ */ new Set();
+  let status = "idle";
+  const throwUnavailable = () => {
+    throw new Error("[@holo-js/flux] No realtime connector configured. Pass connector or connectorFactory to createFluxClient(...).");
+  };
+  return Object.freeze({
+    async connect() {
+      throwUnavailable();
+    },
+    async disconnect() {
+      if (status !== "disconnected") {
+        status = "disconnected";
+        notifyStatusListeners(statusListeners, status);
+      }
+    },
+    getStatus() {
+      return status;
+    },
+    onStatusChange(callback) {
+      statusListeners.add(callback);
+      return () => {
+        statusListeners.delete(callback);
+      };
+    },
+    subscribe() {
+      return throwUnavailable();
+    }
+  });
+}
+function createPusherConnector(options = {}) {
+  const channels = /* @__PURE__ */ new Map();
+  const statusListeners = /* @__PURE__ */ new Set();
+  let status = "idle";
+  void options;
+  const ensureChannel = (name, kind) => {
+    const key = `${kind}:${name}`;
+    const existing = channels.get(key);
+    if (existing) {
+      return existing;
+    }
+    const state = {
+      name,
+      kind,
+      eventListeners: /* @__PURE__ */ new Map(),
+      whisperListeners: /* @__PURE__ */ new Map(),
+      notificationListeners: /* @__PURE__ */ new Set(),
+      memberListeners: /* @__PURE__ */ new Set(),
+      members: Object.freeze([])
+    };
+    channels.set(key, state);
+    return state;
+  };
+  const debug = Object.freeze({
+    emitEvent(channel, event, payload) {
+      for (const state of channels.values()) {
+        if (state.name !== channel) {
+          continue;
+        }
+        for (const callback of state.eventListeners.get(event) ?? []) {
+          callback(payload);
+        }
+      }
+    },
+    emitNotification(channel, payload) {
+      for (const state of channels.values()) {
+        if (state.name !== channel) {
+          continue;
+        }
+        for (const callback of state.notificationListeners) {
+          callback(payload);
+        }
+      }
+    },
+    updatePresenceMembers(channel, members) {
+      for (const state of channels.values()) {
+        if (state.name === channel && state.kind === "presence") {
+          state.members = Object.freeze([...members]);
+          for (const callback of state.memberListeners) {
+            callback(state.members);
+          }
+        }
+      }
+    },
+    getJoinedChannels() {
+      return Object.freeze([...channels.values()].map((state) => `${state.kind}:${state.name}`));
+    }
+  });
+  return Object.freeze({
+    __debug: debug,
+    async connect() {
+      if (status === "connected") {
+        return;
+      }
+      status = "connecting";
+      notifyStatusListeners(statusListeners, status);
+      status = "connected";
+      notifyStatusListeners(statusListeners, status);
+    },
+    async disconnect() {
+      status = "disconnected";
+      notifyStatusListeners(statusListeners, status);
+      channels.clear();
+    },
+    getStatus() {
+      return status;
+    },
+    onStatusChange(callback) {
+      statusListeners.add(callback);
+      return () => {
+        statusListeners.delete(callback);
+      };
+    },
+    subscribe(channel, kind) {
+      const state = ensureChannel(channel, kind);
+      return Object.freeze({
+        name: state.name,
+        kind: state.kind,
+        get members() {
+          return state.members;
+        },
+        onEvent(event, callback) {
+          return addCallback(state.eventListeners, event, callback);
+        },
+        onMembersChange(callback) {
+          state.memberListeners.add(callback);
+          return () => {
+            state.memberListeners.delete(callback);
+          };
+        },
+        onNotification(callback) {
+          state.notificationListeners.add(callback);
+          return () => {
+            state.notificationListeners.delete(callback);
+          };
+        },
+        onWhisper(name, callback) {
+          return addCallback(state.whisperListeners, name, callback);
+        },
+        async sendWhisper(name, payload) {
+          for (const callback of state.whisperListeners.get(name) ?? []) {
+            callback(payload);
+          }
+        },
+        leave() {
+          channels.delete(`${state.kind}:${state.name}`);
+        }
+      });
+    }
+  });
+}
+function createSubscription(channelName, kind, connector, registry) {
+  const connectorChannel = connector.subscribe(channelName, kind);
+  let active = true;
+  const detachCallbacks = /* @__PURE__ */ new Set();
+  const connectedEvents = /* @__PURE__ */ new Set();
+  const eventHandlers = /* @__PURE__ */ new Map();
+  const whisperHandlers = /* @__PURE__ */ new Map();
+  const registryKey = `${kind}:${channelName.replace(/^private-/, "").replace(/^presence-/, "")}`;
+  let left = false;
+  const notificationHandlers = /* @__PURE__ */ new Set();
+  const registeredSubscriptions = registry.get(registryKey) ?? /* @__PURE__ */ new Set();
+  registry.set(registryKey, registeredSubscriptions);
+  const runWhenActive = (callback) => {
+    return (payload) => {
+      if (active) {
+        callback(payload);
+      }
+    };
+  };
+  const ensureEvent = (event, callback) => {
+    const normalizedEvent = normalizeRequiredString(event, "Flux event");
+    const listeners = eventHandlers.get(normalizedEvent) ?? /* @__PURE__ */ new Set();
+    listeners.add(callback);
+    eventHandlers.set(normalizedEvent, listeners);
+    if (!connectedEvents.has(normalizedEvent)) {
+      connectedEvents.add(normalizedEvent);
+      const stop = connectorChannel.onEvent(normalizedEvent, runWhenActive((payload) => {
+        for (const listener of eventHandlers.get(normalizedEvent) ?? []) {
+          listener(payload);
+        }
+      }));
+      detachCallbacks.add(stop);
+    }
+  };
+  const ensureNotification = (callback) => {
+    notificationHandlers.add(callback);
+    if (!connectedEvents.has("notification")) {
+      connectedEvents.add("notification");
+      const stop = connectorChannel.onNotification(runWhenActive((payload) => {
+        for (const listener of notificationHandlers) {
+          listener(payload);
+        }
+      }));
+      detachCallbacks.add(stop);
+    }
+  };
+  const ensureWhisper = (event, callback) => {
+    const normalizedEvent = normalizeRequiredString(event, "Flux whisper event");
+    const listeners = whisperHandlers.get(normalizedEvent) ?? /* @__PURE__ */ new Set();
+    listeners.add(callback);
+    whisperHandlers.set(normalizedEvent, listeners);
+    if (!connectedEvents.has(`whisper:${normalizedEvent}`)) {
+      connectedEvents.add(`whisper:${normalizedEvent}`);
+      const stop = connectorChannel.onWhisper(normalizedEvent, runWhenActive((payload) => {
+        for (const listener of whisperHandlers.get(normalizedEvent) ?? []) {
+          listener(payload);
+        }
+      }));
+      detachCallbacks.add(stop);
+    }
+  };
+  const stopListening = () => {
+    active = false;
+  };
+  const resumeListening = () => {
+    active = true;
+  };
+  const leaveChannel = () => {
+    if (left) {
+      return;
+    }
+    left = true;
+    active = false;
+    for (const detach of detachCallbacks) {
+      detach();
+    }
+    detachCallbacks.clear();
+    registeredSubscriptions.delete(leaveChannel);
+    if (registeredSubscriptions.size === 0) {
+      registry.delete(registryKey);
+    }
+    connectorChannel.leave();
+  };
+  const leaveRelated = () => {
+    for (const leave of [...registry.get(registryKey) ?? []]) {
+      leave();
+    }
+  };
+  registeredSubscriptions.add(leaveChannel);
+  const subscription = {
+    name: channelName,
+    type: kind,
+    leaveChannel,
+    leave: leaveRelated,
+    stopListening,
+    listen(event, callback) {
+      if (typeof event === "undefined" || typeof callback === "undefined") {
+        resumeListening();
+        return this;
+      }
+      for (const entry of toReadonlyArray(event)) {
+        ensureEvent(String(entry), callback);
+      }
+      return this;
+    },
+    notification(callback) {
+      ensureNotification(callback);
+      return this;
+    },
+    listenForWhisper(name, callback) {
+      ensureWhisper(name, callback);
+      return this;
+    },
+    async whisper(name, payload) {
+      await connectorChannel.sendWhisper(normalizeRequiredString(name, "Flux whisper event"), payload);
+    },
+    __presenceMembers() {
+      return connectorChannel.members;
+    },
+    __onPresenceChange(callback) {
+      return connectorChannel.onMembersChange(callback);
+    }
+  };
+  return Object.freeze(subscription);
+}
+function createPresenceSubscription(name, connector, registry) {
+  const base = createSubscription(name, "presence", connector, registry);
+  return Object.freeze({
+    ...base,
+    get members() {
+      return base.__presenceMembers();
+    }
+  });
+}
+function createFluxClient(options = {}) {
+  const connector = options.connector ?? options.connectorFactory?.(options) ?? createUnavailableConnector();
+  const subscriptionRegistry = /* @__PURE__ */ new Map();
+  const client = {
+    options: Object.freeze({ ...options }),
+    get status() {
+      return connector.getStatus();
+    },
+    async connect() {
+      await connector.connect();
+    },
+    async disconnect() {
+      await connector.disconnect();
+    },
+    getStatus() {
+      return connector.getStatus();
+    },
+    onStatusChange(callback) {
+      return connector.onStatusChange(callback);
+    },
+    channel(name) {
+      return createSubscription(name, "public", connector, subscriptionRegistry);
+    },
+    private(name) {
+      return createSubscription(name, "private", connector, subscriptionRegistry);
+    },
+    presence(name) {
+      return createPresenceSubscription(name, connector, subscriptionRegistry);
+    },
+    ..."__debug" in connector ? { __debug: connector.__debug } : {}
+  };
+  return Object.freeze(client);
+}
+var defaultFluxClient = createFluxClient();
+function configureFluxClient(options) {
+  defaultFluxClient = "channel" in options ? options : createFluxClient(options);
+  return defaultFluxClient;
+}
+function getFluxClient() {
+  return defaultFluxClient;
+}
+function resetFluxClient() {
+  defaultFluxClient = createFluxClient();
+}
+var flux = new Proxy({}, {
+  get(_target, property) {
+    return Reflect.get(getFluxClient(), property);
+  },
+  has(_target, property) {
+    return Reflect.has(getFluxClient(), property);
+  },
+  getPrototypeOf() {
+    return Reflect.getPrototypeOf(getFluxClient());
+  }
+});
+var fluxInternals = {
+  createUnavailableConnector,
+  createPusherConnector,
+  createPresenceSubscription,
+  createSubscription
+};
+var src_default = flux;
+export {
+  configureFluxClient,
+  createFluxClient,
+  src_default as default,
+  flux,
+  fluxInternals,
+  getFluxClient,
+  resetFluxClient
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@holo-js/flux",
+  "version": "0.1.3",
+  "description": "Holo-JS Framework - framework-agnostic realtime client skeleton for broadcast and presence",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "stub": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest --run"
+  },
+  "dependencies": {
+    "@holo-js/broadcast": "^0.1.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}