@nolag/collab 1.1.0 → 1.2.0

package/dist/types.d.ts

@@ -80,6 +80,24 @@ export interface SendOperationOptions {
     content?: string;
     /** Arbitrary operation payload for custom types */
     data?: Record<string, unknown>;
+    /**
+     * Route this operation to collaborators filtering on this value.
+     * Unfiltered (wildcard) collaborators still receive it.
+     */
+    filter?: string;
+    /**
+     * AND composite filter — reaches only collaborators filtering on all of
+     * these values together. Ignored when `filter` is also set.
+     */
+    filters?: string[];
+}
+/** Options for `NoLagCollab.joinDocument()`. */
+export interface JoinDocumentOptions {
+    /**
+     * Only receive operations published with one of these filter values.
+     * Omit (or pass an empty array) to receive every operation.
+     */
+    filters?: FilterValue[];
 }
 export interface CursorPosition {
     /** User ID of the cursor owner */
@@ -178,3 +196,11 @@ export interface CollabDocumentEvents {
         replayed: number;
     }];
 }
+/**
+ * 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/collab",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "engines": {
     "node": ">=18.0.0"