@soleil-se/app-util 5.2.2 → 5.4.0

package/CHANGELOG.md

@@ -5,29 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [5.2.2] - 2023-01-31
+## [5.4.0] - 2023-08-09
+
+- Add `fetchJson` function to make requests to app routes or other resources.
+
+## [5.3.0] - 2023-07-06
 
-### Changed
+- Added helper functions for managing parameters in the URL-field.
+
+## [5.2.2] - 2023-01-31
 
 - Fix `parseParams` export.
 
 ## [5.2.1] - 2023-01-31
 
-### Changed
-
 - Fix homepage url.
 - More lenient with peerDependency `@sitevision/api`.
 
 ## [5.2.0] - 2023-01-31
 
-### Changed
-
 - New function `parseParams` to parse query parameters from an URL, URI or query string.
 
 ## [5.1.0] - 2022-05-27
 
-### Changed
-
 - New function `stringifyParams` to stringify query parameters to a Sitevision compatible format.
 - Possible to pass a parameters object to `getRouteUri`.
 - All common constants and functions are now usable in hooks.
@@ -35,74 +35,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [5.0.0] - 2022-02-08
 
-### Changed
-
 - Using WebApps 2 for rendering apps.
-
-### Removed
-
-- `getAppData`, use `getAppProps` instead.
-- `server/render`, use `res.agnosticRender` for framework agnostic rendering.
-- `server/renderTemplate`, used for rendering underscore templates.
+- Removed `getAppData`, use `getAppProps` instead.
+- Removed `server/render`, use `res.agnosticRender` for framework agnostic rendering.
+- Removed `server/renderTemplate`, used for rendering underscore templates.
 
 ## [4.2.1] - 2021-09-06
 
-### Fixed
-
 - Underscore is misspelled in `renderTemplate`.
 
 ## [4.2.0] - 2021-08-20
 
-### Added
-
-- `getAppProps` for getting props passed to the app when rendering.
-
-### Changed
-
+- Added `getAppProps` for getting props passed to the app when rendering.
 - `getAppData` deprecated due to confusion, use `getAppProps` instead.
 
 ## [4.1.4] - 2021-05-25
 
-### Fixed
-
 - Return empty object instead of undefined when app data isn't set.
-
-### Removed
-
 - Remove `vue` as optional dependency.
 
 ## [4.1.3] - 2021-03-31
 
-### Fixed
-
 - Consistent rendering when using `serverServer` and `render` for Svelte.
-
-### Added
-
 - Docs for Svelte `renderServer` function.
 
 ## [4.1.2] - 2021-02-24
 
-### Fixed
-
 - Escape tags when parsing data to prevent closure of script tags.
 
 ## [4.1.1] - 2021-02-17
 
-### Fixed
-
 - Validation error for `id` on script tags, even though it's allowed.
 
 ## [4.1.0] - 2021-02-17
 
-### Changed
-
 - Put app data and metadata in script elements instead of data attributes.
 
 ## [4.0.1] - 2021-01-28
 
-### Fixed
-
 - Crashes when no data is passed to app and then trying to call `getAppData`.
 
 ## [4.0.0] - 2021-01-27
@@ -110,17 +80,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 A much needed major overhaul of the package.
 See [MIGRATION](./MIGRATION.md).
 
-### Changed
-
 - Major refactoring of package.
 - Exports for render functions are moved.
 - All documented constants and functions from base import (`@soleil-api/webapp-util`) now works both in a server and client context.
 - Settings for selector is moved from server to client rendering functions.
-
-### Removed
-
-- `noScript` option in `render` (formerly `renderApp`) has been removed. If a no script message is needed use the `html` option wrapped in `<noscript>`.
-- `@soleil-api/webapp-util/app-data` has been removed, use [getAppData](./README.md#getAppData) from `@soleil-api/webapp-util`.
+- Removed `noScript` option in `render` (formerly `renderApp`) has been removed. If a no script message is needed use the `html` option wrapped in `<noscript>`.
+- Removed `@soleil-api/webapp-util/app-data` has been removed, use [getAppData](./README.md#getAppData) from `@soleil-api/webapp-util`.
 
 ## [3.0.3] - 2020-11-03
 
@@ -132,86 +97,56 @@ See [MIGRATION](./MIGRATION.md).
 
 ## [3.0.1] - 2020-09-28
 
-### Added
-
 - Homepage link
 
 ## [3.0.0] - 2020-09-28
 
-### Added
-
 - Svelte support.
 - New exports:
   - `uniqueId` - A unique id for the app instance.
 
 ## [2.4.1] - 2020-09-01
 
-### Fixed
-
 - App data with single quotes crashes app in edit mode, use double quotes instead.
 
 ## [2.4.0] - 2020-05-26
 
-### Fixed
-
 - `getViewUri` returns correct URI when in offline mode and in the Addons view.
 
 ## [2.3.0] - 2020-05-22
 
-### Added
-
 - `renderApp` now accepts `req` as a setting to opimize script loading when multiple instances of the app exists. If `req` is present the script will only be loaded once in all browsers except IE11 that needs a unique script src for the currentScript polyfill to work.
-
-### Fixed
-
 - `noScript` in `renderApp` was not wrapped in a `<noscript>` tag.
 
 ## [2.2.0] - 2020-05-20
 
-### Added
-
 - `renderTemplate` function is now available inside templates rendered by the function.
 
 ## [2.1.4] - 2020-04-07
 
-### Fixed
-
 - `getViewUri` had incorrect portlet ID.
 
 ## [2.1.3] - 2020-02-25
 
-### Fixed
-
 - Add timestamp to script url in edit mode as well.
 
 ## [2.1.2] - 2020-02-21
 
-### Fixed
-
 - Wrapped `renderApp` script in svDocReady in edit mode to be sure it executes when other bundles are loaded.
 
 ## [2.1.1] - 2020-02-14
 
-### Changed
-
 - Updated readme, heading levels and examples.
 
 ## [2.1.0] - 2020-02-14
 
-### Added
-
 - App data import in client, `@soleil-api/webapp-util/app-data`.
 - `getViewUri` to get the URI that also renders the page.
 - `isOnline` to see if the app is online.
-
-### Changed
-
 - `vue` is now an optional depedency.  
 
 ## [2.0.0] - 2020-02-12
 
-### Changed
-
 - Now using `currentScript` to reference the script element the app is running in to pass data when using `renderApp`.
 - `renderApp` is no longer using appName.
 - `render` is now called directly in `./app_src/client/index.js`.

package/README.md

@@ -52,7 +52,7 @@ Integrity check failed for "@soleil-se/webapp-util" (computed integrity doesn...
 Migrating from version 4?  
 See [MIGRATION](./MIGRATION.md).
 
-## API
+## Common
 
 All imports from base package are available both on the server and client.
 
@@ -180,7 +180,7 @@ Stringify an object to a query string compatible with Sitevision.
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
 | params | `Object` | | Object with parameters to stringify. |
-| [options] | `Object` | `{}` | Settings object. |
+| [options] | `Object` | `{}` | Options object. |
 | [options.addQueryPrefix] | `Boolean` | `false` | If a leading `?` should be added to the string. |
 
 ```js
@@ -210,6 +210,151 @@ const params = parseParams('?foo=bar&arr[]=1&arr[]=2');
 // { foo: 'bar', arr: [1, 2] }
 ```
 
+## Client
+
+Following API:s are available in a client context.
+
+### Fetch
+
+Fetch wrapper for calling app routes, rest-api or external resources.
+
+#### fetchJson() => `Promise<Object>`
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| uri | `String` | | URI for resource |
+| [options] | `Object` | `{}` | Options object, two custom options rest is standard [fetch options](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options) |
+| [options.params] | `Object` | `{}` | Object with parameters to be appended to the URI |
+| [options.retries] | `Number` | `0` | Number of retries if the request times out. |
+
+**Returns**: `Promise<Object>` - Promise containing parsed JSON-data.  
+**Throws** `Error` - Extended error object with custom properties for `status`, `aborted` and other JSON-data returned by the request.
+
+Most common usage is getting data from a route in the current app.
+
+```js
+import { fetchJson } from '@soleil-se/webapp-util/client';
+
+async function getItems() {
+  const params = { query: 'foo', start: 0, num: 10 };
+  const result = await fetchJson('/items', { params });
+  console.log(result);
+}
+```
+
+Posting form data.
+
+```js
+import { fetchJson } from '@soleil-se/webapp-util/client';
+
+async function postForm() {
+  const body = new FormData();
+  body.append('name', 'Foo');
+  body.append('mail', 'foo@bar.com');
+
+  const result = await fetchJson('/create', { method: 'POST', body }));
+  console.log(result);
+}
+```
+
+Specify number of retries if a request times out.
+
+```js
+import { fetchJson } from '@soleil-se/webapp-util/client';
+
+async function getItems() {
+  const params = { query: 'foo', start: 0, num: 10 };
+  const result = await fetchJson('/items', { params, retries: 5 });
+  console.log(result);
+}
+```
+
+Handle aborted requests called in rapid succession, for example searching when typing.
+
+```js
+import { fetchJson } from '@soleil-se/webapp-util/client';
+
+async function onInput() {
+  const params = { query: 'foo' };
+  try {
+    const result = await fetchJson('/search', { params });
+    console.log(result);
+  } catch(e) {
+    // Ignore aborts due to new search.
+    if(e.aborted) return;
+    // Handle error as usual.
+  }
+}
+```
+
+### URL Parameters
+
+Helper functions setting, getting, updating and clearing query parameters in the URL-field.
+
+#### getUrlParams() ⇒ `Object`
+
+Get parameters from the URL-field.
+
+**Returns**: `Object` - Parameters in URL-field.
+
+```js
+import { getUrlParams } from '@soleil-se/webapp-util/client';
+
+const params = getUrlParams();
+```
+
+#### getUrlParam() ⇒ `String|Array[String]`
+
+Get single parameter from the URL-field.
+
+**Returns**: `String|Array[String]` - Parameter value.
+
+```js
+import { getUrlParam } from '@soleil-se/webapp-util/client';
+
+const param = getUrlParam('name');
+```
+
+#### setUrlParams(params)
+
+Set parameters in the URL-field, overwriting other parameters.
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| params | `Object` | | Object with parameters to set in the URL-field. |
+
+```js
+import { setUrlParams } from '@soleil-se/webapp-util/client';
+
+setUrlParams({ foo: 'bar', arr: [1, 2] });
+```
+
+#### updateUrlParams(params)
+
+Update parameters in the URL-field, merging with existing parameters
+
+**Returns**: `String` - Stringified parameters.
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| params | `Object` | | Object with parameters to add to the URL-field. |
+
+```js
+import { updateUrlParams } from '@soleil-se/webapp-util/client';
+
+updateUrlParams({ foo: 'bar', arr: [1, 2] });
+```
+
+#### clearUrlParams()
+
+Clear parameters in the URL-field
+
+```js
+import { clearUrlParams } from '@soleil-se/webapp-util/client';
+
+clearUrlParams();
+```
+
 ## Rendering
 
 * [Svelte](./docs/1.svelte.md)

package/client/fetch-json/index.js

@@ -0,0 +1,48 @@
+import { getRouteUri, stringifyParams } from '../../common';
+
+function getUrl(uri, params) {
+  if (uri.startsWith('/rest-api') || uri.startsWith('/appresource') || !uri.startsWith('/')) {
+    return uri + stringifyParams(params, { addQueryPrefix: true });
+  }
+  return getRouteUri(uri, params);
+}
+
+function toJson(response) {
+  try {
+    return response.json();
+  } catch (e) {
+    return {};
+  }
+}
+
+async function handleResponse(response) {
+  const json = await toJson(response);
+  if (!response.ok) {
+    const error = new Error(json?.message || response?.statusText);
+    Object.entries(json).forEach(([key, value]) => {
+      error[key] = value;
+    });
+    error.status = response.status;
+    throw error;
+  }
+
+  return json;
+}
+
+const controllers = {};
+
+export default function fetchJson(uri, { params = {}, retries = 0, ...options } = {}) {
+  if (controllers[uri]) controllers[uri].abort();
+  controllers[uri] = new AbortController();
+  return fetch(getUrl(uri, params), { signal: controllers[uri].signal, ...options })
+    .then(handleResponse)
+    .catch((error) => {
+      const isTimeout = error.status === 504 || error.status === 408 || error.message.includes('SocketTimeoutException');
+      if (isTimeout && retries > 0) {
+        return fetchJson(uri, { ...options, params, retries: retries - 1 });
+      }
+      // eslint-disable-next-line no-param-reassign
+      error.aborted = error.name === 'AbortError';
+      return Promise.reject(error);
+    });
+}

package/client/index.js

@@ -0,0 +1,9 @@
+export {
+  getUrlParam,
+  getUrlParams,
+  setUrlParams,
+  updateUrlParams,
+  clearUrlParams,
+} from './url-params';
+
+export { default as fetchJson } from './fetch-json';

package/client/url-params/index.js

@@ -0,0 +1,52 @@
+import { stringifyParams, parseParams } from '../../common';
+
+const isEmpty = (obj) => Object.keys(obj).length === 0 && obj.constructor === Object;
+
+/**
+ * Set query parameters in the url-field.
+ * @param {Object} obj - Values to be set.
+ * @param {Object} [options] Optional options.
+ * @param {Boolean} [options.scoped = false] If parameter keys should be scoped to current app.
+ */
+export function setUrlParams(params) {
+  window.history.replaceState({}, '', (isEmpty(params) ? window.location.pathname : `?${stringifyParams(params)}`));
+}
+
+/**
+ * Get query parameter from the url-field.
+ */
+export function getUrlParam(key) {
+  const params = parseParams(window.location.search.substring(1));
+  return params[key];
+}
+
+/**
+ * Get query parameters from the url-field.
+ */
+export function getUrlParams() {
+  const params = parseParams(window.location.search.substring(1));
+  return params;
+}
+
+/**
+ * Clear query parameters in the url-field.
+ */
+export function clearUrlParams() {
+  window.history.replaceState({}, '', window.location.pathname);
+}
+
+/**
+ * Updates query parameters in the url-field.
+ * @param {Object} params - Values to be updated.
+ */
+export function updateUrlParams(params) {
+  setUrlParams(Object.assign(getUrlParams(), params));
+}
+
+export default {
+  getUrlParam,
+  setUrlParams,
+  getUrlParams,
+  clearUrlParams,
+  updateUrlParams,
+};

package/common/index.js

@@ -1,4 +1,3 @@
-/* global document console */
 /* eslint-disable global-require */
 import router from '@sitevision/api/common/router';
 import app from '@sitevision/api/common/app';
@@ -116,7 +115,7 @@ export function parseParams(url = '') {
  * @param {object} params Query parameters.
  * @returns {string} URI for route.
  */
-export function getRouteUri(route = '', params) {
+export function getRouteUri(route = '', params = undefined) {
   const path = route.replace(leadingSlashes, '');
   const qs = stringifyParams(params, { addQueryPrefix: true });
   if (router?.getStandaloneUrl) {
@@ -133,13 +132,13 @@ export function getRouteUri(route = '', params) {
  * @param {string} route A route.
  * @returns {string} URI for view.
  */
-export function getViewUri(route = '', query) {
+export function getViewUri(route = '', params = undefined) {
   if (!router?.getUrl) {
     console.warn('[@soleil-api/webapp-util] getViewUri requires router.getUrl support.');
     return undefined;
   }
 
-  return router.getUrl(route, query);
+  return router.getUrl(route, params);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soleil-se/app-util",
-  "version": "5.2.2",
+  "version": "5.4.0",
   "description": "Utility and rendering functions for WebApps.",
   "main": "./common/index.js",
   "author": "Soleil AB",
@@ -14,6 +14,6 @@
   "peerDependencies": {
     "@sitevision/api": "*"
   },
-  "gitHead": "53b207511538040495c560637273434daff093fa",
+  "gitHead": "b590af917fa521db8bdb7e6f97bd35dffa50a0de",
   "dependencies": {}
 }

package/client/.eslintrc.js

@@ -1,4 +0,0 @@
-module.exports = {
-  extends: '@soleil/eslint-config-sitevision/client',
-  root: true,
-};

package/docs/2.vue.md

@@ -1,57 +0,0 @@
-# Vue (DEPRECATED)
-
-Sitevision only supports client side rendering with Vue.
-
-## index.js
-
-Render an app with only client code.
-`index.js`
-
-```javascript
-import router from '@sitevision/api/common/router';
-
-router.get('/', (req, res) => {
-  const props = { foo: 'bar' };
-  res.agnosticRender('', props)
-});
-```
-
-## main.js
-
-### `render(App, { target, props })`
-
-`@soleil-api/webapp-util/client/vue`
-
-Renders a client side Vue application.
-
-**Returns**: <code>\*</code> - Initialized Vue app.
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| App | <code>\*</code> |  | Svelte app root component. |
-| [settings] | <code>Object</code> | <code>{}</code> | Settings object. |
-| [settings.target] | <code>Element</code> | | Target where app should be mounted. |
-| [settings.props] | <code>Object</code> | | Root component props. |
-
-`main.js`
-
-```javascript
-import { render } from '@soleil-api/webapp-util/client/vue';
-import App from './App.vue';
-
-export default (props, target) => {
-  render(App, { props, target });
-};
-```
-
-Mount the app in another element:
-`main.js`
-
-```javascript
-import { render } from '@soleil-api/webapp-util/client/vue';
-import App from './App.vue';
-
-export default (props) => {
-  render(App, { props, target: document.querySelector('#mount_app_here') });
-};
-```