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

package/dist/constants/deviceTypes.d.ts

@@ -5,10 +5,4 @@ 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;AAiBtE,iEAEoC;;;;;;yBAZ9B,CAAA,OAAO,YAAY,EAAC,MAAM,OAAO,YAAY,CAAC"}
+{"version":3,"file":"deviceTypes.d.ts","sourceRoot":"","sources":["../../src/constants/deviceTypes.js"],"names":[],"mappings":"AA0BA;;;;GAIG;AAEH,0FAA6E;AAStE,iEAEoC"}

package/dist/utils/subscribedDevices.d.ts

@@ -1,12 +1,11 @@
 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: import("../constants/deviceTypes.js").DeviceType;
+    deviceType: string;
 }>, { 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":"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"}
+{"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"}

package/package.json

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

package/src/constants/deviceTypes.js

@@ -32,14 +32,6 @@ 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,8 +276,7 @@ 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
-  // errors projectSubscribedMonitors throws; consumers branch on it rather
-  // than on message wording.
+  // throw above; consumers branch on it rather than on message wording.
   projectSubscribedMonitors,
   SUBSCRIBED_DEVICES_ERRORS,
   // Utilities

package/src/utils/subscribedDevices.js

@@ -42,20 +42,11 @@
 //      { 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 — 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
+//      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
 //      overwrite. Removing a subscription is not correct any other way.
 //
 // This module deliberately does NOT offer a `union: true` flag. A blanket
@@ -86,7 +77,6 @@ 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",
 });
 
@@ -135,6 +125,38 @@ 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,
@@ -154,29 +176,26 @@ const validateResolvedSiteMonitorIds = (resolved) => {
     throw error;
   }
 
-  // `.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.
+  // 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.
   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_NESTED_ARRAYS;
+    error.code = SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_NON_ARRAY;
     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) && typeof id.toHexString !== "function"
+      (id) => isPlainObject(id) && id._id !== undefined && id._id !== id
     )
   ) {
     const error = new TypeError(
@@ -189,41 +208,8 @@ 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: import("../constants/deviceTypes.js").DeviceType }>} [subscribedDevices]
+ * @param {Array<{ deviceId: import("mongoose").Types.ObjectId, deviceType: string }>} [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,9 +1,4 @@
 import mongoose from 'mongoose';
-import { Users } from '../../models/users.js';
-import {
-  DEVICE_TYPE_VALUES,
-  isAqiCapableDeviceType,
-} from '../../constants/deviceTypes.js';
 import {
   projectSubscribedMonitors,
   SUBSCRIBED_DEVICES_ERRORS,
@@ -145,46 +140,15 @@ describe('projectSubscribedMonitors', () => {
         resolveSiteMonitorIds: async () => [[oid(), oid()]],
       }),
     ).rejects.toMatchObject({
-      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,
+      code: SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_NON_ARRAY,
     });
   });
 
   test('does not mistake ordinary ObjectIds for documents', async () => {
-    // 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.
+    // 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.
     const siteId = oid();
     const monitorId = oid();
 
@@ -367,49 +331,3 @@ 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));
-  });
-});