Document sort, fix length(null), bump to 0.6.5

docs/quick-reference.md

@@ -86,6 +86,7 @@ This is a quick reference card. For detailed documentation, see [Expression Synt
 | `indexOf(arr, val)` | `indexOf([1, 2, 3], 2)` | 1 |
 | `join(arr, sep)` | `join([1, 2], "-")` | "1-2" |
 | `unique(arr)` | `unique([1, 1, 2])` | [1, 2] |
+| `sort(arr, fn?)` | `sort([3, 1, 2])` | [1, 2, 3] |
 | `map(arr, fn)` | `map([1, 2], x => x * 2)` | [2, 4] |
 | `filter(arr, fn)` | `filter([1, 2, 3], x => x > 1)` | [2, 3] |
 | `find(arr, fn)` | `find([1, 5, 2], x => x > 3)` | 5 |

package.json

@@ -37,6 +37,7 @@
   },
   "resolutions": {
     "ip-address": "^10.1.1",
+    "qs": "^6.15.2",
     "vite": "^6.0.1"
   }
 }

packages/expreszo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pro-fa/expreszo",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "Mathematical expression evaluator",
   "keywords": [
     "expression",

packages/expreszo/src/operators/unary/logical.ts

@@ -7,11 +7,16 @@ export function not(a: any): boolean {
   return !a;
 }
 
-export function length(s: any[] | string | number | undefined): number | undefined {
+export function length(s: any[] | string | number | null | undefined): number | undefined {
   if (s === undefined) {
     return undefined;
   }
 
+  // `null` is an explicit empty value — its length is 0, not `String(null).length` (4).
+  if (s === null) {
+    return 0;
+  }
+
   if (Array.isArray(s)) {
     return s.length;
   }

packages/expreszo/src/registry/builtin/function-docs.ts

@@ -394,6 +394,17 @@ export const BUILTIN_FUNCTION_DOCS: Readonly<Record<string, FunctionDocs>> = {
       { name: 'size', description: 'Positive integer chunk size.', type: 'number' }
     ]
   },
+  sort: {
+    description:
+      'Return a sorted copy of an array (the original is not mutated). With no comparator, ' +
+      'values are sorted in natural ascending order. Optionally pass a comparator f(a, b) ' +
+      'that returns a negative number, zero, or a positive number to order a before, equal ' +
+      'to, or after b.',
+    params: [
+      { name: 'a', description: 'Input array.', type: 'array' },
+      { name: 'f', description: 'Optional comparator (a, b) => number.', optional: true, type: 'function' }
+    ]
+  },
   union: {
     description: 'Concatenate arrays and remove duplicates, preserving first-seen order. Element equality follows Set semantics (strict for primitives, reference for objects).',
     params: [

packages/expreszo/test/functions/functions-string.ts

@@ -15,6 +15,11 @@ describe('String Functions TypeScript Test', function () {
       assert.strictEqual(parser.evaluate('length(undefined)'), undefined);
     });
 
+    it('should return 0 if argument is null', function () {
+      const parser = new Parser();
+      assert.strictEqual(parser.evaluate('length(null)'), 0);
+    });
+
     // Note: length(123) returns 3 (number of digits) because there's also a unary operator
     // that handles numbers, so we don't test the error case for non-string argument
   });

yarn.lock

@@ -3166,7 +3166,7 @@ punycode@^2.1.0:
   resolved "https://registry.yarnpkg.com/punycode/-/punycode-2.3.1.tgz#027422e2faec0b25e1549c3e1bd8309b9133b6e5"
   integrity sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==
 
-qs@^6.14.0, qs@^6.14.1:
+qs@^6.14.0, qs@^6.14.1, qs@^6.15.2:
   version "6.15.2"
   resolved "https://registry.yarnpkg.com/qs/-/qs-6.15.2.tgz#fd55426d710403ddccc45e0f9eab16db7727ece9"
   integrity sha512-Rzq0KEyX/w/tEybncDgdkZrJgVUsUMk3xjh3t5bv3S1HTAtg+uOYt72+ZfwiQwKdysThkTBdL/rTi6HDmX9Ddw==