@nolag/iot 1.1.0 → 1.2.0

package/dist/types.d.ts

@@ -62,6 +62,31 @@ export interface TelemetryReading {
 export interface SendTelemetryOptions {
     unit?: string;
     tags?: Record<string, string>;
+    /**
+     * Route this reading to subscribers filtering on this value — a site, a
+     * sensor class, a criticality tier. Unfiltered subscribers still receive it.
+     */
+    filter?: string;
+    /**
+     * AND composite filter — reaches only subscribers filtering on all of these
+     * values together, e.g. `['site-a', 'critical']`. Ignored when `filter` is
+     * also set.
+     */
+    filters?: string[];
+}
+/** Options for `NoLagIoT.joinGroup()`. */
+export interface JoinGroupOptions {
+    /**
+     * Only receive telemetry published with one of these filter values — the
+     * way to subscribe a dashboard to one site's sensors instead of every
+     * device in the group.
+     *
+     * Commands and command acks are not affected: those already route by
+     * deviceId internally, and overriding that would break command delivery.
+     *
+     * Omit (or pass an empty array) to receive all telemetry.
+     */
+    filters?: FilterValue[];
 }
 export interface DeviceCommand {
     /** Client-generated unique command ID */
@@ -131,3 +156,11 @@ export interface DeviceGroupEvents {
     replayStart: [];
     replayEnd: [];
 }
+/**
+ * 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/iot",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "engines": {
     "node": ">=18.0.0"