Support singleton array equality with IS and IS_NOT

Author: roncohen

.changeset/array-contains-membership.md

@@ -5,4 +5,6 @@
 
 Fix `CONTAINS` and `NOT_CONTAINS` for array-valued context. `CONTAINS` now checks for an exact, case-sensitive array element; `NOT_CONTAINS` checks its absence. Both use the first comparison value, while `ANY_OF` and `NOT_ANY_OF` continue to support multiple comparison values. Empty arrays do not contain any value.
 
-Scalar strings retain case-insensitive substring matching. Supported array membership checks no longer produce `UNSUPPORTED_ARRAY_OPERATOR` warnings in Node SDK flag targeting or config evaluation.
+Support `IS` for arrays containing exactly one element equal to the comparison value; `IS_NOT` matches all other present arrays, including empty arrays and arrays with duplicate matching elements. Missing fields still fail closed. Scalar equality is unchanged.
+
+Scalar strings retain case-insensitive substring matching. Supported array equality and membership checks no longer produce `UNSUPPORTED_ARRAY_OPERATOR` warnings in Node SDK flag targeting or config evaluation.

packages/flag-evaluation/src/index.ts

@@ -59,8 +59,8 @@ export type FilterTree<T extends FilterClass> =
  * set membership, and boolean evaluations.
  *
  * Possible values:
- * - "IS": Specifies exact match.
- * - "IS_NOT": Specifies a negation of exact match.
+ * - "IS": Exact scalar match, or an array containing exactly one matching element.
+ * - "IS_NOT": Negates scalar equality or singleton-array equality.
  * - "ANY_OF": Checks if a value is present in a set of specified values.
  * - "NOT_ANY_OF": Checks if a value is not present in a set of specified values.
  * - "CONTAINS": Case-insensitive substring match for strings; exact, case-sensitive element membership for arrays.
@@ -374,6 +374,8 @@ export function hashInt(hashInput: string): number {
 }
 
 const ARRAY_OPERATORS = new Set<ContextFilterOperator>([
+  "IS",
+  "IS_NOT",
   "CONTAINS",
   "NOT_CONTAINS",
   "ANY_OF",
@@ -395,6 +397,20 @@ export function evaluate(
 
   if (Array.isArray(normalizedFieldValue)) {
     switch (operator) {
+      case "IS":
+        return (
+          typeof value === "string" &&
+          normalizedFieldValue.length === 1 &&
+          normalizedFieldValue[0] === value
+        );
+      case "IS_NOT":
+        return (
+          typeof value === "string" &&
+          !(
+            normalizedFieldValue.length === 1 &&
+            normalizedFieldValue[0] === value
+          )
+        );
       case "CONTAINS":
         return (
           typeof value === "string" && normalizedFieldValue.includes(value)
@@ -416,7 +432,7 @@ export function evaluate(
       case "NOT_SET":
         return normalizedFieldValue.length === 0;
       default:
-        // Scalar equality, numeric, date, and boolean operators are scalar-only.
+        // Numeric, date, and boolean operators are scalar-only.
         // Do not accidentally stringify arrays for comparison.
         return false;
     }

packages/flag-evaluation/test/index.test.ts

@@ -613,6 +613,70 @@ describe("evaluate flag targeting integration ", () => {
       },
     );
 
+    describe.each(["IS", "IS_NOT"] as const)(
+      "%s singleton arrays",
+      (operator) => {
+        it.each([
+          { entries: [2], candidate: "2", equal: true },
+          { entries: [true], candidate: "true", equal: true },
+          { entries: [null], candidate: "", equal: true },
+          { entries: [{ level: 3 }], candidate: '{"level":3}', equal: true },
+          { entries: [[false]], candidate: "[false]", equal: true },
+          { entries: [2, 2], candidate: "2", equal: false },
+          { entries: [], candidate: "2", equal: false },
+        ])(
+          "evaluates $entries against $candidate without errors",
+          ({ entries, candidate, equal }) => {
+            const rules: Rule<boolean>[] = [
+              {
+                value: true,
+                filter: {
+                  type: "context",
+                  field: "user.roles",
+                  operator,
+                  values: [candidate],
+                },
+              },
+            ];
+            const context = { user: { roles: entries } };
+            for (const result of [
+              evaluateFlagRules({ flagKey: "singleton", rules, context }),
+              newEvaluator(rules)(context, "singleton"),
+            ]) {
+              expect(result.ruleEvaluationResults).toEqual([
+                operator === "IS" ? equal : !equal,
+              ]);
+              expect(result.errors).toBeUndefined();
+            }
+          },
+        );
+
+        it("fails closed for missing fields, even under negation", () => {
+          const result = evaluateFlagRules({
+            flagKey: "missing",
+            rules: [
+              {
+                value: true,
+                filter: {
+                  type: "negation",
+                  filter: {
+                    type: "context",
+                    field: "user.roles",
+                    operator,
+                    values: ["admin"],
+                  },
+                },
+              },
+            ],
+            context: { user: {} },
+          });
+          expect(result.ruleEvaluationResults).toEqual([false]);
+          expect(result.missingContextFields).toEqual(["user.roles"]);
+          expect(result.errors?.[0].code).toBe("MISSING_CONTEXT_FIELD");
+        });
+      },
+    );
+
     it("keeps JSON-looking strings scalar", () => {
       const evaluator = newEvaluator([
         {
@@ -670,7 +734,7 @@ describe("evaluate flag targeting integration ", () => {
             filter: {
               type: "context",
               field: "user.roles",
-              operator: "IS",
+              operator: "GT",
               values: ["admin"],
             },
           },
@@ -684,9 +748,9 @@ describe("evaluate flag targeting integration ", () => {
         {
           code: "UNSUPPORTED_ARRAY_OPERATOR",
           field: "user.roles",
-          operator: "IS",
+          operator: "GT",
           message:
-            'Operator IS does not support array-valued context field "user.roles".',
+            'Operator GT does not support array-valued context field "user.roles".',
         },
       ]);
     });
@@ -702,7 +766,7 @@ describe("evaluate flag targeting integration ", () => {
               filter: {
                 type: "context",
                 field: "user.roles",
-                operator: "IS",
+                operator: "GT",
                 values: ["admin"],
               },
             },
@@ -728,7 +792,7 @@ describe("evaluate flag targeting integration ", () => {
                 {
                   type: "context",
                   field: "user.teams",
-                  operator: "IS",
+                  operator: "GT",
                   values: ["platform"],
                 },
                 { type: "constant", value: true },
@@ -1124,6 +1188,25 @@ describe("operator evaluation", () => {
   );
 
   it.each([
+    [["a"], "IS", ["a"], true],
+    [["a"], "IS_NOT", ["a"], false],
+    [["a", "b"], "IS", ["a"], false],
+    [["a", "b"], "IS_NOT", ["a"], true],
+    [["a", "a"], "IS", ["a"], false],
+    [["a", "a"], "IS_NOT", ["a"], true],
+    [[], "IS", ["a"], false],
+    [[], "IS_NOT", ["a"], true],
+    [["A"], "IS", ["a"], false],
+    [["A"], "IS_NOT", ["a"], true],
+    [["admin"], "IS", ["adm"], false],
+    [[""], "IS", [""], true],
+    [[""], "IS_NOT", [""], false],
+    [["a"], "IS", ["b", "a"], false],
+    [["a"], "IS_NOT", ["b", "a"], true],
+    [["a"], "IS", [], false],
+    [["a"], "IS_NOT", [], false],
+    [[], "IS", [], false],
+    [[], "IS_NOT", [], false],
     [["a", "b"], "CONTAINS", ["a"], true],
     [["a", "b"], "CONTAINS", ["c"], false],
     [["a", "b"], "NOT_CONTAINS", ["c"], true],
@@ -1162,8 +1245,6 @@ describe("operator evaluation", () => {
   );
 
   it.each([
-    "IS",
-    "IS_NOT",
     "GT",
     "LT",
     "AFTER",

packages/node-sdk/test/client.test.ts

@@ -1756,7 +1756,7 @@ describe("ReflagClient", () => {
       expect(logger.warn).toHaveBeenCalledTimes(1);
     });
 
-    it.each(["CONTAINS", "NOT_CONTAINS"] as const)(
+    it.each(["CONTAINS", "NOT_CONTAINS", "IS", "IS_NOT"] as const)(
       "evaluates array %s for targeting and config without warnings",
       async (operator) => {
         const filter = {
@@ -1788,19 +1788,27 @@ describe("ReflagClient", () => {
         });
         await client.initialize();
 
-        for (const [roles, contains] of [
-          [["admin", "editor"], true],
-          [["superadmin"], false],
-          [["Admin"], false],
-          [[], false],
-          // Scalars retain their case-insensitive substring semantics.
-          ["SUPERADMIN", true],
+        for (const [roles, contains, equals] of [
+          [["admin"], true, true],
+          [["admin", "editor"], true, false],
+          [["admin", "admin"], true, false],
+          [["superadmin"], false, false],
+          [["Admin"], false, false],
+          [[], false, false],
+          // Scalars retain substring matching and exact equality respectively.
+          ["SUPERADMIN", true, false],
+          ["admin", true, true],
         ] as const) {
           const flag = client.getFlag(
             { user: { id: "user123", roles } },
             "array-membership",
           );
-          const expected = operator === "CONTAINS" ? contains : !contains;
+          const positiveMatch =
+            operator === "IS" || operator === "IS_NOT" ? equals : contains;
+          const expected =
+            operator === "CONTAINS" || operator === "IS"
+              ? positiveMatch
+              : !positiveMatch;
           expect(flag.isEnabled).toBe(expected);
           expect(flag.config).toEqual(
             expected
@@ -1826,7 +1834,7 @@ describe("ReflagClient", () => {
                   filter: {
                     type: "context",
                     field: "user.roles",
-                    operator: "IS",
+                    operator: "GT",
                     values: ["admin"],
                   },
                 },
@@ -1855,9 +1863,9 @@ describe("ReflagClient", () => {
             {
               code: "UNSUPPORTED_ARRAY_OPERATOR",
               field: "user.roles",
-              operator: "IS",
+              operator: "GT",
               message:
-                'Operator IS does not support array-valued context field "user.roles".',
+                'Operator GT does not support array-valued context field "user.roles".',
             },
           ],
         },
@@ -1891,7 +1899,7 @@ describe("ReflagClient", () => {
                   filter: {
                     type: "context",
                     field: "user.roles",
-                    operator: "IS",
+                    operator: "GT",
                     values: ["admin"],
                   },
                 },
@@ -1920,9 +1928,9 @@ describe("ReflagClient", () => {
             {
               code: "UNSUPPORTED_ARRAY_OPERATOR",
               field: "user.roles",
-              operator: "IS",
+              operator: "GT",
               message:
-                'Operator IS does not support array-valued context field "user.roles".',
+                'Operator GT does not support array-valued context field "user.roles".',
             },
           ],
         },