@nolag/signal 1.1.0 → 1.2.0

package/dist/types.d.ts

@@ -72,3 +72,39 @@ export interface SignalPresenceData {
     peerId: string;
     metadata?: Record<string, unknown>;
 }
+/** Publish-side filter options for a signaling message. */
+export interface SignalOptions {
+    /**
+     * Route this signal to peers filtering on this value — normally the
+     * recipient's peerId, which turns the room broadcast into a direct send.
+     *
+     * Peers subscribed without filters still receive it, so this is safe to
+     * adopt one peer at a time.
+     */
+    filter?: string;
+    /**
+     * AND composite filter — reaches only peers filtering on all of these
+     * values together. Ignored when `filter` is also set.
+     */
+    filters?: string[];
+}
+/** Options for `NoLagSignal.joinRoom()`. */
+export interface JoinRoomOptions {
+    /**
+     * Only receive signals published with one of these filter values. Join with
+     * your own peerId to receive only signals addressed to you.
+     *
+     * Note this is exclusive: a filtered peer no longer receives the room-wide
+     * broadcasts that unfiltered peers send. Adopt it on every peer at once, or
+     * not at all.
+     */
+    filters?: FilterValue[];
+}
+/**
+ * A single subscription filter value.
+ *
+ * A plain string is an OR term: `['alice', 'bob']` matches either. A nested
+ * array is an AND group: `[['alice', 'admin']]` matches only what was
+ * published tagged with both.
+ */
+export type FilterValue = string | string[];

package/dist/utils.d.ts

@@ -1,5 +1,54 @@
+import type { FilterValue } from './types';
 export declare function generateId(): string;
 export declare function createLogger(prefix: string, enabled: boolean): (..._args: unknown[]) => void;
+/**
+ * Build the filter fragment of an emit options object.
+ *
+ * `filter` wins over `filters`: a publish is routed to exactly one topic, so
+ * honouring both would silently drop one of them.
+ */
+export declare function filterEmitOptions(opts?: {
+    filter?: string;
+    filters?: string[];
+}): {
+    filter?: string;
+    filters?: string[];
+};
+/**
+ * Rebuild publish options from the filter a message arrived with, so a reply
+ * to it reaches the same audience the original did.
+ *
+ * The server joins AND groups into one composite value with '|', which is not
+ * a legal character in a plain filter, so split those back apart.
+ */
+export declare function inheritFilter(filter?: string): {
+    filter?: string;
+    filters?: string[];
+};
+/**
+ * Merge OR terms into an existing filter set. AND groups (nested arrays) are
+ * preserved as-is — only plain string terms are deduplicated.
+ */
+export declare function mergeFilters(existing: FilterValue[], add: string[]): FilterValue[];
+/**
+ * Drop OR terms from a filter set. AND groups are left untouched — remove
+ * those by calling `setFilters` with the set you want.
+ */
+export declare function withoutFilters(existing: FilterValue[], remove: string[]): FilterValue[];
+/**
+ * The composite key the server derives from an AND filter group: values are
+ * lowercased, sorted, and joined with '|'. Mirrored here so an item created
+ * locally carries the same filter string as one arriving off the wire.
+ */
+export declare function compositeFilterKey(values: string[]): string;
+/**
+ * The single string form of whatever filter a publish used, for recording on
+ * the local copy of an item. Round-trips through `inheritFilter`.
+ */
+export declare function recordedFilter(opts?: {
+    filter?: string;
+    filters?: string[];
+}): string | undefined;
 /** Register a wrapper against a client + appName; warns on collision. */
 export declare function registerWrapper(client: object, appName: string, wrapperName: string): void;
 /** Release a wrapper's (client, appName) registration on detach. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nolag/signal",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "engines": {
     "node": ">=18.0.0"