j-templates 7.0.65 → 7.0.66

package/Utils/thread.d.ts

@@ -1,10 +1,85 @@
+/**
+ * A threading utility for managing asynchronous and synchronous callbacks
+ * in an efficient manner, similar to how requestIdleCallback works but with
+ * more control over execution timing.
+ *
+ * Only the following functions result in actual thread processing:
+ * - Synch() - executes callbacks synchronously or asynchronously based on context
+ * - Thread() - schedules callbacks that may run synchronously or asynchronously
+ * - ThreadAsync() - creates async operations that return promises
+ *
+ * Schedule() and After() are scheduling functions that add work to the queue,
+ * but don't trigger processing themselves. They only take effect when called
+ * within a callback passed to one of the three processing functions above.
+ *
+ * Example usage:
+ * ```typescript
+ * import { Schedule, Thread, ThreadAsync } from './thread';
+ *
+ * // Run a callback in the next tick
+ * Thread(() => {
+ *   console.log('This runs in thread context');
+ *   // Schedule work to be done after this callback
+ *   Schedule(() => {
+ *     console.log('This runs asynchronously after the thread callback');
+ *   });
+ * });
+ *
+ * // Create an async operation that returns a promise
+ * ThreadAsync(async () => {
+ *   const result = await someAsyncOperation();
+ *   console.log('Result:', result);
+ * }).then(completed => {
+ *   console.log('Async operation completed:', completed);
+ * });
+ *
+ * // Create a callback wrapper
+ * const wrappedCallback = Callback((data: string) => {
+ *   console.log('Received data:', data);
+ * });
+ *
+ * // Schedule the wrapped callback (this will be processed by Thread)
+ * Thread(() => {
+ *   wrappedCallback('Hello World');
+ * });
+ * ```
+ */
+/**
+ * Type definition for thread callback functions
+ */
 type ThreadCallback = {
     (async: boolean): void;
 };
+/**
+ * Schedules a callback to run asynchronously
+ * @param callback - The callback function to schedule
+ */
 export declare function Schedule(callback: ThreadCallback): void;
+/**
+ * Schedules a callback to run after existing callbacks in the same context
+ * @param callback - The callback function to schedule
+ */
 export declare function After(callback: ThreadCallback): void;
+/**
+ * Creates a wrapper function that schedules callbacks to run asynchronously
+ * @param callback - The original callback function
+ * @returns A wrapped function that schedules execution
+ */
 export declare function Callback<A = void, B = void, C = void, D = void>(callback: (a: A, b: B, c: C, d: D) => void): (a?: A, b?: B, c?: C, d?: D) => void;
+/**
+ * Executes a callback synchronously or asynchronously based on context
+ * @param callback - The callback function to execute
+ */
 export declare function Synch(callback: ThreadCallback): void;
+/**
+ * Schedules a callback that can run either synchronously or asynchronously
+ * @param callback - The callback function to schedule
+ */
 export declare function Thread(callback: ThreadCallback): void;
+/**
+ * Creates an asynchronous thread operation that returns a promise
+ * @param callback - The callback function to execute
+ * @returns A promise that resolves when the callback completes
+ */
 export declare function ThreadAsync(callback: ThreadCallback): Promise<boolean>;
 export {};

package/Utils/thread.js

@@ -7,21 +7,43 @@ exports.Synch = Synch;
 exports.Thread = Thread;
 exports.ThreadAsync = ThreadAsync;
 const list_1 = require("./list");
+// Constants
+/**
+ * The maximum time allowed for work execution in milliseconds
+ */
 const workTimeMs = 16;
+/**
+ * Queue of thread contexts that need processing
+ */
 const contextQueue = list_1.List.Create();
+// State variables
 let threadContext = null;
 let timeoutRunning = false;
+// Callback scheduling functions
 const scheduleInitialCallback = queueMicrotask;
 const scheduleCallback = setTimeout;
+/**
+ * Calculates the remaining time until the deadline
+ * @param this - The deadline object
+ * @returns The remaining time in milliseconds
+ */
 function timeRemaining() {
     return this.end - Date.now();
 }
+/**
+ * Creates a deadline object for time management
+ * @returns An IdleDeadline object with timeRemaining function
+ */
 function createDeadline() {
     return {
         end: Date.now() + workTimeMs,
         timeRemaining,
     };
 }
+/**
+ * Processes the queue of thread contexts, executing callbacks within the time limit
+ * @param deadline - The deadline for execution
+ */
 function ProcessQueue(deadline = createDeadline()) {
     let ctx;
     while (deadline.timeRemaining() > 0 && (ctx = list_1.List.Pop(contextQueue)))
@@ -31,6 +53,10 @@ function ProcessQueue(deadline = createDeadline()) {
     else
         timeoutRunning = false;
 }
+/**
+ * Schedules work for a thread context to be processed
+ * @param ctx - The thread context to schedule
+ */
 function ScheduleWork(ctx) {
     list_1.List.Add(contextQueue, ctx);
     if (timeoutRunning)
@@ -38,12 +64,22 @@ function ScheduleWork(ctx) {
     timeoutRunning = true;
     scheduleInitialCallback(ProcessQueue);
 }
+/**
+ * Invokes a callback in the specified thread context
+ * @param ctx - The thread context
+ * @param callback - The callback to invoke
+ */
 function Invoke(ctx, callback) {
     const parent = ctx.workEndNode;
     ctx.workEndNode = ctx.workList.head;
     callback(true);
     ctx.workEndNode = parent;
 }
+/**
+ * Executes work for a specific thread context within a deadline
+ * @param ctx - The thread context to execute work for
+ * @param deadline - The deadline for execution (default: createDeadline())
+ */
 function DoWork(ctx, deadline = createDeadline()) {
     const parentContext = threadContext;
     threadContext = ctx;
@@ -57,6 +93,10 @@ function DoWork(ctx, deadline = createDeadline()) {
         ScheduleWork(ctx);
     threadContext = parentContext;
 }
+/**
+ * Creates a new thread context
+ * @returns A new IThreadContext object
+ */
 function CreateContext() {
     return {
         async: false,
@@ -64,6 +104,12 @@ function CreateContext() {
         workList: list_1.List.Create(),
     };
 }
+/**
+ * Schedules a callback to be executed in the appropriate context
+ * @param callback - The callback function to schedule
+ * @param before - Whether to add the callback before existing ones
+ * @param async - Whether this is an asynchronous operation
+ */
 function ScheduleCallback(callback, before, async) {
     threadContext = threadContext || CreateContext();
     threadContext.async = threadContext.async || async;
@@ -74,6 +120,10 @@ function ScheduleCallback(callback, before, async) {
     else
         threadContext.workEndNode = list_1.List.Add(threadContext.workList, callback);
 }
+/**
+ * Executes a callback synchronously without using threading
+ * @param callback - The callback to execute
+ */
 function SynchWithoutThread(callback) {
     callback(false);
     if (threadContext)
@@ -83,12 +133,25 @@ function SynchWithoutThread(callback) {
             DoWork(threadContext);
     threadContext = null;
 }
+/**
+ * Schedules a callback to run asynchronously
+ * @param callback - The callback function to schedule
+ */
 function Schedule(callback) {
     ScheduleCallback(callback, true, true);
 }
+/**
+ * Schedules a callback to run after existing callbacks in the same context
+ * @param callback - The callback function to schedule
+ */
 function After(callback) {
     ScheduleCallback(callback, false, false);
 }
+/**
+ * Creates a wrapper function that schedules callbacks to run asynchronously
+ * @param callback - The original callback function
+ * @returns A wrapped function that schedules execution
+ */
 function Callback(callback) {
     return function (a, b, c, d) {
         Schedule(function () {
@@ -96,7 +159,14 @@ function Callback(callback) {
         });
     };
 }
+/**
+ * Flag to track if we're currently in a synchronous callback
+ */
 var inSynchCallback = false;
+/**
+ * Executes a callback synchronously or asynchronously based on context
+ * @param callback - The callback function to execute
+ */
 function Synch(callback) {
     if (threadContext || inSynchCallback)
         callback(false);
@@ -106,12 +176,21 @@ function Synch(callback) {
         inSynchCallback = false;
     }
 }
+/**
+ * Schedules a callback that can run either synchronously or asynchronously
+ * @param callback - The callback function to schedule
+ */
 function Thread(callback) {
     if (threadContext)
         ScheduleCallback(callback, true, false);
     else
         Synch(callback);
 }
+/**
+ * Creates an asynchronous thread operation that returns a promise
+ * @param callback - The callback function to execute
+ * @returns A promise that resolves when the callback completes
+ */
 function ThreadAsync(callback) {
     return new Promise((resolve) => Thread(function (async) {
         callback(async);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "j-templates",
-  "version": "7.0.65",
+  "version": "7.0.66",
   "description": "j-templates",
   "license": "MIT",
   "repository": "https://github.com/TypesInCode/jTemplates",