@lowdefy/shell 3.23.2 → 7.2.0

package/src/host/reportShellError.test.js

@@ -0,0 +1,79 @@
+/*
+  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 { jest } from '@jest/globals';
+import { RequestError, UserError } from '@lowdefy/errors';
+
+import createNetworkError from '../test/createNetworkError.js';
+import reportShellError from './reportShellError.js';
+
+function createSession(handleError) {
+  return { getState: () => ({ lowdefy: { _internal: { handleError } } }) };
+}
+
+let consoleError;
+
+beforeEach(() => {
+  consoleError = jest.spyOn(console, 'error').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  consoleError.mockRestore();
+});
+
+test('a fault goes to the core handleError once a page has made one', () => {
+  const handleError = jest.fn(async () => {});
+  const error = new RequestError('Something went wrong.');
+  reportShellError({ error, session: createSession(handleError) });
+  expect(handleError).toHaveBeenCalledWith(error);
+  expect(consoleError).not.toHaveBeenCalled();
+});
+
+test('a fault goes to the device console before any page made a core', () => {
+  const error = new Error('Push token registration failed.');
+  reportShellError({ error, session: { getState: () => ({ lowdefy: { buildId: 'b1' } }) } });
+  expect(consoleError).toHaveBeenCalledWith(error);
+});
+
+test('a fault goes to the device console when no app is open', () => {
+  const error = new Error('The shell could not open its database.');
+  reportShellError({ error });
+  expect(consoleError).toHaveBeenCalledWith(error);
+});
+
+test('no network and expected outcomes are not reported', () => {
+  const handleError = jest.fn(async () => {});
+  const session = createSession(handleError);
+  reportShellError({ error: createNetworkError(), session });
+  reportShellError({ error: new UserError('Camera permission was denied.'), session });
+  const refusal = new Error('Not allowed.');
+  refusal.name = 'AuthorizationError';
+  reportShellError({ error: refusal, session });
+  expect(handleError).not.toHaveBeenCalled();
+  expect(consoleError).not.toHaveBeenCalled();
+});
+
+test('a handleError that fails falls back to the device console', async () => {
+  const error = new Error('Background fetch failed.');
+  reportShellError({
+    error,
+    session: createSession(async () => {
+      throw new Error('Logger gone.');
+    }),
+  });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  expect(consoleError).toHaveBeenCalledWith(error);
+});

package/src/host/withNetworkErrors.js

@@ -0,0 +1,38 @@
+/*
+  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.
+*/
+
+/**
+ * Marks a rejection of the platform's fetch as a network failure (isNetworkError): the request never
+ * reached the server, so the offline queue keeps it and the screens say there is no connection.
+ * Marked where the platform answers, so a programming fault later in the send path (a TypeError
+ * reading the response) is never taken for "offline". A call the caller aborted is not marked.
+ *
+ * @param {Function} fetch The platform's fetch (React Native's, expo/fetch, or Lowdefy Dev's).
+ */
+function withNetworkErrors(fetch) {
+  return async function networkErrorFetch(url, init) {
+    try {
+      return await fetch(url, init);
+    } catch (error) {
+      if (init?.signal?.aborted !== true && error instanceof Error) {
+        error.isNetworkError = true;
+      }
+      throw error;
+    }
+  };
+}
+
+export default withNetworkErrors;

package/src/host/withNetworkErrors.test.js

@@ -0,0 +1,61 @@
+/*
+  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 { jest } from '@jest/globals';
+
+import isNetworkError from './isNetworkError.js';
+import withNetworkErrors from './withNetworkErrors.js';
+
+test('a call the platform fetch rejects is marked as a network failure', async () => {
+  const failure = new TypeError('Network request failed');
+  const fetch = withNetworkErrors(jest.fn(async () => Promise.reject(failure)));
+  const error = await fetch('https://app.example.com/api/user', {}).catch((caught) => caught);
+  expect(error).toBe(failure);
+  expect(isNetworkError(error)).toBe(true);
+});
+
+test('expo/fetch failures, which are not TypeErrors, are marked too', async () => {
+  const failure = new Error('fetch failed: The Internet connection appears to be offline.');
+  const fetch = withNetworkErrors(jest.fn(async () => Promise.reject(failure)));
+  const error = await fetch('https://app.example.com/api/agent', {}).catch((caught) => caught);
+  expect(isNetworkError(error)).toBe(true);
+});
+
+test('a call the caller aborted is not a network failure', async () => {
+  const controller = new AbortController();
+  controller.abort();
+  const failure = new Error('The operation was aborted.');
+  const fetch = withNetworkErrors(jest.fn(async () => Promise.reject(failure)));
+  const error = await fetch('https://app.example.com/api/agent', {
+    signal: controller.signal,
+  }).catch((caught) => caught);
+  expect(isNetworkError(error)).toBe(false);
+});
+
+test('a TypeError thrown after the answer arrived is not a network failure', async () => {
+  const response = { ok: true, status: 200 };
+  const fetch = withNetworkErrors(jest.fn(async () => response));
+  const res = await fetch('https://app.example.com/api/user', {});
+  expect(res).toBe(response);
+  let fault;
+  try {
+    res.headers.get('etag');
+  } catch (error) {
+    fault = error;
+  }
+  expect(fault).toBeInstanceOf(TypeError);
+  expect(isNetworkError(fault)).toBe(false);
+});

package/src/host/withShellHeader.js

@@ -0,0 +1,25 @@
+/*
+  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.
+*/
+
+// Every call a shell makes carries x-lowdefy-shell, its version: the server serves mobile pages
+// only to shells and web pages only to browsers.
+function withShellHeader({ fetch, shellVersion }) {
+  return function shellHeaderFetch(url, init = {}) {
+    return fetch(url, { ...init, headers: { ...init.headers, 'x-lowdefy-shell': shellVersion } });
+  };
+}
+
+export default withShellHeader;

package/src/host/withShellHeader.test.js

@@ -0,0 +1,28 @@
+/*
+  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 { jest } from '@jest/globals';
+
+import withShellHeader from './withShellHeader.js';
+
+test('every call carries the shell version as x-lowdefy-shell', async () => {
+  const fetch = jest.fn(async () => ({ status: 200 }));
+  const shellFetch = withShellHeader({ fetch, shellVersion: '7.4.0' });
+  await shellFetch('https://app.example.com/api/page/home', { headers: { Accept: 'x' } });
+  await shellFetch('https://app.example.com/api/user');
+  expect(fetch.mock.calls[0][1].headers).toEqual({ Accept: 'x', 'x-lowdefy-shell': '7.4.0' });
+  expect(fetch.mock.calls[1][1].headers).toEqual({ 'x-lowdefy-shell': '7.4.0' });
+});

package/src/js/evaluateJsEntries.js

@@ -0,0 +1,43 @@
+/*
+  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';
+
+/**
+ * The one place the shell turns `_js` source into functions. A shell is shared by every app, so
+ * it cannot carry an app's compiled clientJsMap: each mobile page, and the mobile root for the
+ * app events, carries its `_js` as `_jsEntries`, the module text the build generates
+ * (`export default { [hash]: fn }`). It is evaluated with `new Function`, as the dev server
+ * evaluates a page it builds on request (server-dev usePageConfig), and keeps the `volatile` flag
+ * the module sets for dependency tracking.
+ *
+ * Hermes must run `new Function` for this to work. Should it not, `_js` on mobile pages becomes a
+ * build error, and this function the one place that refuses it.
+ *
+ * @param {string|null|undefined} jsEntries The module text; none when the page has no `_js`.
+ * @returns {Object} `{ [hash]: fn }`, the jsMap the engine's `_js` operator reads.
+ */
+function evaluateJsEntries(jsEntries) {
+  if (type.isNone(jsEntries)) {
+    return {};
+  }
+  const define = new Function('exports', jsEntries.replace('export default', 'exports.default ='));
+  const module = {};
+  define(module);
+  return module.default;
+}
+
+export default evaluateJsEntries;

package/src/js/evaluateJsEntries.test.js

@@ -0,0 +1,48 @@
+/*
+  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 evaluateJsEntries from './evaluateJsEntries.js';
+import helloJsEntries from '../../fixtures/hello.jsEntries.json';
+
+const accessors = {
+  lowdefyGlobal: (key) => ({ greeting: 'Hello from Lowdefy' })[key],
+};
+
+test('evaluateJsEntries turns the hello page module text into its _js functions', () => {
+  const jsMap = evaluateJsEntries(helloJsEntries.today);
+  expect(Object.keys(jsMap)).toEqual([
+    'HorPchxU3cTNYhB6dbx9DFcepx4=',
+    'b+IYcPY3kW9J7YdZ4RyICtelfz8=',
+  ]);
+  expect(jsMap['HorPchxU3cTNYhB6dbx9DFcepx4='](accessors)).toBe('Hello from Lowdefy');
+  expect(jsMap['b+IYcPY3kW9J7YdZ4RyICtelfz8='](accessors)).toBe(String(new Date().getFullYear()));
+});
+
+test('evaluateJsEntries keeps the volatile flag dependency tracking reads', () => {
+  const jsMap = evaluateJsEntries(helloJsEntries.today);
+  expect(jsMap['b+IYcPY3kW9J7YdZ4RyICtelfz8='].volatile).toBe(true);
+  expect(jsMap['HorPchxU3cTNYhB6dbx9DFcepx4='].volatile).toBeUndefined();
+});
+
+test('evaluateJsEntries evaluates the app events module text of the root', () => {
+  const jsMap = evaluateJsEntries(helloJsEntries.app);
+  expect(jsMap['yHZGzdxAuSQ8P5USi0AFFY81iNg='](accessors)).toBe('Hello from Lowdefy');
+});
+
+test('evaluateJsEntries gives an empty map for a page without _js', () => {
+  expect(evaluateJsEntries(undefined)).toEqual({});
+  expect(evaluateJsEntries(null)).toEqual({});
+});

package/src/locale/createShellLocale.js

@@ -0,0 +1,112 @@
+/*
+  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 { appStorageKey, type } from '@lowdefy/helpers';
+
+import loadDayjsLocale from './loadDayjsLocale.js';
+import resolveActiveLocale from './resolveActiveLocale.js';
+
+/**
+ * The locale of one app in the shell, kept as the web client keeps it (useLocale): the app's
+ * i18n config from the mobile root, the person's choice that SetLocale sets and the device store
+ * keeps under the app's key, and the device's locale.
+ *
+ * `apply` points the app at its active locale: `lowdefy.i18n` (read by `_t`, `_locale` and
+ * translate), the window members the engine trace reads, and the dayjs locale `_dayjs` formats
+ * with. Screens call it as they render and re-render on `subscribe`.
+ *
+ * It sets `window.__lowdefy_setLocale`, which actions-core's SetLocale calls.
+ *
+ * @param {Object} params
+ * @param {() => string[]} params.getDeviceLocales
+ * @param {Object} params.globals The app's host globals.
+ * @param {Object} params.session The app's session (createAppSession).
+ * @param {Object} params.storage The device store.
+ */
+function createShellLocale({ getDeviceLocales, globals, session, storage }) {
+  const listeners = new Set();
+  let version = 0;
+
+  function getStorageKey() {
+    const { rootConfig } = session.getState();
+    return appStorageKey({
+      basePath: '',
+      name: 'lowdefy_locale',
+      slug: rootConfig.lowdefyApp.slug,
+    });
+  }
+
+  // A host store may throw when the platform blocks storage, as the core allows; the choice then
+  // lasts only while the app runs.
+  function readPreference() {
+    try {
+      return storage.get(getStorageKey()) ?? 'auto';
+    } catch {
+      return 'auto';
+    }
+  }
+
+  function writePreference(preference) {
+    try {
+      if (preference === 'auto') {
+        storage.remove(getStorageKey());
+        return;
+      }
+      storage.set(getStorageKey(), preference);
+    } catch {
+      // See readPreference.
+    }
+  }
+
+  function apply() {
+    const { lowdefy, rootConfig } = session.getState();
+    const { i18n } = rootConfig;
+    if (type.isNone(i18n.defaultLocale)) {
+      return;
+    }
+    const active = resolveActiveLocale({
+      deviceLocales: getDeviceLocales(),
+      i18n,
+      preference: readPreference(),
+    });
+    lowdefy.i18n = { ...i18n, active };
+    globals.window.__lowdefy_locale = active;
+    globals.window.__lowdefy_supported_locales = i18n.locales;
+    const dayjsId = i18n.locales.find((locale) => locale.code === active)?.dayjs;
+    if (type.isString(dayjsId)) {
+      loadDayjsLocale(dayjsId);
+    }
+  }
+
+  // Applied now, not on the next render: SetLocale updates the engine straight after.
+  function setPreference(code) {
+    writePreference(code ?? 'auto');
+    apply();
+    version += 1;
+    listeners.forEach((listener) => listener());
+  }
+
+  function subscribe(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  }
+
+  globals.window.__lowdefy_setLocale = setPreference;
+
+  return { apply, getVersion: () => version, setPreference, subscribe };
+}
+
+export default createShellLocale;

package/src/locale/createShellLocale.test.js

@@ -0,0 +1,74 @@
+/*
+  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 { jest } from '@jest/globals';
+
+import createMemoryStore from '../host/createMemoryStore.js';
+import createShellLocale from './createShellLocale.js';
+
+const i18n = {
+  defaultLocale: 'en-US',
+  locales: [
+    { code: 'en-US', dayjs: 'en' },
+    { code: 'af-ZA', dayjs: 'af' },
+  ],
+  messages: {},
+};
+
+function createLocale(rootI18n) {
+  const lowdefy = {};
+  const session = {
+    getState: () => ({ lowdefy, rootConfig: { i18n: rootI18n, lowdefyApp: { slug: 'field' } } }),
+  };
+  const globals = { window: {} };
+  const storage = createMemoryStore();
+  const locale = createShellLocale({
+    getDeviceLocales: () => ['en-ZA'],
+    globals,
+    session,
+    storage,
+  });
+  return { globals, locale, lowdefy, storage };
+}
+
+test('createShellLocale points lowdefy.i18n and the window at the active locale', () => {
+  const { globals, locale, lowdefy } = createLocale(i18n);
+  locale.apply();
+  expect(lowdefy.i18n).toEqual({ ...i18n, active: 'en-US' });
+  expect(globals.window.__lowdefy_locale).toBe('en-US');
+  expect(globals.window.__lowdefy_supported_locales).toBe(i18n.locales);
+});
+
+test('SetLocale sets the choice through the window, keeps it and tells the screens', () => {
+  const { globals, locale, lowdefy, storage } = createLocale(i18n);
+  const listener = jest.fn();
+  locale.subscribe(listener);
+  globals.window.__lowdefy_setLocale('af-ZA');
+  expect(lowdefy.i18n.active).toBe('af-ZA');
+  expect(storage.get('lowdefy:field::lowdefy_locale')).toBe('af-ZA');
+  expect(listener).toHaveBeenCalledTimes(1);
+  expect(locale.getVersion()).toBe(1);
+  globals.window.__lowdefy_setLocale('auto');
+  expect(storage.keys()).toEqual([]);
+  expect(lowdefy.i18n.active).toBe('en-US');
+});
+
+test('createShellLocale leaves an app without i18n alone', () => {
+  const { globals, locale, lowdefy } = createLocale({});
+  locale.apply();
+  expect(lowdefy.i18n).toBeUndefined();
+  expect(globals.window.__lowdefy_locale).toBeUndefined();
+});