@lowdefy/build 5.6.0 → 6.0.0

package/dist/build/buildPages/buildPage.js

@@ -15,6 +15,7 @@
 */ import { type } from '@lowdefy/helpers';
 import { ConfigError, ConfigWarning } from '@lowdefy/errors';
 import buildBlock from './buildBlock/buildBlock.js';
+import buildSubscriptions from './buildSubscriptions.js';
 import collectExceptions from '../../utils/collectExceptions.js';
 import createCheckDuplicateId from '../../utils/createCheckDuplicateId.js';
 import validateId from '../../utils/validateId.js';
@@ -54,10 +55,16 @@ function buildPage({ page, index, context, checkDuplicatePageId }) {
     const requests = [];
     const requestActionRefs = [];
     const shortcutRefs = [];
-    buildBlock(page, {
+    // Extract subscriptions before block building — validateBlock rejects the
+    // subscriptions key on nested blocks, so the page root must not carry it.
+    const subscriptions = page.subscriptions;
+    delete page.subscriptions;
+    const pageContext = {
         auth: page.auth,
         blockIdCounter: createCounter(),
         callApiActionRefs: context.callApiActionRefs ?? [],
+        websocketActionRefs: context.websocketActionRefs ?? [],
+        dynamicBlockRefs: context.dynamicBlockRefs ?? [],
         checkDuplicateRequestId: createCheckDuplicateId({
             message: 'Duplicate requestId "{{ id }}" on page "{{ pageId }}".'
         }),
@@ -68,9 +75,26 @@ function buildPage({ page, index, context, checkDuplicatePageId }) {
         shortcutRefs,
         linkActionRefs: context.linkActionRefs,
         typeCounters: context.typeCounters
-    });
+    };
+    buildBlock(page, pageContext);
     // set page.id since buildBlock sets id as well.
     page.id = `page:${page.pageId}`;
+    // Flag pages with Dynamic blocks so the server can skip resolution
+    // (and the deep copy it requires) for static pages with one property read.
+    if (pageContext.hasDynamicBlocks === true) {
+        page.dynamic = true;
+    }
+    page.subscriptions = subscriptions;
+    buildSubscriptions(page, {
+        callApiActionRefs: context.callApiActionRefs ?? [],
+        context,
+        linkActionRefs: context.linkActionRefs,
+        pageId: page.pageId,
+        requestActionRefs,
+        shortcutRefs,
+        typeCounters: context.typeCounters,
+        websocketActionRefs: context.websocketActionRefs ?? []
+    });
     // Validate that all Request actions reference defined requests
     validateRequestReferences({
         requestActionRefs,
@@ -79,7 +103,7 @@ function buildPage({ page, index, context, checkDuplicatePageId }) {
         context
     });
     // Warn on duplicate shortcuts within the page
-    const seenShortcuts = {};
+    const seenShortcuts = Object.create(null);
     shortcutRefs.forEach(({ shortcut, blockId, eventId, configKey })=>{
         if (seenShortcuts[shortcut]) {
             context.handleWarning(new ConfigWarning(`Duplicate shortcut "${shortcut}" on event "${eventId}" on block "${blockId}" on page "${page.pageId}" — already defined on block "${seenShortcuts[shortcut].blockId}".`, {

package/dist/build/buildPages/buildSubscriptions.js

@@ -0,0 +1,145 @@
+/* eslint-disable no-param-reassign */ /*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { type } from '@lowdefy/helpers';
+import { ConfigError, ConfigWarning } from '@lowdefy/errors';
+import buildEvents from './buildBlock/buildEvents.js';
+import countOperators from '../../utils/countOperators.js';
+import createCheckDuplicateId from '../../utils/createCheckDuplicateId.js';
+const SUBSCRIPTION_EVENTS = [
+    'onMessage',
+    'onSubscribe',
+    'onError'
+];
+const DEFAULT_MAX_MESSAGES = 100;
+const DEFAULT_THROTTLE_RENDER = 250;
+const MIN_THROTTLE_RENDER = 100;
+function buildSubscription({ subscription, pageContext }) {
+    const { context, pageId } = pageContext;
+    const configKey = subscription['~k'];
+    if (type.isUndefined(subscription.websocketId)) {
+        throw new ConfigError(`Subscription websocketId missing at page "${pageId}".`, {
+            configKey
+        });
+    }
+    if (!type.isString(subscription.websocketId)) {
+        throw new ConfigError(`Subscription websocketId is not a string at page "${pageId}".`, {
+            received: subscription.websocketId,
+            configKey
+        });
+    }
+    pageContext.checkDuplicateSubscriptionId({
+        id: subscription.websocketId,
+        configKey,
+        pageId
+    });
+    if (!context.websocketIds.has(subscription.websocketId)) {
+        throw new ConfigError(`Subscription "${subscription.websocketId}" at page "${pageId}" references a websocket which does not exist.`, {
+            configKey
+        });
+    }
+    if (type.isNone(subscription.payload)) {
+        subscription.payload = {};
+    }
+    if (!type.isObject(subscription.payload)) {
+        throw new ConfigError(`Subscription "${subscription.websocketId}" at page "${pageId}" payload should be an object.`, {
+            received: subscription.payload,
+            configKey
+        });
+    }
+    if (type.isNone(subscription.client)) {
+        subscription.client = {};
+    }
+    if (!type.isObject(subscription.client)) {
+        throw new ConfigError(`Subscription "${subscription.websocketId}" at page "${pageId}" client should be an object.`, {
+            received: subscription.client,
+            configKey
+        });
+    }
+    if (type.isNone(subscription.client.maxMessages)) {
+        subscription.client.maxMessages = DEFAULT_MAX_MESSAGES;
+    }
+    if (!type.isInt(subscription.client.maxMessages) || subscription.client.maxMessages < 1) {
+        throw new ConfigError(`Subscription "${subscription.websocketId}" at page "${pageId}" client.maxMessages should be a positive integer.`, {
+            received: subscription.client.maxMessages,
+            configKey
+        });
+    }
+    if (type.isNone(subscription.client.throttleRender)) {
+        subscription.client.throttleRender = DEFAULT_THROTTLE_RENDER;
+    }
+    if (!type.isNumber(subscription.client.throttleRender)) {
+        throw new ConfigError(`Subscription "${subscription.websocketId}" at page "${pageId}" client.throttleRender should be a number.`, {
+            received: subscription.client.throttleRender,
+            configKey
+        });
+    }
+    if (subscription.client.throttleRender < MIN_THROTTLE_RENDER) {
+        context.handleWarning(new ConfigWarning(`Subscription "${subscription.websocketId}" at page "${pageId}" client.throttleRender is below the minimum of ${MIN_THROTTLE_RENDER}ms and will be clamped.`, {
+            configKey
+        }));
+        subscription.client.throttleRender = MIN_THROTTLE_RENDER;
+    }
+    if (type.isNone(subscription.events)) {
+        subscription.events = {};
+    }
+    Object.keys(subscription.events).forEach((eventName)=>{
+        if (eventName.startsWith('~')) return;
+        if (!SUBSCRIPTION_EVENTS.includes(eventName)) {
+            context.handleWarning(new ConfigWarning(`Subscription "${subscription.websocketId}" at page "${pageId}" has event "${eventName}" which will never fire. Supported events: ${SUBSCRIPTION_EVENTS.join(', ')}.`, {
+                configKey: subscription.events[eventName]?.['~k'] ?? configKey
+            }));
+        }
+    });
+    // Reuse the block event builder — normalizes actions to { try, catch },
+    // validates action ids, counts action types, and collects Request action
+    // refs so subscription events can trigger page requests.
+    buildEvents({
+        blockId: `subscription:${subscription.websocketId}`,
+        events: subscription.events,
+        '~k': configKey
+    }, pageContext);
+    // Subscriptions are extracted from the page before buildBlock runs, so
+    // countBlockOperators never sees them — count client operators here.
+    // Payload and event action params are both evaluated client-side.
+    countOperators({
+        events: subscription.events,
+        payload: subscription.payload
+    }, {
+        counter: pageContext.typeCounters.operators.client
+    });
+    subscription.pageId = pageId;
+    subscription.id = `subscription:${pageId}:${subscription.websocketId}`;
+}
+function buildSubscriptions(page, pageContext) {
+    if (type.isNone(page.subscriptions)) {
+        page.subscriptions = [];
+    }
+    if (!type.isArray(page.subscriptions)) {
+        throw new ConfigError(`Subscriptions is not an array at page "${pageContext.pageId}".`, {
+            received: page.subscriptions,
+            configKey: page['~k']
+        });
+    }
+    pageContext.checkDuplicateSubscriptionId = createCheckDuplicateId({
+        message: 'Duplicate subscription "{{ id }}" on page "{{ pageId }}".'
+    });
+    page.subscriptions.forEach((subscription)=>{
+        buildSubscription({
+            subscription,
+            pageContext
+        });
+    });
+}
+export default buildSubscriptions;

package/dist/build/buildPages/validateDynamicBlockRefs.js

@@ -0,0 +1,30 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { ConfigWarning } from '@lowdefy/errors';
+function validateDynamicBlockRefs({ dynamicBlockRefs, endpointConfigs, context }) {
+    // Both Api and InternalApi endpoints are valid — resolution is an in-process
+    // call, so InternalApi is the recommended resolver type.
+    const existingEndpointIds = new Set(endpointConfigs.map((config)=>config.endpointId));
+    dynamicBlockRefs.forEach(({ endpointId, block, sourcePageId })=>{
+        if (!existingEndpointIds.has(endpointId)) {
+            context.handleWarning(new ConfigWarning(`Dynamic block "${block.blockId}" on page "${sourcePageId}" references non-existent endpoint "${endpointId}".`, {
+                configKey: block['~k'],
+                prodError: true,
+                checkSlug: 'dynamic-endpoint-refs'
+            }));
+        }
+    });
+}
+export default validateDynamicBlockRefs;

package/dist/build/buildPages/validateStateReferences.js

@@ -68,10 +68,12 @@ function validateStateReferences({ page, context }) {
     stateRefs.forEach((configKey, topLevelKey)=>{
         // Skip if state key is from an input block or SetState action
         if (blockIds.has(topLevelKey) || setStateKeys.has(topLevelKey)) return;
-        const message = `_state references "${topLevelKey}" on page "${page.pageId}", ` + `but no input block with id "${topLevelKey}" exists on this page. ` + `State keys are created from input block ids. ` + `Check for typos, add an input block with this id, or initialize the state with SetState.`;
+        const message = `_state references "${topLevelKey}" on page "${page.pageId}", ` + `but no input block with id "${topLevelKey}" exists on this page. ` + `State keys are created from input block ids. ` + `Check for typos, add an input block with this id, or initialize the state with SetState. ` + `If the state is set at runtime (for example by a custom action calling setState), ` + `suppress this check with "~ignoreBuildChecks: [state-refs]" on the reference.`;
+        // This check is a heuristic: state written at runtime — custom actions
+        // calling setState, dynamic SetState wrappers — is statically invisible,
+        // so a miss here must never fail a production build (no prodError).
         context.handleWarning(new ConfigWarning(message, {
             configKey,
-            prodError: true,
             checkSlug: 'state-refs'
         }));
     });

package/dist/build/buildPages/validateWebsocketRefs.js

@@ -0,0 +1,30 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { ConfigWarning } from '@lowdefy/errors';
+function validateWebsocketRefs({ websocketActionRefs, websocketIds, context }) {
+    websocketActionRefs.forEach(({ websocketId, action, actionType, sourcePageId })=>{
+        if (action.skip === true) {
+            return;
+        }
+        if (!websocketIds.has(websocketId)) {
+            context.handleWarning(new ConfigWarning(`${actionType} action on page "${sourcePageId}" references non-existent websocket "${websocketId}".`, {
+                configKey: action['~k'],
+                prodError: true,
+                checkSlug: 'websocket-refs'
+            }));
+        }
+    });
+}
+export default validateWebsocketRefs;

package/dist/build/buildRefs/buildRefs.js

@@ -16,7 +16,6 @@
 import { resolve, WalkContext } from './walker.js';
 import getRefContent from './getRefContent.js';
 import makeRefDefinition from './makeRefDefinition.js';
-import evaluateStaticOperators from './evaluateStaticOperators.js';
 import collectDynamicIdentifiers from '../collectDynamicIdentifiers.js';
 import validateOperatorsDynamic from '../validateOperatorsDynamic.js';
 import isPageContentPath from '../jit/isPageContentPath.js';
@@ -30,6 +29,9 @@ const dynamicIdentifiers = collectDynamicIdentifiers({
 async function buildRefs({ context, shallowOptions }) {
     context.unresolvedRefVars = context.unresolvedRefVars ?? {};
     const refDef = makeRefDefinition('lowdefy.yaml', null, context.refMap);
+    // Stash for Phase 3.5 (precomputeRuntimeOperators) so it can resolve error
+    // source file paths without creating a new makeId entry.
+    context.rootRefDef = refDef;
     const ctx = new WalkContext({
         buildContext: context,
         refId: refDef.id,
@@ -42,24 +44,31 @@ async function buildRefs({ context, shallowOptions }) {
         ] : []),
         operators,
         env: process.env,
+        lowdefyApp: context.appMeta,
         dynamicIdentifiers,
-        shouldStop: shallowOptions ? // JIT can re-resolve them from source files. Inline pages (defined
-        // directly in lowdefy.yaml) live in the root ref and have no separate
-        // source file — their content must be preserved for buildShallowPages.
-        (path, refId)=>isPageContentPath(path) && refId !== refDef.id : null
+        shouldStop: (path, refId)=>{
+            // Module entry vars/connections were already resolved by parseLowdefyYaml
+            // (same predicate) and live on context.modules — preserve the raw blobs so
+            // the app pass doesn't pull and walk their refs a second time. buildModules
+            // reads entry ids only and deletes components.modules before testSchema.
+            if (/^modules\.\d+\.vars$/.test(path)) return 'preserve';
+            if (/^modules\.\d+\.connections$/.test(path)) return 'preserve';
+            if (shallowOptions) {
+                // Strip page content (blocks, events, etc.) from ref-backed pages so
+                // JIT can re-resolve them from source files. Inline pages (defined
+                // directly in lowdefy.yaml) live in the root ref and have no separate
+                // source file — their content must be preserved for buildShallowPages.
+                return isPageContentPath(path) && refId !== refDef.id;
+            }
+            return null;
+        }
     });
     const content = await getRefContent({
         context,
         refDef,
         referencedFrom: null
     });
-    let components = await resolve(content, ctx);
-    // Evaluate static operators (_sum, _if, etc.) that don't depend on runtime data
-    components = evaluateStaticOperators({
-        context,
-        input: components,
-        refDef
-    });
+    const components = await resolve(content, ctx);
     return components ?? {};
 }
 export default buildRefs;

package/dist/build/buildRefs/cloneWithMarkers.js

@@ -0,0 +1,57 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { type } from '@lowdefy/helpers';
+import setNonEnumerableProperty from '../../utils/setNonEnumerableProperty.js';
+// THE deep clone for config subtrees inside buildRefs — preserves the
+// non-enumerable provenance markers (~r ~l ~k ~arr), and with assignRefId set
+// stamps ~r on nodes that have none (pass nothing to preserve the template's
+// existing markers only). Non-plain values (Date) pass by reference; nothing
+// in the build mutates them.
+//
+// Do not use serializer.copy on config subtrees in buildRefs: it round-trips
+// the same markers but pays a JSON round-trip and re-instantiates Dates — the
+// serializer is the artifact boundary, this is the in-memory clone.
+function cloneWithMarkers(value, { assignRefId = null } = {}) {
+    if (!type.isObject(value) && !type.isArray(value)) return value;
+    let clone;
+    if (type.isArray(value)) {
+        clone = value.map((item)=>cloneWithMarkers(item, {
+                assignRefId
+            }));
+    } else {
+        clone = {};
+        for (const key of Object.keys(value)){
+            clone[key] = cloneWithMarkers(value[key], {
+                assignRefId
+            });
+        }
+    }
+    if (value['~r'] !== undefined) {
+        setNonEnumerableProperty(clone, '~r', value['~r']);
+    } else if (assignRefId) {
+        setNonEnumerableProperty(clone, '~r', assignRefId);
+    }
+    for (const marker of [
+        '~l',
+        '~k',
+        '~arr'
+    ]){
+        if (value[marker] !== undefined) {
+            setNonEnumerableProperty(clone, marker, value[marker]);
+        }
+    }
+    return clone;
+}
+export default cloneWithMarkers;

package/dist/build/buildRefs/deferredRegions.js

@@ -0,0 +1,80 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ // The single source of truth for which module-manifest regions each build
+// phase defers, records, or skips — one table instead of hand-maintained
+// shouldStop regex sets that must agree.
+//
+// Phases:
+// - 'header'      Phase A: parse static header keys (dependencies, plugins,
+//                 secrets, vars definitions — defaults record-ified); content
+//                 sections stay raw parsed YAML ('skip' = leave raw, do not
+//                 descend).
+// - 'exportables' Phase C.5: record-ify per-consumer bodies (components,
+//                 menu links) in module-static scope; everything else stays
+//                 raw for Phase D.
+// - 'manifest'    Phase D: one full walk; only varDefault placeholders need a
+//                 rule (single-value kinds would otherwise be forced by the
+//                 placeholder dispatch — they are demand-only). Per-consumer
+//                 placeholders pass through the dispatch untouched.
+//
+// entryRef/connRemap creation is value-shape-driven (deferModuleRefs in the
+// walker), not path-driven, so it has no row here. The JIT page-content
+// predicate lives in buildRefs.js (it composes with the app-pass modules
+// preserve and is not a manifest phase).
+const VAR_DEFAULT = /^vars(\.[^.]+\.properties)*\.[^.]+\.default(\..*)?$/;
+const CONTENT_SECTIONS = /^(pages|api|connections|agents|notifications|menus|components)(\..*)?$/;
+const NON_EXPORTABLE_SECTIONS = /^(pages|api|connections|agents|notifications|vars|dependencies|plugins|secrets)(\..*)?$/;
+const DEFERRED_REGIONS = [
+    {
+        phase: 'header',
+        match: VAR_DEFAULT,
+        action: 'record:varDefault'
+    },
+    {
+        phase: 'header',
+        match: CONTENT_SECTIONS,
+        action: 'skip'
+    },
+    {
+        phase: 'exportables',
+        match: /^components\.\d+\.component$/,
+        action: 'record:component'
+    },
+    {
+        phase: 'exportables',
+        match: /^menus\.\d+\.links$/,
+        action: 'record:menuLinks'
+    },
+    {
+        phase: 'exportables',
+        match: NON_EXPORTABLE_SECTIONS,
+        action: 'skip'
+    },
+    {
+        phase: 'manifest',
+        match: VAR_DEFAULT,
+        action: 'record:varDefault'
+    }
+];
+function makeShouldStop(phase) {
+    const rows = DEFERRED_REGIONS.filter((row)=>row.phase === phase);
+    return (childPath)=>{
+        for (const row of rows){
+            if (row.match.test(childPath)) return row.action;
+        }
+        return false;
+    };
+}
+export { DEFERRED_REGIONS, makeShouldStop };