@justair/justair-library 7.5.0-alpha.ed6e6e7 → 7.5.0

package/dist/constants/deviceTypes.d.ts

@@ -5,4 +5,10 @@ export const DEVICE_TYPES: Readonly<{
 }>;
 export const DEVICE_TYPE_VALUES: readonly ("monitor" | "sample-site" | "linked-device")[];
 export function isAqiCapableDeviceType(deviceType: any): boolean;
+/**
+ * The device-type vocabulary as a type, so consumers get autocomplete and a
+ * compile error on a mis-cased value like "sampleSite" — the exact bug the
+ * runtime comments in utils/subscribedDevices.js warn about at length.
+ */
+export type DeviceType = (typeof DEVICE_TYPES)[keyof typeof DEVICE_TYPES];
 //# sourceMappingURL=deviceTypes.d.ts.map

package/dist/constants/deviceTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deviceTypes.d.ts","sourceRoot":"","sources":["../../src/constants/deviceTypes.js"],"names":[],"mappings":"AA0BA;;;;GAIG;AAEH,0FAA6E;AAStE,iEAEoC"}
+{"version":3,"file":"deviceTypes.d.ts","sourceRoot":"","sources":["../../src/constants/deviceTypes.js"],"names":[],"mappings":"AA0BA;;;;GAIG;AAEH,0FAA6E;AAiBtE,iEAEoC;;;;;;yBAZ9B,CAAA,OAAO,YAAY,EAAC,MAAM,OAAO,YAAY,CAAC"}

package/dist/utils/subscribedDevices.d.ts

@@ -1,11 +1,12 @@
 export const SUBSCRIBED_DEVICES_ERRORS: Readonly<{
     MISSING_SITE_RESOLVER: "missing_site_resolver";
     RESOLVER_RETURNED_NON_ARRAY: "resolver_returned_non_array";
+    RESOLVER_RETURNED_NESTED_ARRAYS: "resolver_returned_nested_arrays";
     RESOLVER_RETURNED_DOCUMENTS: "resolver_returned_documents";
 }>;
 export function projectSubscribedMonitors(subscribedDevices?: Array<{
     deviceId: import("mongoose").Types.ObjectId;
-    deviceType: string;
+    deviceType: import("../constants/deviceTypes.js").DeviceType;
 }>, { resolveSiteMonitorIds }?: {
     resolveSiteMonitorIds?: (siteIds: import("mongoose").Types.ObjectId[]) => Promise<Array<import("mongoose").Types.ObjectId | null | undefined>>;
 }): Promise<import("mongoose").Types.ObjectId[]>;

package/dist/utils/subscribedDevices.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscribedDevices.d.ts","sourceRoot":"","sources":["../../src/utils/subscribedDevices.js"],"names":[],"mappings":"AA4EA;;;;GAIG;AAwII,8DALI,KAAK,CAAC;IAAE,QAAQ,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,8BAC1E;IAAE,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,KAC7E,OAAO,CAAC,KAAK,CAAC,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAA;CAAE,GAC9D,OAAO,CAAC,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CA0BxD"}
+{"version":3,"file":"subscribedDevices.d.ts","sourceRoot":"","sources":["../../src/utils/subscribedDevices.js"],"names":[],"mappings":"AAqFA;;;;;GAKG;AA4II,8DANI,KAAK,CAAC;IAAE,QAAQ,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC;IAC1D,UAAU,EAAE,OAAO,6BAA6B,EAAE,UAAU,CAAA;CAAE,CAAC,8BACzD;IAAE,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,KAC7E,OAAO,CAAC,KAAK,CAAC,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAA;CAAE,GAC9D,OAAO,CAAC,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CA0BxD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justair/justair-library",
-  "version": "7.5.0-alpha.ed6e6e7",
+  "version": "7.5.0",
   "description": "JustAir Internal Library",
   "main": "src/index.js",
   "type": "module",

package/src/constants/deviceTypes.js

@@ -32,6 +32,14 @@ export const DEVICE_TYPES = Object.freeze({
 
 export const DEVICE_TYPE_VALUES = Object.freeze(Object.values(DEVICE_TYPES));
 
+/**
+ * The device-type vocabulary as a type, so consumers get autocomplete and a
+ * compile error on a mis-cased value like "sampleSite" — the exact bug the
+ * runtime comments in utils/subscribedDevices.js warn about at length.
+ *
+ * @typedef {typeof DEVICE_TYPES[keyof typeof DEVICE_TYPES]} DeviceType
+ */
+
 // Whether a device of this type can ever report AQI, and therefore whether a
 // subscription to it can contribute to AQI alert delivery.
 //

package/src/index.js

@@ -276,7 +276,8 @@ export {
   // Every consumer that writes a subscription recomputes the AQI audience with
   // this instead of re-implementing the per-device-type rule.
   // SUBSCRIBED_DEVICES_ERRORS is the stable `err.code` vocabulary for the
-  // throw above; consumers branch on it rather than on message wording.
+  // errors projectSubscribedMonitors throws; consumers branch on it rather
+  // than on message wording.
   projectSubscribedMonitors,
   SUBSCRIBED_DEVICES_ERRORS,
   // Utilities

package/src/utils/subscribedDevices.js

@@ -42,11 +42,20 @@
 //      { deviceId, deviceType: "monitor" } entry per existing id), then
 //      overwrite freely. This is the target state.
 //   2. Until that backfill has run for the user, union the projection with the
-//      existing subscribedMonitors instead of overwriting. THIS IS
-//      SUBSCRIBE-ONLY. A union can only ever add ids, so using it for an
-//      unsubscribe makes the removal a silent no-op. There is deliberately no
-//      third option: an unsubscribe on a user who predates subscribedDevices
-//      MUST run the per-user backfill in option 1 first, and only then
+//      existing subscribedMonitors instead of overwriting — AND write the
+//      per-user backfill in the same update, one
+//      { deviceId, deviceType: "monitor" } entry per id already in
+//      subscribedMonitors, alongside the device being subscribed. Both halves
+//      are required. Unioning without backfilling leaves a user who looks
+//      migrated (subscribedDevices is non-empty) but is not, so the obvious
+//      "has this user been backfilled?" check answers yes and the next
+//      unsubscribe overwrites subscribedMonitors with a projection missing
+//      every monitor they had before. A half-migrated user must never exist.
+//
+//      This path is also SUBSCRIBE-ONLY. A union can only ever add ids, so
+//      using it for an unsubscribe makes the removal a silent no-op. There is
+//      deliberately no third option: an unsubscribe on a user who predates
+//      subscribedDevices MUST be preceded by the backfill, and only then
 //      overwrite. Removing a subscription is not correct any other way.
 //
 // This module deliberately does NOT offer a `union: true` flag. A blanket
@@ -77,6 +86,7 @@ import { DEVICE_TYPES } from "../constants/deviceTypes.js";
 export const SUBSCRIBED_DEVICES_ERRORS = Object.freeze({
   MISSING_SITE_RESOLVER: "missing_site_resolver",
   RESOLVER_RETURNED_NON_ARRAY: "resolver_returned_non_array",
+  RESOLVER_RETURNED_NESTED_ARRAYS: "resolver_returned_nested_arrays",
   RESOLVER_RETURNED_DOCUMENTS: "resolver_returned_documents",
 });
 
@@ -125,38 +135,6 @@ const linkedSiteIds = (entries) =>
     .filter((entry) => entry.deviceType === DEVICE_TYPES.LINKED_DEVICE)
     .map((entry) => entry.deviceId);
 
-// Returns the monitor ids that should be stored in Users.subscribedMonitors for
-// the given subscribedDevices array. Order is deterministic — direct `monitor`
-// subscriptions in array order, then Site-derived ids in resolver order, first
-// occurrence wins — but carries no meaning; treat the result as a set.
-//
-// `subscribedDevices` tolerates undefined/null: a user row written before this
-// field existed has no key at all on a `.lean()` read (pinned in
-// models/tests/users.test.js), and a projection over "no subscriptions" is an
-// empty audience, not a crash.
-//
-// `resolveSiteMonitorIds(siteIds)` is called at most once, with every
-// linked-device id at a time, and must resolve to the flat union of those
-// Sites' monitorIds — the ids themselves, not the Site documents:
-//
-//   const sites = await Sites.find({ _id: { $in: siteIds } }, "monitorIds").lean();
-//   return sites.flatMap((site) => site.monitorIds ?? []);
-//
-// Returning the documents is the easy mistake, so it is rejected rather than
-// merely documented: the return is validated and a document-shaped entry
-// throws RESOLVER_RETURNED_DOCUMENTS, as a non-array return throws
-// RESOLVER_RETURNED_NON_ARRAY. Left unchecked it would fail silently — each
-// Site doc casts to its own _id on write and subscribedMonitors fills with
-// Site ids, exactly the polymorphic id this field split exists to keep out.
-//
-// It is not called at all when nothing is subscribed to a linked-device, so a
-// consumer that only handles monitors pays no query. A resolver may return
-// nullish entries — Sites.monitorIds is `default: undefined`, so a sample-only
-// Site has no array — and they are filtered out here rather than trusted to
-// the caller.
-//
-// Read the PRECONDITION and STALENESS notes at the top of this file before
-// writing the result to Users.subscribedMonitors.
 // The resolver is consumer-supplied, so its return is the one input this
 // module cannot check at the type boundary. Validate it rather than trust it:
 // both bad shapes below would otherwise corrupt subscribedMonitors silently,
@@ -176,26 +154,29 @@ const validateResolvedSiteMonitorIds = (resolved) => {
     throw error;
   }
 
-  // Discriminating a document from an id without importing mongoose: both
-  // expose `_id`, because mongoose defines `_id` on ObjectId.prototype as a
-  // self-reference (`oid._id === oid`). A document's `_id` is a *different*
-  // object, so the self-reference is the test — checking merely for the
-  // presence of `_id` would reject every ordinary ObjectId.
-  // `.map` instead of `.flatMap` yields [[m1, m2]]. It is not caught by the
-  // document check (an array is not a plain object) and fails inconsistently
-  // downstream: one monitor per Site casts back to the id and silently works,
-  // two throws a CastError at write time, far from the cause.
+  // `.map` instead of `.flatMap` yields [[m1, m2]]. An array is not a plain
+  // object, so the document check below never sees it, and it fails
+  // inconsistently downstream: one monitor per Site casts back to the id and
+  // silently works, two throws a CastError at write time, far from the cause.
   if (resolved.some(Array.isArray)) {
     const error = new TypeError(
       "resolveSiteMonitorIds must resolve to a flat array of monitor ids"
     );
-    error.code = SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_NON_ARRAY;
+    error.code = SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_NESTED_ARRAYS;
     throw error;
   }
 
+  // Discriminating a document from an id without importing mongoose: test for
+  // what only an id has. `toHexString` is on ObjectId (mongoose-patched or raw
+  // bson) and on nothing a Sites query returns, hydrated or lean.
+  //
+  // Deliberately not keyed on `_id`, which is wrong in both directions: every
+  // ObjectId appears to carry one (mongoose defines `_id` on ObjectId.prototype
+  // as a self-reference), and a lean read that projects it away
+  // (`Sites.find(..., "monitorIds -_id").lean()`) carries none.
   if (
     resolved.some(
-      (id) => isPlainObject(id) && id._id !== undefined && id._id !== id
+      (id) => isPlainObject(id) && typeof id.toHexString !== "function"
     )
   ) {
     const error = new TypeError(
@@ -208,8 +189,41 @@ const validateResolvedSiteMonitorIds = (resolved) => {
   return resolved;
 };
 
+// Returns the monitor ids that should be stored in Users.subscribedMonitors for
+// the given subscribedDevices array. Order is deterministic — direct `monitor`
+// subscriptions in array order, then Site-derived ids in resolver order, first
+// occurrence wins — but carries no meaning; treat the result as a set.
+//
+// `subscribedDevices` tolerates undefined/null: a user row written before this
+// field existed has no key at all on a `.lean()` read (pinned in
+// models/tests/users.test.js), and a projection over "no subscriptions" is an
+// empty audience, not a crash.
+//
+// `resolveSiteMonitorIds(siteIds)` is called at most once, with every
+// linked-device id at a time, and must resolve to the flat union of those
+// Sites' monitorIds — the ids themselves, not the Site documents:
+//
+//   const sites = await Sites.find({ _id: { $in: siteIds } }, "monitorIds").lean();
+//   return sites.flatMap((site) => site.monitorIds ?? []);
+//
+// Returning the documents is the easy mistake, so it is rejected rather than
+// merely documented: the return is validated and a document-shaped entry
+// throws RESOLVER_RETURNED_DOCUMENTS, as a non-array return throws
+// RESOLVER_RETURNED_NON_ARRAY. Left unchecked it would fail silently — each
+// Site doc casts to its own _id on write and subscribedMonitors fills with
+// Site ids, exactly the polymorphic id this field split exists to keep out.
+//
+// It is not called at all when nothing is subscribed to a linked-device, so a
+// consumer that only handles monitors pays no query. A resolver may return
+// nullish entries — Sites.monitorIds is `default: undefined`, so a sample-only
+// Site has no array — and they are filtered out here rather than trusted to
+// the caller.
+//
+// Read the PRECONDITION and STALENESS notes at the top of this file before
+// writing the result to Users.subscribedMonitors.
 /**
- * @param {Array<{ deviceId: import("mongoose").Types.ObjectId, deviceType: string }>} [subscribedDevices]
+ * @param {Array<{ deviceId: import("mongoose").Types.ObjectId,
+ *   deviceType: import("../constants/deviceTypes.js").DeviceType }>} [subscribedDevices]
  * @param {{ resolveSiteMonitorIds?: (siteIds: import("mongoose").Types.ObjectId[]) =>
  *   Promise<Array<import("mongoose").Types.ObjectId | null | undefined>> }} [options]
  * @returns {Promise<import("mongoose").Types.ObjectId[]>}

package/src/utils/tests/subscribedDevices.test.js

@@ -1,4 +1,9 @@
 import mongoose from 'mongoose';
+import { Users } from '../../models/users.js';
+import {
+  DEVICE_TYPE_VALUES,
+  isAqiCapableDeviceType,
+} from '../../constants/deviceTypes.js';
 import {
   projectSubscribedMonitors,
   SUBSCRIBED_DEVICES_ERRORS,
@@ -140,15 +145,46 @@ describe('projectSubscribedMonitors', () => {
         resolveSiteMonitorIds: async () => [[oid(), oid()]],
       }),
     ).rejects.toMatchObject({
-      code: SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_NON_ARRAY,
+      code: SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_NESTED_ARRAYS,
+    });
+  });
+
+  test('rejects a lean Site read that projected _id away', async () => {
+    // The `_id`-based discriminator missed this: `Sites.find(..., "monitorIds
+    // -_id").lean()` yields objects carrying no _id at all, which would
+    // otherwise key as "[object Object]" in dedupeById and land in
+    // subscribedMonitors as junk.
+    await expect(
+      projectSubscribedMonitors([{ deviceId: oid(), deviceType: 'linked-device' }], {
+        resolveSiteMonitorIds: async () => [{ monitorIds: [oid()] }],
+      }),
+    ).rejects.toMatchObject({
+      code: SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_DOCUMENTS,
+    });
+  });
+
+  test('rejects a hydrated Site document (the forgot-.lean() case)', async () => {
+    // The likeliest real-world shape of this mistake. A throwaway model keeps
+    // this file off the real Sites schema; hydration needs no connection.
+    const HydratedSite = mongoose.model(
+      'SubscribedDevicesProbeSite',
+      new mongoose.Schema({ monitorIds: [mongoose.Schema.Types.ObjectId] }),
+    );
+
+    await expect(
+      projectSubscribedMonitors([{ deviceId: oid(), deviceType: 'linked-device' }], {
+        resolveSiteMonitorIds: async () => [new HydratedSite({ monitorIds: [oid()] })],
+      }),
+    ).rejects.toMatchObject({
+      code: SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_DOCUMENTS,
     });
   });
 
   test('does not mistake ordinary ObjectIds for documents', async () => {
-    // Regression guard for the discriminator: mongoose defines `_id` on
-    // ObjectId.prototype as a self-reference, so a naive "has _id" check
-    // rejects every legitimate resolver result. Only a differing `_id` marks
-    // an actual document.
+    // Regression guard for the discriminator: an id has `toHexString`, a Site
+    // document does not. Keying on `_id` instead gets it wrong both ways —
+    // mongoose defines `_id` on ObjectId.prototype as a self-reference, so a
+    // naive "has _id" check rejects every legitimate resolver result.
     const siteId = oid();
     const monitorId = oid();
 
@@ -331,3 +367,49 @@ describe('projectSubscribedMonitors', () => {
     expect(after).toEqual([shared]);
   });
 });
+
+// Two encodings of "which device types can produce AQI" exist: the predicate
+// isAqiCapableDeviceType, and the selectors inside projectSubscribedMonitors.
+// Nothing structural keeps them in step, so a fourth type added to one and not
+// the other would report as AQI-capable while contributing no audience — the
+// silent failure this module exists to prevent. This pins them together.
+// Every other case here passes plain object literals, but the real call site
+// hands in user.subscribedDevices — a mongoose DocumentArray of subdocuments,
+// which has to survive the isPlainObject filter. If it ever stopped doing so
+// every entry would be dropped and the projection would return an empty
+// audience with no error. Hydration needs no connection, so this stays DB-free.
+describe('accepts real mongoose subdocuments, not just object literals', () => {
+  test('projects a hydrated user.subscribedDevices the same as plain objects', async () => {
+    const monitorId = oid();
+    const siteId = oid();
+    const siteMonitorId = oid();
+
+    const user = new Users({
+      subscribedDevices: [
+        { deviceId: monitorId, deviceType: 'monitor' },
+        { deviceId: siteId, deviceType: 'linked-device' },
+        { deviceId: oid(), deviceType: 'sample-site' },
+      ],
+    });
+
+    await expect(
+      projectSubscribedMonitors(user.subscribedDevices, {
+        resolveSiteMonitorIds: async () => [siteMonitorId],
+      }),
+    ).resolves.toEqual([monitorId, siteMonitorId]);
+  });
+});
+
+describe('isAqiCapableDeviceType agrees with the projection', () => {
+  test.each(DEVICE_TYPE_VALUES)('%s', async (deviceType) => {
+    const deviceId = oid();
+    const projected = await projectSubscribedMonitors(
+      [{ deviceId, deviceType }],
+      // Resolves as though the id were a Site linking exactly one monitor, so
+      // a linked-device yields an audience and a sample-site still yields none.
+      { resolveSiteMonitorIds: async () => [oid()] },
+    );
+
+    expect(projected.length > 0).toBe(isAqiCapableDeviceType(deviceType));
+  });
+});