@kernlang/core 3.5.8-canary.210.1.239de0e0 → 3.5.8

package/dist/schema.js

@@ -18,6 +18,7 @@
 import { isPostfixMutationOperator, isSupportedAssignOperator, SUPPORTED_ASSIGN_OPERATORS, } from './assignment-operators.js';
 import { VALID_TARGETS } from './config.js';
 import { validateCapabilityMetadata, validateImportMetadata } from './import-metadata.js';
+import { parsePortablePredicateProp, validatePortablePredicateAST } from './portable-predicate.js';
 import { defaultRuntime } from './runtime.js';
 import { KERN_VERSION, NODE_TYPES, STYLE_SHORTHANDS, VALUE_SHORTHANDS } from './spec.js';
 // ── Schema Definitions ──────────────────────────────────────────────────
@@ -588,7 +589,12 @@ export const NODE_SCHEMAS = {
             'do',
             'fmt',
             'clamp',
+            'firstTruthy',
+            'coalesce',
+            'firstDefined',
             'objectMerge',
+            'objectOmit',
+            'objectPick',
             'return',
             'if',
             'else',
@@ -628,7 +634,12 @@ export const NODE_SCHEMAS = {
             'do',
             'fmt',
             'clamp',
+            'firstTruthy',
+            'coalesce',
+            'firstDefined',
             'objectMerge',
+            'objectOmit',
+            'objectPick',
             'return',
             'if',
             'else',
@@ -654,7 +665,12 @@ export const NODE_SCHEMAS = {
             'do',
             'fmt',
             'clamp',
+            'firstTruthy',
+            'coalesce',
+            'firstDefined',
             'objectMerge',
+            'objectOmit',
+            'objectPick',
             'return',
             'if',
             'else',
@@ -669,13 +685,14 @@ export const NODE_SCHEMAS = {
         ],
     },
     filter: {
-        description: 'Declarative `.filter` binding — `filter name=active in=items where="item.active"` lowers to `const active = items.filter(item => item.active);`. Use `item=x` to rename the per-item binding.',
-        example: 'filter name=active in=items where="item.active"',
+        description: 'Declarative `.filter` binding — `filter name=active in=items where="item.active"` lowers to `const active = items.filter(item => item.active);`. Portable routes may use `predicate={{ {eq: ["active", true]} }}` for target-normalized logic. Use `item=x` to rename the per-item binding.',
+        example: 'filter name=active in=items predicate={{ {eq: ["active", true]} }}',
         props: {
             name: { required: true, kind: 'identifier' },
             in: { required: true, kind: 'rawExpr' },
             item: { kind: 'identifier' },
-            where: { required: true, kind: 'rawExpr' },
+            where: { kind: 'rawExpr' },
+            predicate: { kind: 'rawExpr' },
             type: { kind: 'typeAnnotation' },
             export: { kind: 'boolean' },
         },
@@ -813,6 +830,39 @@ export const NODE_SCHEMAS = {
             export: { kind: 'boolean' },
         },
     },
+    firstTruthy: {
+        description: 'Declarative ordered truthy fallback binding — `firstTruthy name=label values="preferred, nickname, \'Anonymous\'"` lowers to the first truthy value using TS `||` and Python `or`. Empty string, zero, false, null/None, and undefined all fall through.',
+        example: 'firstTruthy name=label values="preferred, nickname, \'Anonymous\'"',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            values: { required: true, kind: 'rawExpr' },
+            type: { kind: 'typeAnnotation' },
+            trailingComment: { kind: 'string' },
+            export: { kind: 'boolean' },
+        },
+    },
+    coalesce: {
+        description: 'Declarative ordered nullish fallback binding — `coalesce name=label values="preferred, nickname, \'Anonymous\'"` lowers to the first defined value using TS `??` and Python None-only fallback logic. Preserves falsy values like empty string, zero, and false.',
+        example: 'coalesce name=label values="preferred, nickname, \'Anonymous\'"',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            values: { required: true, kind: 'rawExpr' },
+            type: { kind: 'typeAnnotation' },
+            trailingComment: { kind: 'string' },
+            export: { kind: 'boolean' },
+        },
+    },
+    firstDefined: {
+        description: 'Alias for coalesce — declarative ordered nullish fallback binding.',
+        example: 'firstDefined name=label values="preferred, nickname, \'Anonymous\'"',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            values: { required: true, kind: 'rawExpr' },
+            type: { kind: 'typeAnnotation' },
+            trailingComment: { kind: 'string' },
+            export: { kind: 'boolean' },
+        },
+    },
     objectMerge: {
         description: 'Declarative shallow record merge binding — `objectMerge name=merged sources="base, overrides, { extra: 1 }"` lowers to a new object/dict. Sources are evaluated left-to-right, duplicate keys are last-write-wins, and source records are not mutated.',
         example: 'objectMerge name=merged sources="base, overrides, { extra: 1 }"',
@@ -824,6 +874,60 @@ export const NODE_SCHEMAS = {
             export: { kind: 'boolean' },
         },
     },
+    objectPick: {
+        description: "Declarative shallow record key selection — `objectPick name=picked in=user keys=\"['id', 'name']\"` lowers to a new object/dict containing the picked keys in order; missing keys are materialized as null/None for cross-target parity.",
+        example: "objectPick name=picked in=user keys=\"['id', 'name']\"",
+        props: {
+            name: { required: true, kind: 'identifier' },
+            in: { required: true, kind: 'rawExpr' },
+            keys: { required: true, kind: 'rawExpr' },
+            type: { kind: 'typeAnnotation' },
+            trailingComment: { kind: 'string' },
+            export: { kind: 'boolean' },
+        },
+    },
+    objectOmit: {
+        description: 'Declarative shallow record key omission — `objectOmit name=omitted in=user keys="[\'password\']"` lowers to a new object/dict omitting the specified keys.',
+        example: 'objectOmit name=omitted in=user keys="[\'password\']"',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            in: { required: true, kind: 'rawExpr' },
+            keys: { required: true, kind: 'rawExpr' },
+            type: { kind: 'typeAnnotation' },
+            trailingComment: { kind: 'string' },
+            export: { kind: 'boolean' },
+        },
+    },
+    objectKeys: {
+        description: 'Declarative own-key extraction — `objectKeys name=keys in=user` lowers to Object.keys-style key ordering over a safe record view. Null and primitive inputs produce an empty list in route lowering.',
+        example: 'objectKeys name=keys in=user',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            in: { required: true, kind: 'rawExpr' },
+            type: { kind: 'typeAnnotation' },
+            export: { kind: 'boolean' },
+        },
+    },
+    objectValues: {
+        description: 'Declarative own-value extraction — `objectValues name=values in=user` follows the same key order as objectKeys. Null and primitive inputs produce an empty list in route lowering.',
+        example: 'objectValues name=values in=user',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            in: { required: true, kind: 'rawExpr' },
+            type: { kind: 'typeAnnotation' },
+            export: { kind: 'boolean' },
+        },
+    },
+    objectEntries: {
+        description: 'Declarative own-entry extraction — `objectEntries name=entries in=user` returns two-item [key, value] pairs in Object.entries-style order. Null and primitive inputs produce an empty list in route lowering.',
+        example: 'objectEntries name=entries in=user',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            in: { required: true, kind: 'rawExpr' },
+            type: { kind: 'typeAnnotation' },
+            export: { kind: 'boolean' },
+        },
+    },
     sort: {
         description: 'Declarative immutable sort — `sort name=sorted in=items compare="a.age - b.age"` lowers to `const sorted = [...items].sort((a, b) => a.age - b.age);`. Source collection is never mutated. Omit `compare` for lexicographic sort. Rename bindings with `a=` / `b=`.',
         example: 'sort name=sorted in=items compare="a.age - b.age"',
@@ -948,7 +1052,7 @@ export const NODE_SCHEMAS = {
         },
     },
     uniqueBy: {
-        description: 'Key-based dedup (first-wins, matches Lodash uniqBy) — `uniqueBy name=distinct in=users by="item.id"` emits a Set+filter form.',
+        description: 'Key-based dedup over scalar/hashable selector keys (first-wins, matches Lodash uniqBy) — `uniqueBy name=distinct in=users by="item.id"` emits a Set+filter form.',
         example: 'uniqueBy name=distinct in=users by="item.id"',
         props: {
             name: { required: true, kind: 'identifier' },
@@ -960,7 +1064,7 @@ export const NODE_SCHEMAS = {
         },
     },
     groupBy: {
-        description: 'Partition an array into buckets by a key selector. Emits a reduce-based form (compatible with ES2022) — does not depend on `Object.groupBy` (ES2024).',
+        description: 'Partition an array into buckets by a scalar/hashable key selector. Emits a reduce-based form (compatible with ES2022) — does not depend on `Object.groupBy` (ES2024).',
         example: 'groupBy name=byType in=items by="item.type"',
         props: {
             name: { required: true, kind: 'identifier' },
@@ -972,7 +1076,7 @@ export const NODE_SCHEMAS = {
         },
     },
     partition: {
-        description: 'Split an array into two by a predicate — single-pass reduce. Emits `const [pass, fail] = ...`. Both `pass` and `fail` prop names are required.',
+        description: 'Split an array into two by a predicate — single-pass reduce. Emits `const [pass, fail] = ...`. Both `pass` and `fail` prop names are required. `type=` denotes the element type for each output list.',
         example: 'partition pass=active fail=inactive in=users where="item.active"',
         props: {
             name: { kind: 'identifier' },
@@ -986,7 +1090,7 @@ export const NODE_SCHEMAS = {
         },
     },
     indexBy: {
-        description: 'Array → keyed record via selector. `indexBy name=byId in=users by="item.id"` lowers to `Object.fromEntries(users.map(...))`. Collisions are last-write-wins.',
+        description: 'Array → keyed record via scalar/hashable selector. `indexBy name=byId in=users by="item.id"` lowers to `Object.fromEntries(users.map(...))`. Collisions are last-write-wins.',
         example: 'indexBy name=byId in=users by="item.id"',
         props: {
             name: { required: true, kind: 'identifier' },
@@ -998,7 +1102,7 @@ export const NODE_SCHEMAS = {
         },
     },
     countBy: {
-        description: 'Count occurrences by key. `countBy name=counts in=items by="item.type"` lowers to a reduce with `Object.create(null)` accumulator (prototype-pollution safe).',
+        description: 'Count occurrences by scalar/hashable selector key. `countBy name=counts in=items by="item.type"` lowers to a reduce with `Object.create(null)` accumulator (prototype-pollution safe).',
         example: 'countBy name=counts in=items by="item.type"',
         props: {
             name: { required: true, kind: 'identifier' },
@@ -1329,6 +1433,19 @@ export const NODE_SCHEMAS = {
             export: { kind: 'boolean' },
         },
     },
+    count: {
+        description: 'Declarative collection cardinality — `count name=total in=items` lowers to collection length; add `where=` to count only matching items without materializing a named filtered collection.',
+        example: 'count name=activeCount in=items where="item.active" type=number',
+        props: {
+            name: { required: true, kind: 'identifier' },
+            in: { required: true, kind: 'rawExpr' },
+            where: { kind: 'rawExpr' },
+            predicate: { kind: 'rawExpr' },
+            item: { kind: 'identifier' },
+            type: { kind: 'typeAnnotation' },
+            export: { kind: 'boolean' },
+        },
+    },
     branch: {
         description: 'Pattern-match/switch on an expression — contains `path` children. Top-level form (statement context) emits TS `switch` with `case` blocks. Body-statement form (child of `handler lang="kern"` / `try` / `catch`) emits the same TS `switch` plus a Python `if/elif/else` chain on the fastapi target. Each `path value=X` is a case; `path default=true` is the trailing default case (parallels JS `switch`/`default`). Identifier values like `path value=Status.Active` (unquoted) emit raw refs; quoted strings emit JSON-quoted literals.',
         example: 'branch name=route on=path\n  path value="/home"\n  path value="/about"\n  path default=true',
@@ -1570,7 +1687,12 @@ export const NODE_SCHEMAS = {
             'do',
             'fmt',
             'clamp',
+            'firstTruthy',
+            'coalesce',
+            'firstDefined',
             'objectMerge',
+            'objectOmit',
+            'objectPick',
             'return',
             'if',
             'else',
@@ -1656,7 +1778,12 @@ export const NODE_SCHEMAS = {
             'do',
             'fmt',
             'clamp',
+            'firstTruthy',
+            'coalesce',
+            'firstDefined',
             'objectMerge',
+            'objectOmit',
+            'objectPick',
             'return',
             'if',
             'else',
@@ -1689,7 +1816,12 @@ export const NODE_SCHEMAS = {
             'do',
             'fmt',
             'clamp',
+            'firstTruthy',
+            'coalesce',
+            'firstDefined',
             'objectMerge',
+            'objectOmit',
+            'objectPick',
             'return',
             'if',
             'else',
@@ -1723,7 +1855,12 @@ export const NODE_SCHEMAS = {
             'do',
             'fmt',
             'clamp',
+            'firstTruthy',
+            'coalesce',
+            'firstDefined',
             'objectMerge',
+            'objectOmit',
+            'objectPick',
             'return',
             'if',
             'else',
@@ -1792,6 +1929,24 @@ export const NODE_SCHEMAS = {
             'branch',
             'each',
             'collect',
+            'filter',
+            'count',
+            'compact',
+            'pluck',
+            'take',
+            'drop',
+            'sort',
+            'objectMerge',
+            'objectOmit',
+            'objectPick',
+            'objectKeys',
+            'objectValues',
+            'objectEntries',
+            'uniqueBy',
+            'groupBy',
+            'partition',
+            'indexBy',
+            'countBy',
             'effect',
             // Portable side-effect statements — valid as direct route children
             // (alongside derive/guard/respond) for mutate-and-persist routes.
@@ -1893,6 +2048,7 @@ export const NODE_SCHEMAS = {
             'branch',
             'each',
             'collect',
+            'count',
             'destructure',
             'partition',
         ],
@@ -2076,7 +2232,7 @@ export const NODE_SCHEMAS = {
             name: { required: true, kind: 'identifier' },
             in: { required: true, kind: 'rawExpr' },
         },
-        allowedChildren: ['derive', 'let', 'each', 'fanout', 'emit', 'do', 'assign', 'branch', 'collect'],
+        allowedChildren: ['derive', 'let', 'each', 'fanout', 'emit', 'do', 'assign', 'branch', 'collect', 'count'],
     },
     stream: {
         description: 'Async stream — SSE route (backend), or AsyncGenerator → state with cleanup (Ink). mode=channel for dispatch bridging. Backend SSE bodies may be a raw `handler` (legacy) or a portable body of `derive`/`let`/`each`/`fanout`/`emit`/`do`/`assign`/`branch` nodes (slice 4c) that lowers to the same scaffold without raw JS.',
@@ -2104,6 +2260,7 @@ export const NODE_SCHEMAS = {
             'assign',
             'branch',
             'collect',
+            'count',
         ],
     },
     spawn: {
@@ -3203,6 +3360,60 @@ function checkCrossProps(node, violations, parent) {
             col: node.loc?.col,
         });
     }
+    if (node.type === 'filter') {
+        const hasWhere = props.where !== undefined && props.where !== null && String(props.where).trim() !== '';
+        const hasPredicate = props.predicate !== undefined && props.predicate !== null && String(props.predicate).trim() !== '';
+        if (hasPredicate && parent?.type !== 'route' && parent?.type !== 'path') {
+            violations.push({
+                nodeType: 'filter',
+                message: "'filter predicate={{...}}' is supported only as a portable route child",
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
+        if (!hasWhere && !hasPredicate) {
+            violations.push({
+                nodeType: 'filter',
+                message: "'filter' requires either where= or predicate={{...}}",
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
+        if (hasWhere && hasPredicate) {
+            violations.push({
+                nodeType: 'filter',
+                message: "'filter' cannot combine where= and predicate={{...}}",
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
+        if (hasPredicate) {
+            validatePredicateProp(node, violations, props.predicate);
+        }
+    }
+    if (node.type === 'count') {
+        const hasWhere = props.where !== undefined && props.where !== null && String(props.where).trim() !== '';
+        const hasPredicate = props.predicate !== undefined && props.predicate !== null && String(props.predicate).trim() !== '';
+        if (hasPredicate && parent?.type !== 'route' && parent?.type !== 'path') {
+            violations.push({
+                nodeType: 'count',
+                message: "'count predicate={{...}}' is supported only as a portable route child",
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
+        if (hasWhere && hasPredicate) {
+            violations.push({
+                nodeType: 'count',
+                message: "'count' cannot combine where= and predicate={{...}}",
+                line: node.loc?.line,
+                col: node.loc?.col,
+            });
+        }
+        if (hasPredicate) {
+            validatePredicateProp(node, violations, props.predicate);
+        }
+    }
     if (node.type === 'param') {
         // Slice 3c-extension #3: `param` requires `name=` UNLESS it carries
         // `binding`/`element` destructure children — destructured params encode
@@ -3583,6 +3794,24 @@ function checkCrossProps(node, violations, parent) {
         // both present).
     }
 }
+function pushPredicateViolation(node, violations, message) {
+    violations.push({
+        nodeType: node.type,
+        message,
+        line: node.loc?.line,
+        col: node.loc?.col,
+    });
+}
+function validatePredicateProp(node, violations, predicateProp) {
+    const parsed = parsePortablePredicateProp(predicateProp);
+    if (!parsed.ok) {
+        pushPredicateViolation(node, violations, 'predicate must be a valid object literal');
+        return;
+    }
+    for (const message of validatePortablePredicateAST(parsed.value)) {
+        pushPredicateViolation(node, violations, message);
+    }
+}
 function isTruthyProp(raw) {
     return raw === true || raw === 'true';
 }