@openstax/ts-utils 1.40.2 → 1.41.2

package/dist/esm/services/accountsGateway/index.d.ts

@@ -13,6 +13,7 @@ interface Initializer<C> {
 }
 export type FindUserPayload = ({
     external_id: string;
+    role?: string;
 } | {
     uuid: string;
 }) & {
@@ -45,10 +46,12 @@ export type FindUserResponse = (FindOrCreateUserResponse & {
 export type LinkUserPayload = {
     userId: number;
     externalId: string;
+    role?: string;
 };
 export type LinkUserResponse = {
     user_id: number;
     external_id: string;
+    role?: string;
 };
 export type SearchUsersPayload = {
     q: string;

package/dist/esm/services/accountsGateway/index.js

@@ -53,6 +53,7 @@ export const accountsGateway = (initializer) => (configProvider) => {
             body: {
                 external_id: body.externalId,
                 user_id: body.userId,
+                ...(body.role && { role: body.role }),
             }
         });
         const searchUsers = async (payload) => request(METHOD.GET, `users?${queryString.stringify(payload)}`, {});

package/dist/esm/services/documentStore/dynamoEncoding.js

@@ -12,7 +12,7 @@ export const encodeDynamoAttribute = (value) => {
     if (value === null) {
         return { NULL: true };
     }
-    if (value instanceof Array) {
+    if (Array.isArray(value)) {
         return { L: value.map(encodeDynamoAttribute) };
     }
     if (isPlainObject(value)) {
@@ -20,7 +20,7 @@ export const encodeDynamoAttribute = (value) => {
     }
     throw new Error(`unknown attribute type ${typeof value} with value ${value}.`);
 };
-export const encodeDynamoDocument = (base) => Object.fromEntries(Object.entries(base).map(([key, value]) => ([key, encodeDynamoAttribute(value)])));
+export const encodeDynamoDocument = (base) => Object.fromEntries(Object.entries(base).filter(([, value]) => value !== undefined).map(([key, value]) => ([key, encodeDynamoAttribute(value)])));
 export const decodeDynamoAttribute = (value) => {
     if (value.S !== undefined) {
         return value.S;

package/dist/esm/services/documentStore/unversioned/file-system.d.ts

@@ -8,7 +8,6 @@ interface Initializer<C> {
 export declare const fileSystemUnversionedDocumentStore: <C extends string = "fileSystem">(initializer: Initializer<C>) => <T extends TDocument<T>>() => (configProvider: { [_key in C]: ConfigProviderForConfig<Config>; }) => <K extends keyof T>(_: {}, hashKey: K, options?: {
     afterWrite?: (item: T) => void | Promise<void>;
     batchAfterWrite?: (items: T[]) => void | Promise<void>;
-    skipAssert?: boolean;
 }) => {
     loadAllDocumentsTheBadWay: () => Promise<T[]>;
     getItemsByField: (key: keyof T, value: T[K], pageKey?: string) => Promise<{

package/dist/esm/services/documentStore/unversioned/file-system.js

@@ -4,13 +4,10 @@ import { hashValue } from '../../..';
 import { resolveConfigValue } from '../../../config';
 import { ConflictError, NotFoundError } from '../../../errors';
 import { ifDefined, isDefined } from '../../../guards';
-import { assertNoUndefined } from '../fileSystemAssert';
 export const fileSystemUnversionedDocumentStore = (initializer) => () => (configProvider) => (_, hashKey, options) => {
-    var _a;
     const tableName = resolveConfigValue(configProvider[initializer.configSpace || 'fileSystem'].tableName);
     const tablePath = tableName.then((table) => path.join(initializer.dataDir, table));
     const { mkdir, readdir, readFile, writeFile } = ifDefined(initializer.fs, fsModule);
-    const skipAssert = (_a = options === null || options === void 0 ? void 0 : options.skipAssert) !== null && _a !== void 0 ? _a : false;
     const mkTableDir = new Promise((resolve, reject) => tablePath.then((path) => mkdir(path, { recursive: true }, (err) => err && err.code !== 'EEXIST' ? reject(err) : resolve())));
     const hashFilename = (value) => `${hashValue(value)}.json`;
     const filePath = async (filename) => path.join(await tablePath, filename);
@@ -45,8 +42,6 @@ export const fileSystemUnversionedDocumentStore = (initializer) => () => (config
     return {
         loadAllDocumentsTheBadWay,
         getItemsByField: async (key, value, pageKey) => {
-            if (!skipAssert)
-                assertNoUndefined(value, [key]);
             const pageSize = 10;
             const items = await loadAllDocumentsTheBadWay();
             const filteredItems = items.filter((item) => item[key] === value);
@@ -59,20 +54,14 @@ export const fileSystemUnversionedDocumentStore = (initializer) => () => (config
         },
         batchGetItem: async (ids) => {
             const items = await Promise.all(ids.map((id) => {
-                if (!skipAssert)
-                    assertNoUndefined(id, ['id']);
                 return load(hashFilename(id));
             }));
             return items.filter(isDefined);
         },
         getItem: (id) => {
-            if (!skipAssert)
-                assertNoUndefined(id, ['id']);
             return load(hashFilename(id));
         },
         incrementItemAttribute: async (id, attribute) => {
-            if (!skipAssert)
-                assertNoUndefined(id, ['id']);
             const filename = hashFilename(id);
             const path = await filePath(filename);
             await mkTableDir;
@@ -103,15 +92,11 @@ export const fileSystemUnversionedDocumentStore = (initializer) => () => (config
                 throw new NotFoundError(`Item with ${hashKey.toString()} "${id}" does not exist`);
             }
             const newItem = { ...data, ...item };
-            if (!skipAssert)
-                assertNoUndefined(newItem);
             return new Promise((resolve, reject) => {
                 writeFile(path, JSON.stringify(newItem, null, 2), (err) => err ? reject(err) : resolve(newItem));
             });
         },
         putItem: async (item) => {
-            if (!skipAssert)
-                assertNoUndefined(item);
             const path = await filePath(hashFilename(item[hashKey]));
             await mkTableDir;
             return new Promise((resolve, reject) => {
@@ -119,8 +104,6 @@ export const fileSystemUnversionedDocumentStore = (initializer) => () => (config
             });
         },
         createItem: async (item) => {
-            if (!skipAssert)
-                assertNoUndefined(item);
             const hashed = hashFilename(item[hashKey]);
             const existingItem = await load(hashed);
             if (existingItem) {
@@ -141,8 +124,6 @@ export const fileSystemUnversionedDocumentStore = (initializer) => () => (config
             // Process items sequentially to ensure consistent conflict detection
             // Note: concurrency parameter is ignored for filesystem to avoid race conditions
             for (const item of items) {
-                if (!skipAssert)
-                    assertNoUndefined(item);
                 try {
                     const hashed = hashFilename(item[hashKey]);
                     const existingItem = await load(hashed);

package/dist/esm/services/documentStore/versioned/file-system.d.ts

@@ -8,7 +8,6 @@ interface Initializer<C> {
 }
 export declare const fileSystemVersionedDocumentStore: <C extends string = "fileSystem">(initializer: Initializer<C>) => <T extends VersionedTDocument<T>>() => (configProvider: { [_key in C]: ConfigProviderForConfig<Config>; }) => <K extends keyof T, A extends undefined | ((...a: any[]) => Promise<VersionedDocumentAuthor>)>(_: {}, hashKey: K, options?: {
     getAuthor?: A;
-    skipAssert?: boolean;
 }) => {
     loadAllDocumentsTheBadWay: () => Promise<T[]>;
     getVersions: (id: T[K], startVersion?: number) => Promise<{

package/dist/esm/services/documentStore/versioned/file-system.js

@@ -1,10 +1,7 @@
-import { assertNoUndefined } from '../fileSystemAssert';
 import { fileSystemUnversionedDocumentStore } from '../unversioned/file-system';
 const PAGE_LIMIT = 5;
 export const fileSystemVersionedDocumentStore = (initializer) => () => (configProvider) => (_, hashKey, options) => {
-    var _a;
-    const skipAssert = (_a = options === null || options === void 0 ? void 0 : options.skipAssert) !== null && _a !== void 0 ? _a : false;
-    const unversionedDocuments = fileSystemUnversionedDocumentStore(initializer)()(configProvider)({}, 'id', { skipAssert });
+    const unversionedDocuments = fileSystemUnversionedDocumentStore(initializer)()(configProvider)({}, 'id');
     return {
         loadAllDocumentsTheBadWay: () => {
             return unversionedDocuments.loadAllDocumentsTheBadWay().then(documents => documents.map(document => {
@@ -12,8 +9,6 @@ export const fileSystemVersionedDocumentStore = (initializer) => () => (configPr
             }));
         },
         getVersions: async (id, startVersion) => {
-            if (!skipAssert)
-                assertNoUndefined(id, ['id']);
             const item = await unversionedDocuments.getItem(id);
             const versions = item === null || item === void 0 ? void 0 : item.items.reverse();
             if (!versions) {
@@ -28,8 +23,6 @@ export const fileSystemVersionedDocumentStore = (initializer) => () => (configPr
             };
         },
         getItem: async (id, timestamp) => {
-            if (!skipAssert)
-                assertNoUndefined(id, ['id']);
             const item = await unversionedDocuments.getItem(id);
             if (timestamp) {
                 return item === null || item === void 0 ? void 0 : item.items.find(version => version.timestamp === timestamp);
@@ -45,8 +38,6 @@ export const fileSystemVersionedDocumentStore = (initializer) => () => (configPr
                 save: async (changes) => {
                     var _a;
                     const document = { ...item, ...changes, timestamp, author };
-                    if (!skipAssert)
-                        assertNoUndefined(document);
                     const container = (_a = await unversionedDocuments.getItem(document[hashKey])) !== null && _a !== void 0 ? _a : { id: document[hashKey], items: [] };
                     const updated = { ...container, items: [...container.items, document] };
                     await unversionedDocuments.putItem(updated);
@@ -58,8 +49,6 @@ export const fileSystemVersionedDocumentStore = (initializer) => () => (configPr
             var _a;
             const author = (options === null || options === void 0 ? void 0 : options.getAuthor) ? await options.getAuthor(...authorArgs) : authorArgs[0];
             const document = { ...item, timestamp: new Date().getTime(), author };
-            if (!skipAssert)
-                assertNoUndefined(document);
             const container = (_a = await unversionedDocuments.getItem(document[hashKey])) !== null && _a !== void 0 ? _a : { id: document[hashKey], items: [] };
             const updated = { ...container, items: [...container.items, document] };
             await unversionedDocuments.putItem(updated);

package/dist/esm/services/lrsGateway/batching.d.ts

@@ -0,0 +1,46 @@
+import { GenericFetch, Response } from '../../fetch';
+import { METHOD } from '../../routing';
+export interface BatchRequest {
+    id: string;
+    path: string;
+    method: METHOD;
+    queryParams?: Record<string, string>;
+    headers?: Record<string, string>;
+    body?: string;
+}
+export interface BatchResponse {
+    id: string;
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+interface BatcherConfig {
+    batchEndpoint: string;
+    getAuthHeader: () => Promise<string>;
+    getHost: () => Promise<string>;
+}
+/**
+ * Handles automatic request batching using microtask queue scheduling.
+ * Batches concurrent requests within the same event loop tick.
+ */
+export declare class RequestBatcher {
+    private fetcher;
+    private config;
+    private pendingRequests;
+    private flushScheduled;
+    private requestCounter;
+    constructor(fetcher: GenericFetch, config: BatcherConfig);
+    /**
+     * Queue a request for batching. Returns a promise that resolves with the response.
+     * Automatically flushes the batch on the next microtask.
+     */
+    queueRequest(options: Omit<BatchRequest, 'id'>): Promise<Response>;
+    singleRequest(options: Omit<BatchRequest, 'id'>): Promise<Response>;
+    /**
+     * Flush all pending requests. If only one request is pending, makes a direct HTTP call.
+     * Otherwise, sends a batch request to the batch API endpoint.
+     */
+    private flush;
+    private flushHandler;
+}
+export {};

package/dist/esm/services/lrsGateway/batching.js

@@ -0,0 +1,102 @@
+import { METHOD } from '../../routing';
+/**
+ * Handles automatic request batching using microtask queue scheduling.
+ * Batches concurrent requests within the same event loop tick.
+ */
+export class RequestBatcher {
+    constructor(fetcher, config) {
+        this.fetcher = fetcher;
+        this.config = config;
+        this.pendingRequests = [];
+        this.flushScheduled = false;
+        this.requestCounter = 0;
+    }
+    /**
+     * Queue a request for batching. Returns a promise that resolves with the response.
+     * Automatically flushes the batch on the next microtask.
+     */
+    queueRequest(options) {
+        const id = `req_${++this.requestCounter}`;
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.push({
+                ...options,
+                id, resolve, reject,
+            });
+            // Schedule microtask flush if not already scheduled
+            if (!this.flushScheduled) {
+                this.flushScheduled = true;
+                queueMicrotask(() => this.flush());
+            }
+        });
+    }
+    async singleRequest(options) {
+        const { path, method, queryParams, headers, body } = options;
+        const host = await this.config.getHost();
+        const query = new URLSearchParams(queryParams || {}).toString();
+        const url = host.replace(/\/+$/, '') + path + (query ? `?${query}` : '');
+        return await this.fetcher(url, { method, headers, body });
+    }
+    /**
+     * Flush all pending requests. If only one request is pending, makes a direct HTTP call.
+     * Otherwise, sends a batch request to the batch API endpoint.
+     */
+    flush() {
+        this.flushScheduled = false;
+        const requests = this.pendingRequests;
+        this.pendingRequests = [];
+        this.flushHandler(requests).catch(error => {
+            // If batch request fails entirely, reject all pending requests
+            requests.forEach(req => req.reject(error));
+        });
+    }
+    async flushHandler(requests) {
+        if (requests.length === 0) {
+            return;
+        }
+        // Single request optimization: bypass batching
+        if (requests.length === 1) {
+            return this.singleRequest(requests[0]).then(requests[0].resolve);
+        }
+        // Multiple requests: use batch API
+        const host = await this.config.getHost();
+        const authHeader = await this.config.getAuthHeader();
+        // Build batch request payload
+        const batchRequests = requests.map(({ id, path, method, queryParams, headers, body }) => {
+            return { id, path, method, queryParams, headers, body };
+        });
+        // Send batch request
+        const batchUrl = host.replace(/\/+$/, '') + this.config.batchEndpoint;
+        const batchResponse = await this.fetcher(batchUrl, {
+            method: METHOD.POST,
+            headers: {
+                Authorization: authHeader,
+                'Content-Type': 'application/json',
+                'X-Experience-API-Version': '1.0.0',
+            },
+            body: JSON.stringify({ requests: batchRequests }),
+        });
+        if (batchResponse.status !== 200) {
+            const errorText = await batchResponse.text();
+            // all requests will be rejected in the catch
+            throw new Error(`Batch request failed with status ${batchResponse.status}: ${errorText}`);
+        }
+        const batchResult = await batchResponse.json();
+        // Map responses back to original requests
+        const responseMap = new Map(batchResult.responses.map(r => [r.id, r]));
+        requests.forEach(req => {
+            const batchResp = responseMap.get(req.id);
+            if (!batchResp) {
+                req.reject(new Error(`No response for request ${req.id} in batch`));
+                return;
+            }
+            req.resolve({
+                status: batchResp.status,
+                headers: {
+                    get: (name) => { var _a; return ((_a = Object.entries(batchResp.headers).find(([key]) => key.toLowerCase() === name.toLowerCase())) === null || _a === void 0 ? void 0 : _a[1]) || null; },
+                },
+                json: async () => JSON.parse(batchResp.body),
+                text: async () => batchResp.body,
+            });
+        });
+    }
+}

package/dist/esm/services/lrsGateway/file-system.js

@@ -6,14 +6,24 @@ import { assertDefined } from '../../assertions';
 import { resolveConfigValue } from '../../config';
 import { UnauthorizedError } from '../../errors';
 import { ifDefined } from '../../guards';
+import { hashValue } from '../../misc/hashValue';
 const pageSize = 5;
 export const fileSystemLrsGateway = (initializer) => (configProvider) => ({ authProvider }) => {
     const name = resolveConfigValue(configProvider[initializer.configSpace || 'fileSystem'].name);
     const filePath = name.then((fileName) => path.join(initializer.dataDir, fileName));
     const { readFile, writeFile } = ifDefined(initializer.fs, fsModule);
     let data;
-    const load = filePath.then(path => new Promise(resolve => {
-        readFile(path, (err, readData) => {
+    let stateData;
+    /**
+     * Creates a composite key for state storage.
+     */
+    const makeStateKey = (activityId, agent, stateId, registration) => {
+        const agentName = typeof agent === 'string' ? agent : agent.account.name;
+        return hashValue({ activityId, agentName, stateId, registration });
+    };
+    const stateFilePath = name.then((fileName) => path.join(initializer.dataDir, `${fileName}-state`));
+    const load = filePath.then(filePath => new Promise(resolve => {
+        readFile(filePath, (err, readData) => {
             if (err) {
                 console.error(err);
             }
@@ -31,7 +41,27 @@ export const fileSystemLrsGateway = (initializer) => (configProvider) => ({ auth
             resolve();
         });
     }));
+    const loadState = stateFilePath.then(stateFilePath => new Promise(resolve => {
+        readFile(stateFilePath, (err, readData) => {
+            if (err) {
+                // File not existing is expected on first run
+            }
+            else {
+                try {
+                    const parsed = JSON.parse(readData.toString());
+                    if (typeof parsed === 'object' && parsed !== null && !(parsed instanceof Array)) {
+                        stateData = parsed;
+                    }
+                }
+                catch (e) {
+                    console.error(e);
+                }
+            }
+            resolve();
+        });
+    }));
     let previousSave;
+    let previousStateSave;
     const putXapiStatements = async (statements) => {
         const user = assertDefined(await authProvider.getUser(), new UnauthorizedError);
         const statementsWithDefaults = statements.map(statement => ({
@@ -101,10 +131,30 @@ export const fileSystemLrsGateway = (initializer) => (configProvider) => ({ auth
             statements: allResults.slice(0, pageSize)
         };
     };
+    const getState = async (activityId, agent, stateId, registration) => {
+        var _a;
+        await loadState;
+        const key = makeStateKey(activityId, agent, stateId, registration);
+        return (_a = stateData === null || stateData === void 0 ? void 0 : stateData[key]) !== null && _a !== void 0 ? _a : null;
+    };
+    const setState = async (activityId, agent, stateId, body, registration) => {
+        await loadState;
+        await previousStateSave;
+        const key = makeStateKey(activityId, agent, stateId, registration);
+        const path = await stateFilePath;
+        const save = previousStateSave = new Promise(resolve => {
+            stateData = stateData || {};
+            stateData[key] = body;
+            writeFile(path, JSON.stringify(stateData, null, 2), () => resolve());
+        });
+        await save;
+    };
     return {
         putXapiStatements,
         getAllXapiStatements,
         getXapiStatements,
         getMoreXapiStatements,
+        getState,
+        setState,
     };
 };

package/dist/esm/services/lrsGateway/index.d.ts

@@ -10,6 +10,17 @@ type Config = {
 interface Initializer<C> {
     configSpace?: C;
     fetch: GenericFetch;
+    enableBatching?: boolean;
+}
+export interface XapiAgent {
+    objectType: 'Agent';
+    account: {
+        homePage: string;
+        name: string;
+    };
+}
+export interface StateDocument {
+    [key: string]: any;
 }
 export interface XapiStatement {
     actor: {
@@ -118,5 +129,7 @@ export declare const lrsGateway: <C extends string = "lrs">(initializer: Initial
     }) & {
         fetchUntil?: (statements: XapiStatement[]) => boolean;
     }) => Promise<XapiStatement[]>;
+    getState: (activityId: string, agent: string | XapiAgent, stateId: string, registration?: string) => Promise<StateDocument | null>;
+    setState: (activityId: string, agent: string | XapiAgent, stateId: string, body: StateDocument, registration?: string) => Promise<void>;
 };
 export {};