@sasjs/adapter 4.2.3 → 4.3.0

package/README.md

@@ -153,6 +153,14 @@ The response object will contain returned tables and columns.  Table names are a
 
 The adapter will also cache the logs (if debug enabled) and even the work tables.  For performance, it is best to keep debug mode off.
 
+### Session Manager
+
+To execute a script on Viya a session has to be created first which is time-consuming (~15sec). That is why a Session Manager has been created which is implementing the following logic:
+
+1. When the first session is requested, we also create one more session (hot session) for future requests. Please notice two pending POST requests to create a session within the same context: ![the first session request](./screenshots/session-manager-first-request.png)
+2. When a subsequent request for a session is received and there is a hot session available (not expired), this session is returned and an asynchronous request to create another hot session is sent. Please notice that there is a pending POST request to create a new session while a job has been already finished execution (POST request with status 201): ![subsequent session request](./screenshots/subsequent-session-request.png)
+3. When a subsequent request for a session is received and there is no available hot session, 2 requests are sent asynchronously to create a session. The first created session will be returned and another session will be reserved for future requests.
+
 ### Variable Types
 
 The SAS type (char/numeric) of the values is determined according to a set of rules:

package/SessionManager.d.ts

@@ -8,18 +8,104 @@ export declare class SessionManager {
     constructor(serverUrl: string, contextName: string, requestClient: RequestClient);
     private sessions;
     private currentContext;
+    private settingContext;
     private _debug;
     private printedSessionState;
     get debug(): boolean;
     set debug(value: boolean);
-    getSession(accessToken?: string): Promise<Session | undefined>;
+    /**
+     * Checks if session is valid. Session is considered valid if time since it's creation is less than 'sessionInactiveTimeout' attribute.
+     * @param session - session object.
+     * @returns - boolean indicating if session is valid.
+     */
+    private isSessionValid;
+    /**
+     * Removes session from pool of hot sessions.
+     * @param session - session object.
+     * @returns - void.
+     */
+    private removeSessionFromPool;
+    /**
+     * Filters session pool to keep only valid sessions.
+     * @param session - session object.
+     * @returns - void.
+     */
+    private removeExpiredSessions;
+    /**
+     * Throws set of errors as a single error.
+     * @param errors - array of errors or string.
+     * @param prefix - an optional final error prefix.
+     * @returns - never.
+     */
+    private throwErrors;
+    /**
+     * Returns session.
+     * If there is a hot session available, it will be returned immediately and an asynchronous request to create new hot session will be submitted.
+     * If there is no available session, 2 session creation requests will be submitted. The session is returned once it is created and ready.
+     * @param accessToken - an optional access token.
+     * @returns - a promise which resolves with a session.
+     */
+    getSession(accessToken?: string): Promise<Session>;
+    /**
+     * Returns error message based on the response from SAS API.
+     * @param err - an optional access token.
+     * @param accessToken - an optional access token.
+     * @returns - an error message.
+     */
+    private getErrorMessage;
+    /**
+     * Deletes session.
+     * @param id - a session id.
+     * @param accessToken - an optional access token.
+     * @returns - a promise which resolves when session is deleted.
+     */
     clearSession(id: string, accessToken?: string): Promise<void>;
+    /**
+     * Creates sessions in amount equal to MAX_SESSION_COUNT.
+     * @param accessToken - an optional access token.
+     * @returns - a promise which resolves when required amount of sessions is created.
+     */
     private createSessions;
+    /**
+     * Waits for the current context to be set.
+     * @returns - a promise which resolves when current context is set.
+     */
+    private waitForCurrentContext;
+    /**
+     * Creates and waits for session to be ready.
+     * @param accessToken - an optional access token.
+     * @returns - a promise which resolves with a session.
+     */
     private createAndWaitForSession;
+    /**
+     * Sets current context.
+     * @param accessToken - an optional access token.
+     * @returns - a promise which resolves when current context is set.
+     */
     private setCurrentContext;
-    private getHeaders;
+    /**
+     * Waits for session to be ready.
+     * @param session - a session object.
+     * @param etag - an etag that can be a string or null.
+     * @param accessToken - an optional access token.
+     * @returns - a promise which resolves with a session state.
+     */
     private waitForSession;
+    /**
+     * Gets session state.
+     * @param url - a URL to get session state.
+     * @param etag - an etag string.
+     * @param accessToken - an optional access token.
+     * @returns - a promise which resolves with a result string and response status.
+     */
     private getSessionState;
+    /**
+     * Gets variable.
+     * @param sessionId - a session id.
+     * @param variable - a variable string.
+     * @param accessToken - an optional access token.
+     * @returns - a promise which resolves with a result that confirms to SessionVariable interface, etag string and status code.
+     */
     getVariable(sessionId: string, variable: string, accessToken?: string): Promise<{
         result: SessionVariable;
         etag: string;