Tighten FaceID check; improve UTF-8 and docs

Respect explicitly-set Info.plist Face ID values by checking for null/undefined instead of falsiness; update docs to clarify faceIDPermission type/behavior. Fix utf8ByteLength to correctly handle surrogate pairs and unpaired high surrogates (avoid skipping/undercounting). Add unit tests for deepEqual and extend validate tests for UTF-8 edge cases. Document that deepEqual and useStableOptions do not support circular references and that non-serialisable values compare by identity.

Author: mCodex

app.plugin.js

@@ -57,8 +57,8 @@ function withIosNewArchitecture(config) {
 function withFaceIDUsageDescription(config, faceIDPermission) {
 	if (faceIDPermission === null) return config
 	return withInfoPlist(config, (modConfig) => {
-		// Respect a user-set value; only fill the default when missing.
-		if (!modConfig.modResults.NSFaceIDUsageDescription) {
+		// Respect any user-set value (including empty strings); only fill when truly missing.
+		if (modConfig.modResults.NSFaceIDUsageDescription == null) {
 			modConfig.modResults.NSFaceIDUsageDescription =
 				faceIDPermission ?? DEFAULT_FACE_ID_PERMISSION
 		}

docs/EXPO.md

@@ -39,11 +39,10 @@ Add the plugin to your `app.json` / `app.config.ts`:
 
 ### Plugin options
 
-| Prop                    | Type      | Default                                       | Effect                                                                                                    |
-| ----------------------- | --------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `faceIDPermission`      | `string`  | `"Authenticate to access your secure data."` | Written to `NSFaceIDUsageDescription` if missing. A pre-existing value in your Info.plist is preserved. |
-| `faceIDPermission`      | `null`    | —                                             | Skips the Info.plist modifier entirely (use when another plugin owns the key).                            |
-| `enableNewArchitecture` | `boolean` | `true`                                        | Writes `newArchEnabled` (Android) and `RCT_NEW_ARCH_ENABLED` (iOS) flags.                                 |
+| Prop                    | Type             | Default                                      | Effect                                                                                                                                                                                                                              |
+| ----------------------- | ---------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `faceIDPermission`      | `string \| null` | `"Authenticate to access your secure data."` | When a string is provided, it is written to `NSFaceIDUsageDescription` if the key is missing; a pre-existing value in your Info.plist is always preserved. Pass `null` to skip the modifier entirely (e.g. another plugin owns the key). |
+| `enableNewArchitecture` | `boolean`        | `true`                                       | Writes `newArchEnabled` (Android) and `RCT_NEW_ARCH_ENABLED` (iOS) flags.                                                                                                                                                          |
 
 The plugin also adds the following Android permissions automatically:
 

src/__tests__/hooks.deepEqual.test.ts

@@ -0,0 +1,58 @@
+import deepEqual from '../hooks/internal/deepEqual'
+
+describe('hooks/internal/deepEqual', () => {
+	it('returns true for identical primitives (Object.is semantics)', () => {
+		expect(deepEqual(1, 1)).toBe(true)
+		expect(deepEqual('a', 'a')).toBe(true)
+		expect(deepEqual(Number.NaN, Number.NaN)).toBe(true)
+	})
+
+	it('returns false for differing primitives', () => {
+		expect(deepEqual(1, 2)).toBe(false)
+		expect(deepEqual('a', 'b')).toBe(false)
+		expect(deepEqual(0, -0)).toBe(false)
+	})
+
+	it('returns false when comparing null with an object', () => {
+		expect(deepEqual(null, {})).toBe(false)
+		expect(deepEqual({}, null)).toBe(false)
+	})
+
+	it('returns false when comparing primitive with object', () => {
+		expect(deepEqual(1, {})).toBe(false)
+	})
+
+	it('compares plain objects structurally', () => {
+		expect(deepEqual({ a: 1, b: 2 }, { b: 2, a: 1 })).toBe(true)
+		expect(deepEqual({ a: 1 }, { a: 1, b: undefined })).toBe(false)
+		expect(deepEqual({ a: 1, b: 2 }, { a: 1 })).toBe(false)
+	})
+
+	it('compares arrays structurally', () => {
+		expect(deepEqual([1, 2, 3], [1, 2, 3])).toBe(true)
+		expect(deepEqual([1, 2], [1, 2, 3])).toBe(false)
+		expect(deepEqual([1, 2, 3], [1, 2, 4])).toBe(false)
+	})
+
+	it('returns false when only one side is an array', () => {
+		expect(deepEqual([1], { 0: 1, length: 1 })).toBe(false)
+	})
+
+	it('recurses through nested objects and arrays', () => {
+		expect(deepEqual({ a: [1, { b: 2 }] }, { a: [1, { b: 2 }] })).toBe(true)
+		expect(deepEqual({ a: [1, { b: 2 }] }, { a: [1, { b: 3 }] })).toBe(false)
+	})
+
+	it('returns false for non-plain object instances', () => {
+		expect(deepEqual(new Date(0), new Date(0))).toBe(false)
+		expect(deepEqual(/a/, /a/)).toBe(false)
+	})
+
+	it('treats Object.create(null) as a plain object', () => {
+		const a = Object.create(null) as Record<string, unknown>
+		a.x = 1
+		const b = Object.create(null) as Record<string, unknown>
+		b.x = 1
+		expect(deepEqual(a, b)).toBe(true)
+	})
+})

src/__tests__/internal.validate.test.ts

@@ -82,5 +82,30 @@ describe('internal/validate', () => {
 			// '\u{1F600}' (😀) is 4 UTF-8 bytes; allow well-under-the-limit input through.
 			expect(() => validateValue('\u{1F600}')).not.toThrow()
 		})
+
+		it('counts 2-byte UTF-8 sequences (e.g. accented Latin)', () => {
+			// 'é' (U+00E9) is 2 UTF-8 bytes; ensure the 2-byte branch is exercised.
+			const atLimit = `${'x'.repeat(MAX_VALUE_BYTES - 2)}é`
+			const tooBig = `${'x'.repeat(MAX_VALUE_BYTES - 1)}é`
+			expect(() => validateValue(atLimit)).not.toThrow()
+			expect(() => validateValue(tooBig)).toThrow(InvalidArgumentError)
+		})
+
+		it('treats a lone high surrogate as a 3-byte sequence (no skipping)', () => {
+			// Unpaired high surrogate at end of string should count as 3 bytes (replacement),
+			// not 4, and must not advance past end of string.
+			const atLimit = `${'x'.repeat(MAX_VALUE_BYTES - 3)}\uD83D`
+			const tooBig = `${'x'.repeat(MAX_VALUE_BYTES - 2)}\uD83D`
+			expect(() => validateValue(atLimit)).not.toThrow()
+			expect(() => validateValue(tooBig)).toThrow(InvalidArgumentError)
+		})
+
+		it('handles a high surrogate followed by a non-low surrogate without skipping the next character', () => {
+			// '\uD83D' is unpaired (3 bytes) and 'a' is 1 byte — total tail is 4 bytes.
+			const atLimit = `${'x'.repeat(MAX_VALUE_BYTES - 4)}\uD83Da`
+			const tooBig = `${'x'.repeat(MAX_VALUE_BYTES - 3)}\uD83Da`
+			expect(() => validateValue(atLimit)).not.toThrow()
+			expect(() => validateValue(tooBig)).toThrow(InvalidArgumentError)
+		})
 	})
 })

src/hooks/internal/deepEqual.ts

@@ -10,6 +10,8 @@
  * - Returns `false` (rather than recursing) for instances of `Date`, `RegExp`, `Map`, `Set`,
  *   functions, and any other non-plain object: option payloads are POJOs by contract, and these
  *   types should never appear there. Guarding against them prevents accidental false positives.
+ * - **Circular references are not supported** and will recurse until the call stack overflows.
+ *   Option payloads must be acyclic; this is enforced by contract, not at runtime.
  *
  * @internal
  */

src/hooks/useStableOptions.ts

@@ -10,7 +10,11 @@ import deepEqual from './internal/deepEqual'
  * so it correctly handles:
  * - Key order: `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` are treated as equal.
  * - `undefined` values: `{ a: 1, b: undefined }` and `{ a: 1 }` are treated as **different**.
- * - Circular references and non-serialisable values do not throw.
+ * - Non-serialisable values (`Date`, `RegExp`, `Map`, `Set`, functions) compare by identity
+ *   rather than throwing.
+ *
+ * Option payloads must be **acyclic** — circular references are not supported and will
+ * recurse until the call stack overflows. This is by contract; option objects are POJOs.
  *
  * The merged result is cached until either input changes by content, so consumers can pass
  * inline option literals without forcing downstream `useEffect` / `useMemo` invalidations.

src/internal/validate.ts

@@ -22,13 +22,24 @@ function utf8ByteLength(input: string): number {
 	let bytes = 0
 	for (let i = 0; i < input.length; i++) {
 		const code = input.charCodeAt(i)
-		if (code < 0x80) bytes += 1
-		else if (code < 0x800) bytes += 2
-		else if (code >= 0xd800 && code <= 0xdbff) {
-			// High surrogate — combined with the next low surrogate is a 4-byte UTF-8 sequence.
-			bytes += 4
-			i++
-		} else bytes += 3
+		if (code < 0x80) {
+			bytes += 1
+		} else if (code < 0x800) {
+			bytes += 2
+		} else if (code >= 0xd800 && code <= 0xdbff) {
+			// High surrogate. Only count as a 4-byte sequence when properly paired with a
+			// following low surrogate; otherwise treat the unpaired surrogate as a 3-byte
+			// replacement to avoid skipping or undercounting the next code unit.
+			const next = i + 1 < input.length ? input.charCodeAt(i + 1) : 0
+			if (next >= 0xdc00 && next <= 0xdfff) {
+				bytes += 4
+				i++
+			} else {
+				bytes += 3
+			}
+		} else {
+			bytes += 3
+		}
 	}
 	return bytes
 }