@evoke-platform/context 1.1.0-dev.1 → 1.1.0-dev.3

package/README.md

@@ -36,6 +36,8 @@ const applications = useObject('application');
     -   [getInstanceHistory](#getinstancehistoryinstanceid)
     -   [newInstance](#newinstanceinput)
     -   [instanceAction](#instanceactioninput)
+    -   [invalidateCache](#invalidatecache)
+    -   [invalidateAllCache](#invalidateallcache-static)
 
 #### `useObject(objectId)`
 
@@ -67,15 +69,21 @@ applications.findInstances(callback);
 const results = await applications.findInstances();
 ```
 
+ObjectStore includes built-in caching for object definitions with a 30-second time-to-live (TTL). This improves performance by reducing API calls for frequently accessed objects.
+
 ##### `get(options)`
 
 Get the object definition for this store's object. The returned object includes inherited properties and actions if
-this object is derived from another object.
+this object is derived from another object. Results are cached for improved performance.
 
 -   `options` _[object]_ - _optional_
     -   `sanitized` _[boolean]_
         -   If `true`, returns a sanitized version of the object reflecting only the properties and actions available
             to the current user.
+    -   `bypassCache` _[boolean]_
+        -   If `true`, bypasses the cache and forces a new API call. The cache is still updated with the results of the new API call.
+    -   `skipAlphabetize` _[boolean]_
+        -   If `true`, preserves the original order of properties instead of alphabetizing them (properties are alphabetized by default).
 
 ##### `findInstances(filter)`
 
@@ -124,6 +132,14 @@ Performs an action on an existing instance.
     -   Action to be executed. The action must not be a create action.
 -   Returns updated instance.
 
+##### `invalidateCache()`
+
+Invalidates cached data for this specific object ID and all its option variants. Use this when you know the object definition has changed on the server.
+
+##### `invalidateAllCache()` (static)
+
+Static method that invalidates the entire object cache across all ObjectStore instances. Use this when you need to force fresh data for all objects.
+
 ### Page Context
 
 -   [usePageParam](#usepageparamparam)

package/dist/objects/objects.d.ts

@@ -133,14 +133,15 @@ export type SelectOption = {
     label: string;
     value: string;
 };
+export type VisibilityCondition = {
+    property: string;
+    operator: 'eq' | 'neq';
+    value: string | number | boolean;
+    isInstanceProperty?: boolean;
+};
 export type VisibilityConfiguration = {
     operator?: 'any' | 'all';
-    conditions?: {
-        property: string;
-        operator: 'eq' | 'neq';
-        value: string | number | boolean;
-        isInstanceProperty?: boolean;
-    }[];
+    conditions?: VisibilityCondition[];
 };
 export type RelatedObjectDefaultValue = {
     criteria: Record<string, unknown>;
@@ -148,6 +149,7 @@ export type RelatedObjectDefaultValue = {
     orderBy?: 'asc' | 'desc' | 'ASC' | 'DESC';
 };
 export type CriteriaDefaultValue = Record<string, unknown>;
+export type JsonLogic = Record<string, unknown> | boolean | number | string | null;
 export type DisplayConfiguration = {
     label?: string;
     placeholder?: string;
@@ -163,7 +165,7 @@ export type DisplayConfiguration = {
     charCount?: boolean;
     mode?: 'default' | 'existingOnly';
     relatedObjectDisplay?: 'dropdown' | 'dialogBox';
-    visibility?: VisibilityConfiguration | string;
+    visibility?: VisibilityConfiguration | JsonLogic;
     viewLayout?: ViewLayoutEntityReference;
     choicesDisplay?: {
         type: 'dropdown' | 'radioButton';
@@ -180,7 +182,7 @@ export type InputParameterReference = {
 export type Content = {
     type: 'content';
     html: string;
-    visibility?: VisibilityConfiguration | string;
+    visibility?: VisibilityConfiguration | JsonLogic;
 };
 export type Column = {
     width: number;
@@ -189,7 +191,7 @@ export type Column = {
 export type Columns = {
     type: 'columns';
     columns: Column[];
-    visibility?: VisibilityConfiguration | string;
+    visibility?: VisibilityConfiguration | JsonLogic;
 };
 export type Section = {
     label: string;
@@ -197,8 +199,9 @@ export type Section = {
 };
 export type Sections = {
     type: 'sections';
+    label?: string;
     sections: Section[];
-    visibility?: VisibilityConfiguration | string;
+    visibility?: VisibilityConfiguration | JsonLogic;
 };
 export type FormEntry = InputParameterReference | Columns | Sections | Content;
 export type Form = {
@@ -245,7 +248,7 @@ export type ActionInput = {
     input?: boolean;
     widget?: string;
     conditional?: {
-        json?: string;
+        json?: JsonLogic;
         show?: boolean;
         when?: string;
         eq?: string | number | boolean;
@@ -312,26 +315,89 @@ export type Reference = {
     name?: string;
 };
 export type ObjectOptions = {
+    /**
+     * When true, returns a sanitized version of the object reflecting
+     * only the properties and actions available to the current user.
+     */
     sanitized?: boolean;
+    /**
+     * When true, bypasses the cache and forces a new API call.
+     */
+    bypassCache?: boolean;
+    /**
+     * When true, preserves the original order of properties instead of
+     * alphabetizing them (properties are alphabetized by default).
+     */
+    skipAlphabetize?: boolean;
 };
+/**
+ * Provides methods for working with objects and their instances in Evoke.
+ * Supports retrieving object definitions, finding/retrieving instances,
+ * creating new instances, and performing actions on existing instances.
+ */
 export declare class ObjectStore {
     private services;
     private objectId;
+    private static cache;
     constructor(services: ApiServices, objectId: string);
+    private getCacheKey;
+    private processObject;
+    /**
+     * Invalidates cached data for this specific object ID and all its option variants.
+     * Use this when you know the object definition has changed on the server.
+     */
+    invalidateCache(): void;
+    /**
+     * Invalidates the entire object cache across all ObjectStore instances.
+     * Use this when you need to force fresh data for all objects.
+     */
+    static invalidateAllCache(): void;
+    /**
+     * Retrieves the object definition with inherited properties and actions.
+     * Results are cached with a 30-second TTL to reduce API calls for frequently accessed objects.
+     *
+     * By default, properties are alphabetized by name. Use options to customize behavior.
+     *
+     * @param options - Configuration options for object retrieval and processing
+     * @returns A promise resolving to the object with root
+     */
     get(options?: ObjectOptions): Promise<ObjWithRoot>;
     get(cb?: Callback<ObjWithRoot>): void;
     get(options: ObjectOptions, cb?: Callback<ObjWithRoot>): void;
+    /**
+     * Finds instances of the object that match the specified filter criteria.
+     */
     findInstances<T extends ObjectInstance = ObjectInstance>(filter?: Filter): Promise<T[]>;
     findInstances<T extends ObjectInstance = ObjectInstance>(cb: Callback<T[]>): void;
     findInstances<T extends ObjectInstance = ObjectInstance>(filter: Filter, cb: Callback<T[]>): void;
+    /**
+     * Retrieves a specific instance of the object by ID.
+     */
     getInstance<T extends ObjectInstance = ObjectInstance>(id: string): Promise<T>;
     getInstance<T extends ObjectInstance = ObjectInstance>(id: string, cb: Callback<T>): void;
+    /**
+     * Retrieves the history of an instance of the object.
+     */
     getInstanceHistory(id: string): Promise<History[]>;
     getInstanceHistory(id: string, cb: Callback<History[]>): void;
+    /**
+     * Creates a new instance of the object.
+     */
     newInstance<T extends ObjectInstance = ObjectInstance>(input: ActionRequest): Promise<T>;
     newInstance<T extends ObjectInstance = ObjectInstance>(input: ActionRequest, cb: Callback<T>): void;
+    /**
+     * Performs an action on an existing instance of the object.
+     */
     instanceAction<T extends ObjectInstance = ObjectInstance>(id: string, input: ActionRequest): Promise<T>;
     instanceAction<T extends ObjectInstance = ObjectInstance>(id: string, input: ActionRequest, cb: Callback<T>): void;
 }
+/**
+ * Creates an ObjectStore instance for the specified object.
+ * Provides access to object definitions and instance operations.
+ * Object definitions are cached for performance.
+ *
+ * @param objectId - ID of the object to access
+ * @returns ObjectStore instance
+ */
 export declare function useObject(objectId: string): ObjectStore;
 export {};

package/dist/objects/objects.js

@@ -1,12 +1,50 @@
 // Copyright (c) 2023 System Automation Corporation.
 // This file is licensed under the MIT License.
+import TTLCache from '@isaacs/ttlcache';
 import { useMemo } from 'react';
 import { useApiServices } from '../api/index.js';
+/**
+ * Provides methods for working with objects and their instances in Evoke.
+ * Supports retrieving object definitions, finding/retrieving instances,
+ * creating new instances, and performing actions on existing instances.
+ */
 export class ObjectStore {
     constructor(services, objectId) {
         this.services = services;
         this.objectId = objectId;
     }
+    getCacheKey(options) {
+        return `${this.objectId}:${(options === null || options === void 0 ? void 0 : options.sanitized) ? 'sanitized' : 'default'}:${(options === null || options === void 0 ? void 0 : options.skipAlphabetize) ? 'unsorted' : 'sorted'}`;
+    }
+    processObject(object, options) {
+        const result = Object.assign({}, object);
+        if (result.properties) {
+            // alphabetize properties by default unless disabled
+            if (!(options === null || options === void 0 ? void 0 : options.skipAlphabetize)) {
+                result.properties = [...result.properties].sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }));
+            }
+        }
+        return result;
+    }
+    /**
+     * Invalidates cached data for this specific object ID and all its option variants.
+     * Use this when you know the object definition has changed on the server.
+     */
+    invalidateCache() {
+        const prefix = `${this.objectId}:`;
+        for (const key of ObjectStore.cache.keys()) {
+            if (typeof key === 'string' && key.startsWith(prefix)) {
+                ObjectStore.cache.delete(key);
+            }
+        }
+    }
+    /**
+     * Invalidates the entire object cache across all ObjectStore instances.
+     * Use this when you need to force fresh data for all objects.
+     */
+    static invalidateAllCache() {
+        ObjectStore.cache.clear();
+    }
     get(optionsOrCallback, cb) {
         let options;
         if (cb) {
@@ -18,15 +56,33 @@ export class ObjectStore {
         else {
             options = optionsOrCallback;
         }
+        const cacheKey = this.getCacheKey(options);
+        if (!(options === null || options === void 0 ? void 0 : options.bypassCache)) {
+            const cachedPromise = ObjectStore.cache.get(cacheKey);
+            if (cachedPromise) {
+                if (cb) {
+                    const callback = cb;
+                    cachedPromise.then((data) => callback(null, data)).catch((err) => callback(err));
+                    return;
+                }
+                return cachedPromise;
+            }
+        }
         const config = {
             params: {
                 sanitizedVersion: options === null || options === void 0 ? void 0 : options.sanitized,
             },
         };
-        if (!cb) {
-            return this.services.get(`data/objects/${this.objectId}/effective`, config);
+        const promise = this.services
+            .get(`data/objects/${this.objectId}/effective`, config)
+            .then((result) => this.processObject(result, options));
+        ObjectStore.cache.set(cacheKey, promise);
+        if (cb) {
+            const callback = cb;
+            promise.then((data) => callback(null, data)).catch((err) => callback(err));
+            return;
         }
-        this.services.get(`data/objects/${this.objectId}/effective`, config, cb);
+        return promise;
     }
     findInstances(filterOrCallback, cb) {
         let filter;
@@ -74,6 +130,19 @@ export class ObjectStore {
         this.services.post(`data/objects/${this.objectId}/instances/${id}/actions`, input, cb);
     }
 }
+// Cache that stores in-flight promises
+// 30 second TTL for cached promises
+ObjectStore.cache = new TTLCache({
+    ttl: 30 * 1000,
+});
+/**
+ * Creates an ObjectStore instance for the specified object.
+ * Provides access to object definitions and instance operations.
+ * Object definitions are cached for performance.
+ *
+ * @param objectId - ID of the object to access
+ * @returns ObjectStore instance
+ */
 export function useObject(objectId) {
     const services = useApiServices();
     return useMemo(() => new ObjectStore(services, objectId), [services, objectId]);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@evoke-platform/context",
-    "version": "1.1.0-dev.1",
+    "version": "1.1.0-dev.3",
     "description": "Utilities that provide context to Evoke platform widgets",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -67,6 +67,7 @@
         "react-router-dom": ">=6"
     },
     "dependencies": {
+        "@isaacs/ttlcache": "^1.4.1",
         "@microsoft/signalr": "^7.0.12",
         "axios": "^1.7.9",
         "uuid": "^9.0.1"