@almadar/std 13.6.0 → 13.8.0

package/dist/modules/index.js

@@ -195,9 +195,10 @@ var CORE_OPERATORS = {
     category: "logic",
     minArity: 2,
     maxArity: null,
-    description: "Logical AND",
+    description: "Logical AND (returns the last truthy value, NOT a boolean \u2014 short-circuit)",
     hasSideEffects: false,
     returnType: "boolean",
+    returnSemantics: "last-truthy-of-args",
     params: [{ name: "...conds", type: BOOLEAN, description: "Boolean expressions to AND" }],
     example: '["and", ["=", "@entity.active", true], [">", "@entity.score", 0]]'
   },
@@ -206,9 +207,10 @@ var CORE_OPERATORS = {
     category: "logic",
     minArity: 2,
     maxArity: null,
-    description: "Logical OR",
+    description: "Logical OR (returns the first truthy value, NOT a boolean \u2014 short-circuit)",
     hasSideEffects: false,
     returnType: "boolean",
+    returnSemantics: "first-truthy-of-args",
     params: [{ name: "...conds", type: BOOLEAN, description: "Boolean expressions to OR" }],
     example: '["or", ["=", "@entity.role", "admin"], ["=", "@entity.role", "owner"]]'
   },
@@ -228,9 +230,10 @@ var CORE_OPERATORS = {
     category: "logic",
     minArity: 3,
     maxArity: 3,
-    description: "Conditional expression (ternary)",
+    description: "Conditional expression (ternary). Return type is union of branch types.",
     hasSideEffects: false,
     returnType: "any",
+    returnSemantics: "branch-union",
     params: [
       { name: "cond", type: BOOLEAN, description: "Condition to evaluate" },
       { name: "then", type: ANY, description: "Value or effect if true" },
@@ -1213,9 +1216,10 @@ var ARRAY_OPERATORS = {
     category: "std-array",
     minArity: 1,
     maxArity: 1,
-    description: "Get first element",
+    description: "Get first element (element type of input array, may be undefined when empty)",
     hasSideEffects: false,
     returnType: "any",
+    returnSemantics: "element-of-arg<0>?",
     params: [{ name: "arr", type: "array", description: "The array" }],
     example: '["array/first", [1, 2, 3]] // => 1'
   },
@@ -1224,9 +1228,10 @@ var ARRAY_OPERATORS = {
     category: "std-array",
     minArity: 1,
     maxArity: 1,
-    description: "Get last element",
+    description: "Get last element (element type of input array, may be undefined when empty)",
     hasSideEffects: false,
     returnType: "any",
+    returnSemantics: "element-of-arg<0>?",
     params: [{ name: "arr", type: "array", description: "The array" }],
     example: '["array/last", [1, 2, 3]] // => 3'
   },
@@ -1235,9 +1240,10 @@ var ARRAY_OPERATORS = {
     category: "std-array",
     minArity: 2,
     maxArity: 2,
-    description: "Get element at index",
+    description: "Get element at index (element type of input array, may be undefined out-of-bounds)",
     hasSideEffects: false,
     returnType: "any",
+    returnSemantics: "element-of-arg<0>?",
     params: [
       { name: "arr", type: "array", description: "The array" },
       { name: "index", type: "number", description: "Index (0-based)" }
@@ -1447,9 +1453,10 @@ var ARRAY_OPERATORS = {
     category: "std-array",
     minArity: 2,
     maxArity: 2,
-    description: "Find first element matching predicate",
+    description: "Find first element matching predicate (element type of input array, undefined when no match)",
     hasSideEffects: false,
     returnType: "any",
+    returnSemantics: "element-of-arg<0>?",
     acceptsLambda: true,
     lambdaArgPosition: 1,
     params: [
@@ -1479,9 +1486,10 @@ var ARRAY_OPERATORS = {
     category: "std-array",
     minArity: 2,
     maxArity: 2,
-    description: "Keep elements matching predicate",
+    description: "Keep elements matching predicate (returns same array element type as input)",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "identity-of-arg<0>",
     acceptsLambda: true,
     lambdaArgPosition: 1,
     params: [
@@ -1495,9 +1503,10 @@ var ARRAY_OPERATORS = {
     category: "std-array",
     minArity: 2,
     maxArity: 2,
-    description: "Remove elements matching predicate",
+    description: "Remove elements matching predicate (returns same array element type as input)",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "identity-of-arg<0>",
     acceptsLambda: true,
     lambdaArgPosition: 1,
     params: [
@@ -1511,9 +1520,10 @@ var ARRAY_OPERATORS = {
     category: "std-array",
     minArity: 2,
     maxArity: 2,
-    description: "Transform each element",
+    description: "Transform each element (return type wraps the lambda result in an array)",
     hasSideEffects: false,
     returnType: "array",
+    returnSemantics: "lambda-result",
     acceptsLambda: true,
     lambdaArgPosition: 1,
     params: [
@@ -1527,9 +1537,10 @@ var ARRAY_OPERATORS = {
     category: "std-array",
     minArity: 3,
     maxArity: 3,
-    description: "Reduce array to single value",
+    description: "Reduce array to single value (return type matches the lambda result / init type)",
     hasSideEffects: false,
     returnType: "any",
+    returnSemantics: "lambda-result",
     acceptsLambda: true,
     lambdaArgPosition: 1,
     params: [
@@ -1788,9 +1799,10 @@ var OBJECT_OPERATORS = {
     category: "std-object",
     minArity: 2,
     maxArity: 3,
-    description: "Get nested value by path",
+    description: "Get nested value by path (return type derived from input object shape and key)",
     hasSideEffects: false,
     returnType: "any",
+    returnSemantics: "object-key-lookup",
     params: [
       { name: "obj", type: "object", description: "The object" },
       { name: "path", type: "string", description: 'Dot-separated path (e.g., "user.name")' },
@@ -1854,9 +1866,10 @@ var OBJECT_OPERATORS = {
     category: "std-object",
     minArity: 2,
     maxArity: 2,
-    description: "Select only specified keys",
+    description: "Select only specified keys (return type is subset of input object shape)",
     hasSideEffects: false,
     returnType: "any",
+    returnSemantics: "object-key-lookup",
     params: [
       { name: "obj", type: "object", description: "The object" },
       { name: "keys", type: "array", description: "Keys to keep" }