@appsemble/utils 0.21.2 → 0.22.0

package/README.md

@@ -1,9 +1,9 @@
-# ![](https://gitlab.com/appsemble/appsemble/-/raw/0.21.2/config/assets/logo.svg) Appsemble Utilities
+# ![](https://gitlab.com/appsemble/appsemble/-/raw/0.22.0/config/assets/logo.svg) Appsemble Utilities
 
 > Internal utility functions used across multiple Appsemble projects.
 
 [![npm](https://img.shields.io/npm/v/@appsemble/utils)](https://www.npmjs.com/package/@appsemble/utils)
-[![GitLab CI](https://gitlab.com/appsemble/appsemble/badges/0.21.2/pipeline.svg)](https://gitlab.com/appsemble/appsemble/-/releases/0.21.2)
+[![GitLab CI](https://gitlab.com/appsemble/appsemble/badges/0.22.0/pipeline.svg)](https://gitlab.com/appsemble/appsemble/-/releases/0.22.0)
 [![Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://prettier.io)
 
 ## Table of Contents
@@ -26,5 +26,5 @@ not guaranteed.
 
 ## License
 
-[LGPL-3.0-only](https://gitlab.com/appsemble/appsemble/-/blob/0.21.2/LICENSE.md) ©
+[LGPL-3.0-only](https://gitlab.com/appsemble/appsemble/-/blob/0.22.0/LICENSE.md) ©
 [Appsemble](https://appsemble.com)

package/api/components/schemas/ActionDefinition.js

@@ -72,6 +72,7 @@ export const ActionDefinition = {
                 { $ref: '#/components/schemas/TeamMembersActionDefinition' },
                 { $ref: '#/components/schemas/ThrowActionDefinition' },
                 { $ref: '#/components/schemas/UserLoginActionDefinition' },
+                { $ref: '#/components/schemas/UserLogoutActionDefinition' },
                 { $ref: '#/components/schemas/UserRegisterActionDefinition' },
                 { $ref: '#/components/schemas/UserUpdateActionDefinition' },
             ],

package/api/components/schemas/Asset.js

@@ -1,7 +1,7 @@
 import { normalized } from '../../../constants/index.js';
 export const Asset = {
     type: 'object',
-    description: 'The response object of an asset create call.',
+    description: 'The response object of an asset publish call.',
     additionalProperties: false,
     properties: {
         id: {

package/api/components/schemas/ResourceDefinition.js

@@ -61,6 +61,7 @@ name of the resource and how it should behave.
                 properties: {
                     resource: { type: 'string' },
                     create: referenceAction,
+                    patch: referenceAction,
                     update: referenceAction,
                     delete: referenceAction,
                 },
@@ -171,6 +172,28 @@ name of the resource and how it should behave.
                 },
             },
         },
+        patch: {
+            type: 'object',
+            description: "Overrides for 'patch' requests.",
+            additionalProperties: false,
+            properties: {
+                roles,
+                query,
+                method: {
+                    type: 'string',
+                    default: 'PATCH',
+                    description: 'HTTP method to use for this type of request.',
+                },
+                url: {
+                    type: 'string',
+                    default: '/api/apps/{appId}/{resource}/{id}',
+                    description: 'URL to use for this type of request.',
+                },
+                hooks: {
+                    $ref: '#/components/schemas/ResourceHooksDefinition',
+                },
+            },
+        },
         update: {
             type: 'object',
             description: "Overrides for 'update' requests.",

package/api/components/schemas/UserLogoutActionDefinition.d.ts

@@ -0,0 +1 @@
+export declare const UserLogoutActionDefinition: import("openapi-types").OpenAPIV3.SchemaObject;

package/api/components/schemas/UserLogoutActionDefinition.js

@@ -0,0 +1,14 @@
+import { BaseActionDefinition } from './BaseActionDefinition.js';
+import { extendJSONSchema } from './utils.js';
+export const UserLogoutActionDefinition = extendJSONSchema(BaseActionDefinition, {
+    type: 'object',
+    additionalProperties: false,
+    required: ['type'],
+    properties: {
+        type: {
+            enum: ['user.logout'],
+            description: 'Allow the users to logout of the application.',
+        },
+    },
+});
+//# sourceMappingURL=UserLogoutActionDefinition.js.map

package/api/components/schemas/index.d.ts

@@ -112,6 +112,7 @@ export * from './Theme.js';
 export * from './ThrowActionDefinition.js';
 export * from './User.js';
 export * from './UserEmail.js';
+export * from './UserLogoutActionDefinition.js';
 export * from './UserLoginActionDefinition.js';
 export * from './UserRegisterActionDefinition.js';
 export * from './UserUpdateActionDefinition.js';

package/api/components/schemas/index.js

@@ -112,6 +112,7 @@ export * from './Theme.js';
 export * from './ThrowActionDefinition.js';
 export * from './User.js';
 export * from './UserEmail.js';
+export * from './UserLogoutActionDefinition.js';
 export * from './UserLoginActionDefinition.js';
 export * from './UserRegisterActionDefinition.js';
 export * from './UserUpdateActionDefinition.js';

package/api/components/securitySchemes/cli.js

@@ -11,6 +11,7 @@ export const cli = {
             scopes: {
                 'apps:write': 'Create and update apps',
                 'blocks:write': 'Register and update blocks, and publish new block versions.',
+                'blocks:delete': 'Delete specific block versions.',
                 'organizations:write': 'Create and manage organizations.',
                 'resources:read': 'Read app resources on behalf of a user.',
                 'resources:write': 'Modify app resources on behalf of a user.',

package/api/paths/appQuotas.d.ts

@@ -0,0 +1,2 @@
+import { type OpenAPIV3 } from 'openapi-types';
+export declare const paths: OpenAPIV3.PathsObject;

package/api/paths/appQuotas.js

@@ -0,0 +1,38 @@
+export const paths = {
+    '/api/apps/{appId}/quotas/email': {
+        get: {
+            tags: ['app'],
+            operationId: 'getAppEmailQuota',
+            parameters: [{ $ref: '#/components/parameters/appId' }],
+            security: [{ studio: [] }, {}],
+            responses: {
+                200: {
+                    description: 'Email quota for an app',
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                properties: {
+                                    used: {
+                                        type: 'number',
+                                        description: 'Number of emails sent today',
+                                    },
+                                    limit: {
+                                        type: 'number',
+                                        description: 'Maximum number of emails that can be sent today',
+                                    },
+                                    reset: {
+                                        type: 'string',
+                                        format: 'date-time',
+                                        description: 'Date and time when the quota resets',
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};
+//# sourceMappingURL=appQuotas.js.map

package/api/paths/blocks.js

@@ -102,6 +102,17 @@ export const paths = {
                 },
             },
         },
+        delete: {
+            tags: ['block', 'delete'],
+            description: 'Delete a single block version.',
+            operationId: 'removeBlockVersion',
+            responses: {
+                204: {
+                    description: 'Block version has successfully been deleted',
+                },
+            },
+            security: [{ cli: ['blocks:delete'] }],
+        },
     },
     '/api/blocks/@{organizationId}/{blockId}/versions/{blockVersion}/asset': {
         parameters: [

package/api/paths/index.js

@@ -1,6 +1,7 @@
 import { paths as action } from './action.js';
 import { paths as translations } from './appMessages.js';
 import { paths as appOAuth2Secrets } from './appOAuth2Secrets.js';
+import { paths as appQuotas } from './appQuotas.js';
 import { paths as apps } from './apps.js';
 import { paths as appSamlSecrets } from './appSamlSecrets.js';
 import { paths as scimEndpoints } from './appScimEndpoints.js';
@@ -30,6 +31,7 @@ export const paths = {
     ...scimEndpoints,
     ...appsembleMessages,
     ...appSSLSecrets,
+    ...appQuotas,
     ...assets,
     ...blocks,
     ...emails,

package/api/paths/organizations.js

@@ -125,6 +125,17 @@ export const paths = {
             },
             security: [{ studio: [] }, { cli: ['organizations:write'] }],
         },
+        delete: {
+            tags: ['organization'],
+            description: 'Delete an organization.',
+            operationId: 'deleteOrganization',
+            responses: {
+                200: {
+                    description: 'successfully deleted organization',
+                },
+            },
+            security: [{ studio: [] }, {}],
+        },
     },
     '/api/organizations/{organizationId}/icon': {
         parameters: [{ $ref: '#/components/parameters/organizationId' }],

package/api/paths/user.js

@@ -476,5 +476,44 @@ export const paths = {
             },
         },
     },
+    '/api/subscribed': {
+        get: {
+            tags: ['user'],
+            description: 'Get a list of active and verified users subscribed to the appsemble newsletter',
+            operationId: 'getSubscribedUsers',
+            responses: {
+                200: { description: 'List of subscribed users' },
+                401: { description: 'Invalid or missing admin API secret' },
+            },
+        },
+    },
+    '/api/unsubscribe': {
+        post: {
+            tags: ['user'],
+            description: 'Unsubscribe a user from the newsletter',
+            operationId: 'unsubscribe',
+            responses: {
+                201: { description: 'Unsubscribed successfully' },
+                401: { description: 'Invalid or missing admin API secret' },
+            },
+            requestBody: {
+                required: true,
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            required: ['email'],
+                            properties: {
+                                email: {
+                                    type: 'string',
+                                    format: 'email',
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
 };
 //# sourceMappingURL=user.js.map

package/constants/Permission.d.ts

@@ -26,53 +26,61 @@ export declare enum Permission {
      * The permission to edit the name and logo of an organization.
      */
     EditOrganization = 5,
+    /**
+     * The permission to delete an organization if it doesn't have any apps.
+     */
+    DeleteOrganization = 6,
     /**
      * The permission to invite new members into an organization,
      * removing existing invites, and resending invites.
      */
-    InviteMember = 6,
+    InviteMember = 7,
     /**
      * The permission to create and delete assets.
      */
-    ManageAssets = 7,
+    ManageAssets = 8,
     /**
      * The permission to remove organization members.
      */
-    ManageMembers = 8,
+    ManageMembers = 9,
     /**
      * The permission to create, edit, and delete resources.
      */
-    ManageResources = 9,
+    ManageResources = 10,
     /**
      * The permission to change the roles of organization members.
      */
-    ManageRoles = 10,
+    ManageRoles = 11,
     /**
      * The permission to create and delete teams and manage its members.
      */
-    ManageTeams = 11,
+    ManageTeams = 12,
     /**
      * The permission to publish blocks for an organization.
      */
-    PublishBlocks = 12,
+    PublishBlocks = 13,
+    /**
+     * The permission to delete blocks for an organization.
+     */
+    DeleteBlocks = 14,
     /**
      * The permission to send manual push notifications for an app.
      */
-    PushNotifications = 13,
+    PushNotifications = 15,
     /**
      * The permission to read assets.
      */
-    ReadAssets = 14,
+    ReadAssets = 16,
     /**
      * The permission to read resources.
      */
-    ReadResources = 15,
+    ReadResources = 17,
     /**
      * The permission to view private apps of an organization.
      */
-    ViewApps = 16,
+    ViewApps = 18,
     /**
      * The permission to view the list of members in an organization.
      */
-    ViewMembers = 17
+    ViewMembers = 19
 }

package/constants/Permission.js

@@ -27,54 +27,62 @@ export var Permission;
      * The permission to edit the name and logo of an organization.
      */
     Permission[Permission["EditOrganization"] = 5] = "EditOrganization";
+    /**
+     * The permission to delete an organization if it doesn't have any apps.
+     */
+    Permission[Permission["DeleteOrganization"] = 6] = "DeleteOrganization";
     /**
      * The permission to invite new members into an organization,
      * removing existing invites, and resending invites.
      */
-    Permission[Permission["InviteMember"] = 6] = "InviteMember";
+    Permission[Permission["InviteMember"] = 7] = "InviteMember";
     /**
      * The permission to create and delete assets.
      */
-    Permission[Permission["ManageAssets"] = 7] = "ManageAssets";
+    Permission[Permission["ManageAssets"] = 8] = "ManageAssets";
     /**
      * The permission to remove organization members.
      */
-    Permission[Permission["ManageMembers"] = 8] = "ManageMembers";
+    Permission[Permission["ManageMembers"] = 9] = "ManageMembers";
     /**
      * The permission to create, edit, and delete resources.
      */
-    Permission[Permission["ManageResources"] = 9] = "ManageResources";
+    Permission[Permission["ManageResources"] = 10] = "ManageResources";
     /**
      * The permission to change the roles of organization members.
      */
-    Permission[Permission["ManageRoles"] = 10] = "ManageRoles";
+    Permission[Permission["ManageRoles"] = 11] = "ManageRoles";
     /**
      * The permission to create and delete teams and manage its members.
      */
-    Permission[Permission["ManageTeams"] = 11] = "ManageTeams";
+    Permission[Permission["ManageTeams"] = 12] = "ManageTeams";
     /**
      * The permission to publish blocks for an organization.
      */
-    Permission[Permission["PublishBlocks"] = 12] = "PublishBlocks";
+    Permission[Permission["PublishBlocks"] = 13] = "PublishBlocks";
+    /**
+     * The permission to delete blocks for an organization.
+     */
+    Permission[Permission["DeleteBlocks"] = 14] = "DeleteBlocks";
     /**
      * The permission to send manual push notifications for an app.
      */
-    Permission[Permission["PushNotifications"] = 13] = "PushNotifications";
+    Permission[Permission["PushNotifications"] = 15] = "PushNotifications";
     /**
      * The permission to read assets.
      */
-    Permission[Permission["ReadAssets"] = 14] = "ReadAssets";
+    Permission[Permission["ReadAssets"] = 16] = "ReadAssets";
     /**
      * The permission to read resources.
      */
-    Permission[Permission["ReadResources"] = 15] = "ReadResources";
+    Permission[Permission["ReadResources"] = 17] = "ReadResources";
     /**
      * The permission to view private apps of an organization.
      */
-    Permission[Permission["ViewApps"] = 16] = "ViewApps";
+    Permission[Permission["ViewApps"] = 18] = "ViewApps";
     /**
      * The permission to view the list of members in an organization.
      */
-    Permission[Permission["ViewMembers"] = 17] = "ViewMembers";
+    Permission[Permission["ViewMembers"] = 19] = "ViewMembers";
 })(Permission || (Permission = {}));
 //# sourceMappingURL=Permission.js.map

package/constants/roles.js

@@ -21,10 +21,12 @@ const Maintainer = [
     Permission.InviteMember,
     Permission.ManageTeams,
     Permission.PublishBlocks,
+    Permission.DeleteBlocks,
 ];
 const Owner = [
     ...Maintainer,
     Permission.EditOrganization,
+    Permission.DeleteOrganization,
     Permission.ManageMembers,
     Permission.ManageRoles,
 ];

package/constants/scopes.d.ts

@@ -1,4 +1,4 @@
 /**
  * All known OAuth2 scopes for client credentials.
  */
-export declare const scopes: readonly ["apps:write", "blocks:write", "organizations:write", "resources:read", "resources:write", "assets:write", "teams:read", "teams:write"];
+export declare const scopes: readonly ["apps:write", "blocks:write", "blocks:delete", "organizations:write", "resources:read", "resources:write", "assets:write", "teams:read", "teams:write"];

package/constants/scopes.js

@@ -4,6 +4,7 @@
 export const scopes = [
     'apps:write',
     'blocks:write',
+    'blocks:delete',
     'organizations:write',
     'resources:read',
     'resources:write',

package/formatRequestAction.js

@@ -4,6 +4,7 @@ export function formatRequestAction({ method = 'GET', query, ...action }, data,
         url: String(remap(action.url, data, context)),
         headers: {},
         params: remap(query, data, context),
+        responseType: 'arraybuffer',
     };
 }
 //# sourceMappingURL=formatRequestAction.js.map

package/index.d.ts

@@ -23,5 +23,6 @@ export * from './string.js';
 export * from './theme.js';
 export * from './langmap.js';
 export * from './i18n.js';
+export * from './serverActions.js';
 export * from './validation.js';
 export * from './convertToCsv.js';

package/index.js

@@ -23,6 +23,7 @@ export * from './string.js';
 export * from './theme.js';
 export * from './langmap.js';
 export * from './i18n.js';
+export * from './serverActions.js';
 export * from './validation.js';
 export * from './convertToCsv.js';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appsemble/utils",
-  "version": "0.21.2",
+  "version": "0.22.0",
   "description": "Utility functions used in Appsemble internally",
   "keywords": [
     "app",
@@ -21,6 +21,12 @@
   "author": "Appsemble <info@appsemble.com> (https://appsemble.com)",
   "sideEffects": false,
   "type": "module",
+  "exports": {
+    ".": [
+      "./index.js",
+      "./index.ts"
+    ]
+  },
   "files": [
     "**/*.d.ts",
     "**/*.js",
@@ -31,7 +37,7 @@
     "test": "vitest"
   },
   "dependencies": {
-    "@appsemble/types": "0.21.2",
+    "@appsemble/types": "0.22.0",
     "axios": "^1.0.0",
     "cron-parser": "^4.0.0",
     "date-fns": "^2.0.0",

package/reference-schemas/remappers/conditionals.js

@@ -3,7 +3,28 @@ export const conditionalRemappers = {
         type: 'object',
         description: `Check if condition results in a truthy value.
 
-Returns value of then if condition is truthy, otherwise it returns the value of else.
+Returns value of \`then\` if condition is truthy, otherwise it returns the value of \`else\`.
+
+For example:
+
+\`\`\`yaml
+if:
+  condition: { equals: [{ prop: inputValue }, 4] }
+  then:
+    static: You guessed right!
+  else:
+    static: You guessed wrong!
+\`\`\`
+
+If the \`inputValue\` is \`4\`, it goes to the \`then\` remapper and returns:
+\`\`\`
+You guessed right!
+\`\`\`
+
+If the \`inputValue\` is something other than \`4\`, it goes to the \`else\` remapper and returns:
+\`\`\`
+You guessed wrong!
+\`\`\`
 `,
         additionalProperties: false,
         required: ['condition', 'then', 'else'],
@@ -30,13 +51,35 @@ Returns value of then if condition is truthy, otherwise it returns the value of
         description: `Compare all computed remapper values against each other.
 
 Returns \`true\` if all entries are equal, otherwise \`false\`.
+
+In the following example, if the \`inputValue\` and \`expectedValue\` are of the same value, the
+condition will return \`true\` and the \`then\` remapper will fire.
+
+\`\`\`yaml
+condition:
+  equals:
+    - prop: inputValue
+    - prop: expectedValue
+\`\`\`
 `,
     },
     gt: {
         type: 'array',
-        description: `Compare the first computed remapper value with the second computed remapper value.
+        description: `**(gt = Greater than)**
+
+Compare the first computed remapper value with the second computed remapper value.
+
+Returns \`true\` if the first entry is greater than the second entry.
+
+For example, if \`stock\` is more than 5 here, it returns \`true\`.
 
-Returns \`true\` if the first entry is greater than the second entry.`,
+\`\`\`yaml
+condition:
+  gt:
+    - prop: stock
+    - 5
+\`\`\`
+`,
         minItems: 2,
         maxItems: 2,
         items: {
@@ -45,9 +88,21 @@ Returns \`true\` if the first entry is greater than the second entry.`,
     },
     lt: {
         type: 'array',
-        description: `Compare the first computed remapper value with the second computed remapper value.
+        description: `**(lt = Lesser than)
+
+Compare the first computed remapper value with the second computed remapper value.
+
+Returns \`true\` if the first entry is lesser than the second entry.
 
-Returns \`true\` if the first entry is lesser than the second entry.`,
+For example, if \`stock\` is less than 5 here, it returns \`true\`.
+
+\`\`\`yaml
+condition:
+  lt:
+    - prop: stock
+    - 5
+\`\`\`
+`,
         minItems: 2,
         maxItems: 2,
         items: {
@@ -64,6 +119,15 @@ Returns \`true\` if the first entry is lesser than the second entry.`,
 Returns \`false\` if all entries are equal to the first entry, otherwise \`true\`.
 
 If only one remapper or none is passed, the remapper value gets computed and then inverted.
+
+If \`number\` in the following example is something other than 4, the condition returns \`true\`.
+
+\`\`\`yaml
+condition:
+  not:
+    - prop: number
+    - 4
+\`\`\`
 `,
     },
     match: {
@@ -71,6 +135,21 @@ If only one remapper or none is passed, the remapper value gets computed and the
         description: `Check if any case results in a truthy value.
 
 Returns the value of the first case where the condition equals true, otherwise returns null.
+
+In the following example, let's say the \`Gem\` is a "Ruby". The match remapper then returns
+\`value: 75\`.
+
+\`\`\`yaml
+match:
+  - case: { equals: [{ prop: Gem }, Diamond] }
+    value: 100
+  - case: { equals: [{ prop: Gem }, Ruby] }
+    value: 75
+  - case: { equals: [{ prop: Gem }, Gold] }
+    value: 50
+  - case: { equals: [{ prop: Gem }, Sapphire] }
+    value: 25
+\`\`\`
 `,
         items: {
             type: 'object',

package/reference-schemas/remappers/data.js

@@ -4,6 +4,40 @@ export const dataRemappers = {
         description: `Get the current array.map’s index or length.
 
 Returns nothing when not in the context of \`array.map’s\`.
+
+For example:
+
+Input:
+\`\`\`json
+["a", "b", "c"]
+\`\`\`
+
+This remapper definition maps through the input array and creates an object with the length of the
+array and the current index of the loop:
+\`\`\`yaml
+array.map:
+  object.from:
+    length: { array: length }
+    index: { array: index }
+\`\`\`
+
+Result:
+\`\`\`json
+[
+  {
+    "index": 0,
+    "length": 3
+  },
+  {
+    "index": 1,
+    "length": 3
+  },
+  {
+    "index": 2,
+    "length": 3
+  }
+]
+\`\`\`
 `,
     },
     app: {
@@ -260,7 +294,18 @@ Result:
     `,
     },
     static: {
-        description: 'Use a static value.',
+        description: `Create a static value
+
+\`\`\`yaml
+static: Hello!
+\`\`\`
+
+Returns the following string:
+
+\`\`\`
+Hello!
+\`\`\`
+`,
     },
     translate: {
         type: 'string',

package/reference-schemas/remappers/dates.js

@@ -1,15 +1,101 @@
 export const dateRemappers = {
     'date.add': {
         type: 'string',
-        description: 'Add the specified value to a given date.',
+        description: `Adds a specified date value to the provided date.
+
+The value to add should be specified according to the
+[parse-duration](https://www.npmjs.com/package/parse-duration) API. If you want to add a day to a
+date for example, the syntax would be \`date.add: 1d\`.
+
+Full list of supported unit types:
+- nanoseconds (ns)
+- microseconds (μs)
+- milliseconds (ms)
+- seconds (s, sec)
+- minutes (m, min)
+- hours (h, hr)
+- days (d)
+- weeks (w, wk)
+- months
+- years (y, yr)
+
+For example:
+
+Date now:
+\`\`\`json
+2023-06-30T14:50:19.601Z
+\`\`\`
+
+Remapper definition:
+\`\`\`yaml
+[{ date.now: null }, { date.add: 1w } , { date.format: null }]
+\`\`\`
+
+Result:
+\`\`\`json
+2023-07-07T14:50:19.601Z
+\`\`\`
+
+`,
     },
     'date.format': {
-        enum: [null],
-        description: 'Format a date according to rfc3339.',
+        enum: ['string', null],
+        description: `Format a date according to the RFC3339 format.
+
+Here is an example of a RFC3339 complicit date:
+\`2002-10-02T15:00:00Z\`
+
+In an app definition, it’s best to use this when you want to display a date in a specific format.
+For example, if your app has a form with a Datepicker field the incoming data will be formatted
+as a simple date format. If you want to format it to the RFC3339 format, you can use this remapper.
+
+When you submit a form with a DateField, the internal output looks like this:
+
+\`\`\`js
+2023-07-03
+\`\`\`
+
+You can then format the date so that it uses the RFC3339 format.
+
+\`\`\`yaml
+date.format: null
+\`\`\`
+
+Result:
+\`\`\`js
+"2023-07-02T22:00:00.000Z"
+\`\`\`
+
+The remapper can also be used to format a date or timestamp using a custom format.
+
+\`\`\`js
+"2023-07-02T22:00:00.000Z"
+\`\`\`
+
+You can then format the date with any supported pattern, please refer to https://date-fns.org/docs/format for the supported patterns.
+
+\`\`\`yaml
+date.format: yyyy-MM-dd
+\`\`\`
+
+Result:
+\`\`\`js
+2023-07-03
+\`\`\`
+`,
     },
     'date.now': {
         enum: [null],
-        description: 'Returns the current date.',
+        description: `Returns the current date as a JavaScript Date object.
+\`\`\`yaml
+date.now: null
+\`\`\`
+
+Result:
+\`\`\`js
+"Mon Jul 03 2023 11:47:18 GMT+0200 (Midden-Europese zomertijd)"
+\`\`\`
+`,
     },
     'date.parse': {
         type: 'string',

package/reference-schemas/remappers/randoms.js

@@ -1,7 +1,27 @@
 export const randomRemappers = {
     'random.choice': {
         enum: [null],
-        description: 'Pick and return a random entry from an array. If the input is not an array, the input is returned as-is.',
+        description: `Pick and return a random entry from an array. If the input is not an array, the input is returned as-is.
+For example:
+
+If you input the following array:
+\`\`\`json
+[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+\`\`\`
+
+\`\`\`yaml
+random.choice: null
+\`\`\`
+
+The result could return any one of these numbers.
+
+You can also combine different data types in this array and have it work in the same way. If mixed in
+strings, the result could be either one of the provided numbers or one of the provided strings.
+
+\`\`\`json
+[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, "Peter", "Patrick", "Michael", "Harry"]
+\`\`\`
+`,
     },
     'random.integer': {
         type: 'array',
@@ -10,7 +30,16 @@ export const randomRemappers = {
         items: {
             type: 'integer',
         },
-        description: 'Pick and return a random integer between the provided lowest and highest values.',
+        description: `Pick and return a random integer between the provided lowest and highest values.
+For example:
+\`\`\`yaml
+random.integer:
+  - 0
+  - 1000
+\`\`\`
+
+Returns a random integer between 0 and 1000.
+`,
     },
     'random.float': {
         type: 'array',
@@ -19,7 +48,16 @@ export const randomRemappers = {
         items: {
             type: 'number',
         },
-        description: 'Pick and return a random number between the provided lowest and highest values.',
+        description: `Pick and return a random float value between the provided lowest and highest values.
+For example:
+\`\`\`yaml
+random.float:
+  - 0
+  - 1
+\`\`\`
+
+Returns a random float value between 0 and 1.
+`,
     },
     'random.string': {
         type: 'object',
@@ -29,7 +67,16 @@ export const randomRemappers = {
             choice: { type: 'string', minLength: 1 },
             length: { type: 'integer', minimum: 1 },
         },
-        description: 'Pick and return a random string from a given length using characters from a given input string.',
+        description: `Pick and return a random string from a given length using characters from a given input string defined in \`choice\`.
+For example:
+\`\`\`yaml
+random.string:
+  choice: abcdefghijklmnopqrstuvwxyz0123456789
+  length: 6
+\`\`\`
+
+Returns a randomized string that is 6 characters long and consists of any characters in the \`choice\` field, like: \`g8ajss9\`.
+`,
     },
 };
 //# sourceMappingURL=randoms.js.map

package/reference-schemas/remappers/unsorted.js

@@ -1,7 +1,47 @@
 export const unsortedRemappers = {
     ics: {
         type: 'object',
-        description: 'Create a calendar event',
+        description: `Create a calendar event. This event can be downloaded as an \`.ics\` file and
+uploaded to your agenda using the [download](../reference/action#download) action.
+
+For example, the following input:
+\`\`\`yaml
+ics:
+coordinates
+  object.from:
+    latitude: 38.897700545442646
+    longitude: -77.03655660152435
+description: "Sprint planning meeting"
+duration: 1d
+end: 2023-07-19
+location: The Oval Office.
+start: 2023-07-18
+title: Important Meeting
+url: https://google.nl
+\`\`\`
+
+Creates the following ICS-formatted object:
+\`\`\`
+BEGIN:VCALENDAR
+VERSION:2.0
+CALSCALE:GREGORIAN
+PRODID:http://remappers.appsemble.localhost:9999
+METHOD:PUBLISH
+X-PUBLISHED-TTL:PT1H
+BEGIN:VEVENT
+UID:b8TsbczhfpIxPM-3lNHQz
+SUMMARY:Important Meeting
+DTSTAMP:20230703T102029Z
+DTSTART:20230717T220000Z
+DTEND:20230718T220000Z
+DESCRIPTION:Sprint planning meeting
+URL:https://google.nl
+GEO:38.897700545442646;-77.03655123710632
+LOCATION:The Oval Office.
+END:VEVENT
+END:VCALENDAR
+\`\`\`
+`,
         additionalProperties: false,
         required: ['start', 'title'],
         properties: {
@@ -43,7 +83,51 @@ export const unsortedRemappers = {
         },
     },
     'null.strip': {
-        description: 'Strip all null, undefined, and empty array values from an object.',
+        description: `Strip all null, undefined, and empty array values from an object or array.
+For example, with the following input value:
+\`\`\`json
+[0, 4, null, null, "Peter", 0.4234, null]
+\`\`\`
+\`\`\`yaml
+null.strip: null
+\`\`\`
+
+The null values will be removed, leaving a dense array:
+\`\`\`json
+[0, 4, "Peter", 0.4234]
+\`\`\`
+
+Instead of giving it \`null\` as option, you can also provide a \`depth\` property to specify how
+deep to recurse into the object or array to remove null values.
+
+For example, with the following input:
+\`\`\`json
+{
+  0: [0, null, "Peter"],
+  1: {
+    "array1": [4, null, 0.4234, null]
+  }
+}
+\`\`\`
+
+You can specify to which degree of depth you want the null values to be removed.
+With this remapper definition:
+\`\`\`yaml
+null.strip:
+  depth: 2
+\`\`\`
+
+It will only check two objects in for any null values. That means only the first array within the
+object will be checked. The result looks like this:
+\`\`\`json
+{
+  0: [0, "Peter"],
+  1: {
+    "array1": [4, null, 0.4234, null]
+  }
+}
+\`\`\`
+`,
         anyOf: [
             { enum: [null] },
             {
@@ -63,9 +147,110 @@ export const unsortedRemappers = {
     },
     log: {
         enum: ['info', 'warn', 'error'],
-        description: `Logs its input data (returns it) and its context.
+        description: `Logs in the browser's console and returns the incoming data and the remapper function's context.
+
+The context contains relevant info about the app, like the URL and locale, but also contains the
+remapper’s history.
+
+The options represent the level of logging that will show in the console.
 
-The value to set is the log level.`,
+- \`input\`: The input data going into this remapper,
+- \`context\`:
+  - \`root\`: The input data going into this remapper,
+  - \`appId\`: ID of the application,
+  - \`url\`: Absolute URL of the page where the remapper was fired,
+  - \`appUrl\`: Base URL of the application,
+  - \`pageData\`: Current page data of a FlowPage (See [page remapper](./data#page)),
+  - \`userInfo\`: User's information if they are logged in (See [user remapper](./data#user)),
+  - \`context\`:
+    - \`history\`: Complete list of this remapper’s history (See [history remapper](./history))
+  - \`history\`: Complete list of this remapper’s history (See [history remapper](./history))
+  - \`locale\`: The user’s locale,
+  - \`stepRef\`: In a loop page, gives the properties from the loop’s current data index (See [step remapper](./data#step))
+
+For example:
+
+\`\`\`json
+{
+  "input": {
+    "name": "Peter",
+    "age": 49,
+    "birthday": "07-08-2023"
+  },
+  "context": {
+    "root": {
+      "name": "Peter",
+      "age": 49,
+      "birthday": "07-08-2023"
+    },
+    "appId": 49,
+    "url": "http://remappers.appsemble.localhost:9999/en/other",
+    "appUrl": "http://remappers.appsemble.localhost:9999",
+    "pageData": {
+      "triedAppsemble": false
+    },
+    "userInfo": {
+      "email": "example@hotmail.com",
+      "email_verified": true,
+      "name": "Example User 1",
+      "picture": "https://www.gravatar.com/avatar/f46b82357ce29bcd1099915946cda468?s=128&d=mp",
+      "sub": "0000-0000-0000-0000",
+      "locale": "en",
+      "zoneinfo": "Europe/Amsterdam"
+    },
+    "context": {
+      "history": [
+        [
+          0,
+          4,
+          null,
+          null,
+          "Peter",
+          0.4234,
+          null
+        ],
+        {
+          "name": "Peter",
+          "age": 49
+        },
+        {
+          "name": "Peter",
+          "age": 49,
+          "birthday": "07-08-2023"
+        }
+      ]
+    },
+    "history": [
+      [
+        0,
+        4,
+        null,
+        null,
+        "Peter",
+        0.4234,
+        null
+      ],
+      {
+        "name": "Peter",
+        "age": 49
+      },
+      {
+        "name": "Peter",
+        "age": 49,
+        "birthday": "07-08-2023"
+      }
+    ],
+    "locale": "en",
+    "stepRef": {
+      "current": {
+        "answerType": "multiple choice",
+        "question": "How much do you enjoy working here?"
+      }
+    }
+  }
+}
+\`\`\`
+`,
     },
 };
 //# sourceMappingURL=unsorted.js.map

package/remap.js

@@ -1,4 +1,4 @@
-import { addMilliseconds, parse, parseISO } from 'date-fns';
+import { addMilliseconds, format, parse, parseISO } from 'date-fns';
 import equal from 'fast-deep-equal';
 import { createEvent } from 'ics';
 import parseDuration from 'parse-duration';
@@ -233,7 +233,7 @@ const mapperImplementations = {
         }
         return result;
     },
-    'date.parse': (format, input) => format ? parse(input, format, new Date()) : parseISO(input),
+    'date.parse': (fmt, input) => (fmt ? parse(input, fmt, new Date()) : parseISO(input)),
     'date.now': () => new Date(),
     'date.add'(time, input) {
         const expireDuration = parseDuration(time);
@@ -248,7 +248,7 @@ const mapperImplementations = {
             : typeof input === 'number'
                 ? new Date(input)
                 : parseISO(String(input));
-        return date.toJSON();
+        return args ? format(date, args) : date.toJSON();
     },
     'null.strip': (args, input) => stripNullValues(input, args || {}),
     'random.choice': (args, input) => Array.isArray(input) ? input[Math.floor(Math.random() * input.length)] : input,

package/remap.test.js

@@ -183,6 +183,21 @@ describe('date.format', () => {
             mappers: { 'date.format': null },
             expected: '1970-01-01T00:00:00.000Z',
         },
+        'format date objects to custom format': {
+            input: new Date('2020-01-02T03:04:05Z'),
+            mappers: { 'date.format': 'dd-MM-yyyy' },
+            expected: '02-01-2020',
+        },
+        'format date strings to custom format': {
+            input: '2020-01-02T03:04:05Z',
+            mappers: { 'date.format': 'yyyy-MM-dd' },
+            expected: '2020-01-02',
+        },
+        'format unix timestamps to custom format': {
+            input: 0,
+            mappers: { 'date.format': 'MM/dd/yyyy' },
+            expected: '01/01/1970',
+        },
     });
 });
 describe('log', () => {

package/theme.test.js

@@ -1,4 +1,4 @@
-import bulmaPkg from 'bulma/package.json' assert { type: 'json' };
+import bulmaPkg from 'bulma/package.json';
 import { createThemeURL, mergeThemes } from './theme.js';
 describe('mergeThemes', () => {
     it('should use the base theme as default', () => {

package/vitest.config.d.ts

@@ -1,2 +0,0 @@
-declare const _default: import("vitest/dist/config.js").UserProjectConfigExport;
-export default _default;