Replace overloadOperator with options.strictEquality

Add `defineOption()` to @tko/utils — a plugin-friendly API for registering
custom options with side-effect setters on ko.options.

@tko/utils.parser uses defineOption to register `strictEquality`:
- ko.options.strictEquality = true → == becomes ===, != becomes !==
- ko.options.strictEquality = false → default loose equality (default)
- Strongly typed via declaration merging on the Options class
- Zero runtime cost: swaps function references at config time

builds/reference sets `options.strictEquality = true` at setup.
builds/knockout uses the default (loose equality).

Removes `overloadOperator` (was only used for ==/!=).

6 new tests covering loose/strict modes, toggling, and === isolation.

Addresses #290. Alternative to PR #292.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

builds/reference/src/index.ts

@@ -20,13 +20,12 @@ import components from '@tko/utils.component'
 import { createElement, Fragment } from '@tko/utils.jsx'
 import { JsxObserver } from '@tko/utils.jsx'
 
-import { overloadOperator } from '@tko/utils.parser'
+import { options } from '@tko/utils'
 
 declare const BUILD_VERSION: string
 
-/** Overload "evil twins" with strict equivalents */
-overloadOperator('==', (a, b) => a === b)
-overloadOperator('!=', (a, b) => a !== b)
+/** Use === and !== instead of == and != in binding expressions */
+options.strictEquality = true
 
 const builder = new Builder({
   filters,

packages/utils.parser/spec/strictEqualityBehaviors.ts

@@ -0,0 +1,73 @@
+import { expect } from 'chai'
+
+import { options } from '@tko/utils'
+import { Parser } from '../dist'
+
+function ctxStub(ctx?) {
+  return {
+    lookup(v) {
+      return ctx?.[v]
+    },
+    $data: ctx
+  }
+}
+
+function evaluate(expr: string, vars: object = {}) {
+  const bindings = new Parser().parse(`r: ${expr}`, ctxStub(vars))
+  return bindings.r()
+}
+
+describe('options.strictEquality', function () {
+  afterEach(function () {
+    options.strictEquality = false
+  })
+
+  it('defaults to loose equality (==)', function () {
+    expect(options.strictEquality).to.equal(false)
+    // 0 == '' is true with loose equality
+    expect(evaluate('x == y', { x: 0, y: '' })).to.equal(true)
+    // null == undefined is true with loose equality
+    expect(evaluate('x == y', { x: null, y: undefined })).to.equal(true)
+  })
+
+  it('switches to strict equality when enabled', function () {
+    options.strictEquality = true
+    // 0 === '' is false with strict equality
+    expect(evaluate('x == y', { x: 0, y: '' })).to.equal(false)
+    // 0 === 0 is true
+    expect(evaluate('x == y', { x: 0, y: 0 })).to.equal(true)
+    // null === undefined is false
+    expect(evaluate('x == y', { x: null, y: undefined })).to.equal(false)
+  })
+
+  it('defaults to loose inequality (!=)', function () {
+    // 0 != '' is false with loose equality (both are falsy)
+    expect(evaluate('x != y', { x: 0, y: '' })).to.equal(false)
+  })
+
+  it('switches to strict inequality when enabled', function () {
+    options.strictEquality = true
+    // 0 !== '' is true with strict equality
+    expect(evaluate('x != y', { x: 0, y: '' })).to.equal(true)
+  })
+
+  it('can be toggled back to loose', function () {
+    options.strictEquality = true
+    expect(evaluate('x == y', { x: 0, y: '' })).to.equal(false) // strict
+
+    options.strictEquality = false
+    expect(evaluate('x == y', { x: 0, y: '' })).to.equal(true) // loose again
+  })
+
+  it('does not affect === and !== operators', function () {
+    expect(evaluate('x === y', { x: 0, y: 0 })).to.equal(true)
+    expect(evaluate('x === y', { x: 0, y: '' })).to.equal(false)
+    expect(evaluate('x !== y', { x: 0, y: '' })).to.equal(true)
+
+    options.strictEquality = true
+    // === and !== should behave the same regardless of the setting
+    expect(evaluate('x === y', { x: 0, y: 0 })).to.equal(true)
+    expect(evaluate('x === y', { x: 0, y: '' })).to.equal(false)
+    expect(evaluate('x !== y', { x: 0, y: '' })).to.equal(true)
+  })
+})

packages/utils.parser/src/index.ts

@@ -1,5 +1,3 @@
-import operators from './operators'
-
 export { default as Parser } from './Parser'
 export { default as Identifier } from './Identifier'
 export { default as Arguments } from './Arguments'
@@ -8,9 +6,5 @@ export { default as Node } from './Node'
 
 export { default as parseObjectLiteral } from './preparse'
 
-export function overloadOperator(op: string, fn: (a, b) => any, precedence?: number) {
-  operators[op] = fn
-  if (Number.isInteger(precedence)) {
-    operators[op].precedence = precedence
-  }
-}
+// Importing operators registers the strictEquality option on ko.options
+import './operators'

packages/utils.parser/src/operators.ts

@@ -1,4 +1,5 @@
 import { unwrap } from '@tko/observable'
+import { defineOption } from '@tko/utils'
 
 export function LAMBDA() {}
 
@@ -25,6 +26,16 @@ export interface OperatorWithProperties extends OperatorFunction {
 export interface Operators {
   [key: string]: OperatorWithProperties
 }
+function looseEqual(a, b) {
+  return a == b
+}
+looseEqual.precedence = 10
+
+function looseNotEqual(a, b) {
+  return a != b
+}
+looseNotEqual.precedence = 10
+
 const operators: Operators = {
   // unary
   '@': unwrapOrCall,
@@ -82,13 +93,9 @@ const operators: Operators = {
   //    TODO: 'in': function (a, b) { return a in b; },
   //    TODO: 'instanceof': function (a, b) { return a instanceof b; },
   //    TODO: 'typeof': function (a, b) { return typeof b; },
-  // equality
-  '==': function equal(a, b) {
-    return a == b
-  },
-  '!=': function ne(a, b) {
-    return a != b
-  },
+  // equality — default loose comparison; use setStrictEquality(true) for === behavior
+  '==': looseEqual,
+  '!=': looseNotEqual,
   '===': function sequal(a, b) {
     return a === b
   },
@@ -207,4 +214,34 @@ operators['call'].precedence = 1
 // lambda
 operators['=>'].precedence = 1
 
+/**
+ * When true, == and != in binding expressions use === and !==.
+ * Swaps the operator function references — zero cost at evaluation time.
+ */
+function strictEqual(a, b) {
+  return a === b
+}
+strictEqual.precedence = 10
+
+function strictNotEqual(a, b) {
+  return a !== b
+}
+strictNotEqual.precedence = 10
+
+// Extend the Options type so ko.options.strictEquality is strongly typed
+declare module '@tko/utils' {
+  interface Options {
+    strictEquality: boolean
+  }
+}
+
+/** Register strictEquality as a configurable option on ko.options */
+defineOption('strictEquality', {
+  default: false,
+  set(strict: boolean) {
+    operators['=='] = strict ? strictEqual : looseEqual
+    operators['!='] = strict ? strictNotEqual : looseNotEqual
+  }
+})
+
 export { operators as default }

packages/utils/src/index.ts

@@ -12,7 +12,7 @@ export * from './function'
 export * from './string'
 export * from './symbol'
 export * from './css'
-export { default as options } from './options'
+export { default as options, defineOption, Options } from './options'
 
 // DOM;
 export * from './dom/event'

packages/utils/src/options.ts

@@ -135,4 +135,35 @@ export class Options {
 
 const options = new Options()
 
+/**
+ * Define a custom option on ko.options with an optional side-effect setter.
+ * Plugins use this to register their own configuration properties.
+ *
+ * Must be called before applyBindings — setters run side effects at
+ * configuration time, not retroactively on already-parsed bindings.
+ *
+ * @example
+ * defineOption('strictEquality', {
+ *   default: false,
+ *   set(strict) { /* swap operator functions *\/ }
+ * })
+ * // Then: ko.options.strictEquality = true
+ */
+export function defineOption<T>(name: string, config: { default: T; set?: (value: T) => void }) {
+  let _value = config.default
+  Object.defineProperty(options, name, {
+    get() {
+      return _value
+    },
+    set(value: T) {
+      _value = value
+      config.set?.(value)
+    },
+    enumerable: true,
+    configurable: true
+  })
+  // Run the setter with the default value to initialize side effects
+  config.set?.(_value)
+}
+
 export default options