@almadar/std 13.6.0 → 13.8.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as StdModule, S as StdOperatorMeta } from './types-D7dG8fBF.js';
-export { B as BasicReturnType, b as OPERATOR_CATEGORIES, c as OperatorCategory, d as OperatorEffectMeta, O as OperatorMeta, e as OperatorTypeRef, f as STD_MODULES, g as STD_OPERATOR_CATEGORIES, h as StdOperatorCategory, i as getFunctionFromOperator, j as getModuleFromOperator, k as isStdCategory, l as isStdOperator, m as makeStdOperator } from './types-D7dG8fBF.js';
+import { a as StdModule, S as StdOperatorMeta } from './types-CdSN5hnD.js';
+export { B as BasicReturnType, b as OPERATOR_CATEGORIES, c as OperatorCategory, d as OperatorEffectMeta, O as OperatorMeta, e as OperatorTypeRef, f as STD_MODULES, g as STD_OPERATOR_CATEGORIES, h as StdOperatorCategory, i as getFunctionFromOperator, j as getModuleFromOperator, k as isStdCategory, l as isStdOperator, m as makeStdOperator } from './types-CdSN5hnD.js';
 export { STD_OPERATORS as OPERATORS, OPERATOR_NAMES, STD_OPERATORS, STD_OPERATORS_BY_MODULE, getAllStdOperators as getAllOperatorNames, getAllStdOperators, getLambdaOperators, getModuleOperators, getOperatorMetaExtended, getStdEffectOperators, getStdLibStats, getStdOperatorMeta, getStdOperatorsByModule, getStdPureOperators, isEffectOperatorExtended, isKnownStdOperator as isKnownOperator, isKnownOperatorExtended, isKnownStdOperator, isStdEffectOperator, isStdGuardOperator, validateStdOperatorArity as validateOperatorArity, validateOperatorArityExtended, validateStdOperatorArity } from './registry.js';
 export { CORE_OPERATORS, getCoreOperators } from './modules/core.js';
 export { MATH_OPERATORS } from './modules/math.js';

package/dist/index.js

@@ -299,9 +299,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]]'
   },
@@ -310,9 +311,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"]]'
   },
@@ -332,9 +334,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" },
@@ -1311,9 +1314,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'
   },
@@ -1322,9 +1326,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'
   },
@@ -1333,9 +1338,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)" }
@@ -1545,9 +1551,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: [
@@ -1577,9 +1584,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: [
@@ -1593,9 +1601,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: [
@@ -1609,9 +1618,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: [
@@ -1625,9 +1635,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: [
@@ -1880,9 +1891,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")' },
@@ -1946,9 +1958,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" }