ciorent 0.4.4 → 0.5.1

package/README.md

@@ -7,3 +7,160 @@ A lightweight, low-overhead concurrency library.
 - Fully type-safe.
 
 ## Examples
+
+### Pausing
+Continue the execution on next tick, allowing other asynchronous tasks to run.
+```ts
+import * as co from 'ciorent';
+
+const logTime = (label: string) =>
+  console.log(`${label}: ${Math.floor(performance.now())}ms`);
+
+// Expensive sync task
+const task1 = async () => {
+  let x = 0;
+
+  // Simulate heavy operation
+  for (let i = 0, l = (Math.random() + 15) * 1e6; i < l; i++) {
+    // Yield control back occasionally to the runtime, allowing
+    // it to schedule other tasks
+    if (i % 1e5 === 0) await co.nextTick;
+
+    x += Math.random() * 32 + i * Math.round(Math.random() * 16);
+  }
+
+  console.log('Task 1 result:', x);
+};
+
+// Short async task
+const task2 = async (id: number) => {
+  logTime('Task 2.' + id + ' start fetching');
+  await fetch('http://localhost:3000').catch(() => {});
+  logTime('Task 2.' + id + ' done fetching');
+};
+
+task1();
+
+// Task 2 will not get blocked by task 1
+for (let i = 1; i <= 5; i++) task2(i);
+```
+
+### Sleep
+Cross-runtime synchronous and asynchronous sleep functions.
+```ts
+import * as co from 'ciorent';
+
+const logTime = (label: string) =>
+  console.log(`${label}: ${Math.floor(performance.now())}ms`);
+
+logTime('Start');
+
+// Non-blocking
+await co.sleep(500);
+logTime('After about 0.5s');
+
+// This blocks the event loop
+// On the browser this only works in workers and blocks the worker thread
+co.sleepSync(500);
+logTime('After another 0.5s');
+````
+
+### Semaphores
+Semaphore is a concurrency primitive used to control access to a common resource by multiple processes.
+```ts
+import * as semaphore from 'ciorent/semaphore';
+import * as co from 'ciorent';
+
+// Only allow 2 task to run concurrently
+const sem = semaphore.init(2);
+
+const task = async (id: number) => {
+  // Acquire the semaphore or wait for the semaphore to be available
+  await semaphore.acquire(sem);
+
+  console.log('Task', id, 'started');
+
+  // Let the main thread schedules other tasks
+  for (let i = 1; i <= 5; i++) await co.nextTick;
+
+  console.log('Task', id, 'end');
+
+  // Release the semaphore
+  semaphore.release(sem);
+};
+
+for (let i = 1; i <= 5; i++) task(i);
+```
+
+### Fibers
+Virtual threads with more controlled execution.
+```ts
+import * as co from 'ciorent';
+import * as fiber from 'ciorent/fiber';
+
+const logTime = (label: string) =>
+  console.log(`${label}: ${Math.floor(performance.now())}ms`);
+
+const f1 = fiber.fn(function* () {
+  // Wait for a promise
+  console.log('Fiber 1 waiting: 1s');
+  yield co.sleep(1000);
+
+  // Wait for a promise and return its result
+  const res = yield* fiber.unwrap(Promise.resolve(1));
+  console.log('Fiber 1 recieved:', res);
+
+  return Math.random();
+});
+
+{
+  // Start the fiber process on next event loop cycle
+  const main = fiber.spawn(function* (proc) {
+    // Start f1, wait for the process to complete and get the result
+    console.log('Fiber 2: joins fiber 1');
+    const res = yield* fiber.join(fiber.spawn(f1));
+    console.log('Fiber 2 recieved:', res);
+
+    // Start f1 and make its lifetime depends on current fiber
+    console.log('Fiber 2: spawns fiber 1');
+    const childProc = fiber.spawn(f1);
+    fiber.mount(childProc, proc);
+  });
+
+  console.log('Fiber 2 started:', fiber.running(main));
+
+  // Wait for the fiber process to finish
+  await fiber.complete(main);
+
+  // Check finish status
+  console.log('Fiber 2 completed:', fiber.completed(main));
+}
+
+{
+  console.log('------------------------');
+
+  const main = fiber.spawn(f1);
+  console.log('Fiber 1 started:', fiber.running(main));
+
+  // Interrupt a fiber
+  fiber.interrupt(main);
+
+  // Execution will be stopped on the last yield
+  await fiber.complete(main);
+
+  console.log('Fiber 1 interrupted:', fiber.interrupted(main));
+}
+
+{
+  console.log('------------------------');
+
+  const main = fiber.spawn(f1);
+  logTime('Fiber 1 started');
+
+  // Wait for a time period then interrupt the fiber
+  fiber.timeout(main, 500);
+  await fiber.complete(main);
+
+  logTime('Fiber 1 interrupted');
+}
+```

package/fiber.d.ts

@@ -51,7 +51,7 @@ export declare function join<T extends Process>(t: T): Generator<Awaited<T[0]>,
 * Wait for a fiber to finish and retrieve its result
 * @param t
 */
-export declare const done: <T extends Process>(t: T) => T[0];
+export declare const complete: <T extends Process>(t: T) => T[0];
 /**
 * Mount child fiber lifetime to parent lifetime
 * @param child

package/fiber.js

@@ -1 +1 @@
-import{nextTick,sleep}from"./index.js";export let running=e=>e[1]===1;export let completed=e=>e[1]===2;export let interrupted=e=>e[1]===3;let invoke=async(f,p)=>{await nextTick;try{let e=f.next();while(!e.done){let m=await e.value;if(p[1]===3)return;e=f.next(m)}p[1]=2;return e.value}finally{if(p[1]!==2)p[1]=3;p[2].forEach(interrupt)}};export let fn=e=>e;export let spawn=(e,...f)=>{let p=[null,1,[]];p[0]=invoke(e(p,...f),p);return p};export let interrupt=e=>{if(e[1]!==2)e[1]=3};export let timeout=async(e,p)=>{await sleep(p);interrupt(e)};export function*join(e){return yield e[0]}export let done=e=>e[0];export let mount=(e,f)=>{f[2].push(e)};export let control=(e,f)=>{f.addEventListener(`abort`,()=>{interrupt(e)})};export function*unwrap(e){return yield e}
+import{nextTick,sleep}from"./index.js";export let running=e=>e[1]===1;export let completed=e=>e[1]===2;export let interrupted=e=>e[1]===3;let invoke=async(f,p)=>{await nextTick;try{let e=f.next();while(!e.done){let m=await e.value;if(p[1]===3)return;e=f.next(m)}p[1]=2;return e.value}finally{if(p[1]!==2)p[1]=3;p[2].forEach(interrupt)}};export let fn=e=>e;export let spawn=(e,...f)=>{let p=[,1,[]];p[0]=invoke(e(p,...f),p);return p};export let interrupt=e=>{if(e[1]!==2)e[1]=3};export let timeout=async(e,p)=>{await sleep(p);interrupt(e)};export function*join(e){return yield e[0]}export let complete=e=>e[0];export let mount=(e,f)=>{f[2].push(e)};export let control=(e,f)=>{f.addEventListener(`abort`,()=>{interrupt(e)})};export function*unwrap(e){return yield e}

package/index.d.ts

@@ -12,6 +12,12 @@ export declare const nextTick: Promise<void>;
 */
 export declare const sleep: (ms: number) => Promise<void>;
 /**
+* Timeout a promise after ms milliseconds
+* @param promise - Target promise to timeout
+* @param ms - Timeout duration
+*/
+export declare const timeout: <T>(promise: Promise<T>, ms: number) => Promise<T | void>;
+/**
 * Sleep for a duration synchronously.
 *
 * This method blocks the current thread.
@@ -20,24 +26,3 @@ export declare const sleep: (ms: number) => Promise<void>;
 * @param ms - Sleep duration in milliseconds
 */
 export declare const sleepSync: (ms: number) => void;
-/**
-* Spawn n sequential task
-* @param n
-* @param task - The function to run
-*/
-export declare const sequential: <const T extends any[]>(n: number, task: (...args: [...T, id: number]) => Promise<any>, ...args: T) => Promise<void>;
-/**
-* Spawn n concurrent tasks
-* @param n
-* @param task - The function to run
-*/
-export declare const spawn: <
-	const T extends any[],
-	const R
->(n: number, task: (...args: [...T, id: number]) => Promise<R>, ...args: T) => Promise<R>[];
-/**
-* Throttle function execution for a time period
-* @param ms - The time in milliseconds
-* @param limit - The call limit in the time period
-*/
-export declare const throttle: (ms: number, limit: number) => (() => Promise<void>);

package/index.js

@@ -1 +1 @@
-export let nextTick=Promise.resolve();export let sleep=globalThis.Bun?.sleep??globalThis.process?.getBuiltinModule?.(`timers/promises`).setTimeout??(e=>new Promise(t=>{setTimeout(t,e)}));let sharedBuf=new Int32Array(new SharedArrayBuffer(4));export let sleepSync=globalThis.Bun?.sleepSync??(e=>{Atomics.wait(sharedBuf,0,0,e)});export let sequential=async(e,t,...n)=>{for(let r=0;r<e;r++)await t(...n,r)};export let spawn=(e,t,...n)=>{let r=new Array(e);for(let i=0;i<e;i++)r[i]=t(...n,i);return r};export let throttle=(e,t)=>{let n=[null];let r=n;let i=e=>{n=n[0]=[null,e]};let a=t;let o=false;let s=()=>{a=t;if(r===n){o=false;return}do{a--;(r=r[0])[1]()}while(a>0&&r!==n);setTimeout(s,e)};return async()=>{if(a===0)return new Promise(i);if(!o){o=true;setTimeout(s,e)}a--}};
+export let nextTick=Promise.resolve();export let sleep=globalThis.Bun?.sleep??globalThis.process?.getBuiltinModule?.(`timers/promises`).setTimeout??(e=>new Promise(r=>{setTimeout(r,e)}));export let timeout=(e,i)=>Promise.race([e,sleep(i)]);let sharedBuf=new Int32Array(new SharedArrayBuffer(4));export let sleepSync=globalThis.Bun?.sleepSync??(e=>{Atomics.wait(sharedBuf,0,0,e)});

package/package.json

@@ -1,11 +1,10 @@
 {
 "name": "ciorent",
-"version": "0.4.4",
+"version": "0.5.1",
 "description": "A lightweight, low-overhead concurrency library",
-"homepage": "https://ciorent.netlify.app",
 "repository": {
-"type": "github",
-"url": "https://github.com/re-utils/ciorent"
+"type": "git",
+"url": "git+https://github.com/re-utils/ciorent.git"
 },
 "keywords": ["low-overhead", "lightweight", "concurrency", "cross-runtime"],
 "license": "MIT",
@@ -13,10 +12,10 @@
 "main": "./index.js",
 "types": "./index.d.ts",
 "exports": {
-"./queue": "./queue.js",
 "./fiber": "./fiber.js",
-"./stream": "./stream.js",
-".": "./index.js",
-"./semaphore": "./semaphore.js"
+"./queue": "./queue.js",
+"./rate-limit": "./rate-limit.js",
+"./semaphore": "./semaphore.js",
+".": "./index.js"
 }
 }

package/queue.d.ts

@@ -1,14 +1,11 @@
 /**
-* @module Queue utilities
+* @module Queue types
+* @private
 */
 /**
-* Describe a fixed-sized queue
-*/
-export type FixedQueue<T extends {} = {}> = [buffer: (T | undefined | null)[], capacity: number, head: number, tail: number];
-/**
 * Describe a queue node (singly linked list node)
 */
-export type QueueNode<T> = [next: QueueNode<T> | null, value: T];
+export type QueueNode<T> = [next: QueueNode<T> | undefined, value: T];
 /**
 * Describe an unbounded queue
 */

package/rate-limit.d.ts

@@ -0,0 +1,25 @@
+/**
+* @module Rate limit
+*/
+/**
+* Describe a rate limiter
+*/
+export type Limiter = (limit: number, ms: number) => () => boolean;
+/**
+* Fixed window strategy
+* @param limit
+* @param ms
+*/
+export declare const fixed: Limiter;
+/**
+* Sliding window strategy
+* @param limit
+* @param ms
+*/
+export declare const sliding: Limiter;
+/**
+* Token bucket strategy
+* @param limit
+* @param ms
+*/
+export declare const bucket: Limiter;

package/rate-limit.js

@@ -0,0 +1 @@
+export let fixed=(e,t)=>{let n=e;let r=()=>{n=e};return()=>{if(n===0)return false;if(n--===e)setTimeout(r,t);return true}};export let sliding=(e,t)=>{let n=e;let r=()=>{n++};return()=>{if(n===0)return false;n--;setTimeout(r,t);return true}};export let bucket=(e,t)=>{let n=e;t/=e;let r=()=>{if(n++<e)setTimeout(r,t)};return()=>{if(n===0)return false;if(n--===e)setTimeout(r,t);return true}};

package/semaphore.d.ts

@@ -18,7 +18,3 @@ export declare const acquire: (s: Semaphore) => Promise<void>;
 * Signal to the semaphore to release access
 */
 export declare const release: (s: Semaphore) => void;
-/**
-* Bind a task to a semaphore
-*/
-export declare const bind: <T extends (...args: any[]) => Promise<any>>(f: T, s: Semaphore) => T;

package/semaphore.js

@@ -1 +1 @@
-export let init=e=>{let n=[null];let r=[n,n,e=>{r[0]=r[0][0]=[null,e]},e];return r};export let acquire=async e=>{e[3]--;if(e[3]<0)return new Promise(e[2])};export let release=e=>{if(e[3]<0)(e[1]=e[1][0])[1]();e[3]++};export let bind=(e,n)=>async(...r)=>{n[3]--;if(n[3]<0)await new Promise(n[2]);try{return await e(...r)}finally{if(n[3]<0)(n[1]=n[1][0])[1]();n[3]++}};
+export let init=e=>{let t=[,];let n=[t,t,e=>{n[0]=n[0][0]=[,e]},e];return n};export let acquire=async e=>{e[3]--;if(e[3]<0)return new Promise(e[2])};export let release=e=>{if(e[3]<0)(e[1]=e[1][0])[1]();e[3]++};

package/stream.d.ts

@@ -1,27 +0,0 @@
-/**
-* @module Streams
-*/
-import type { PromiseFn, UnboundedQueue } from "./queue.js";
-/**
-* Describe a stream
-*/
-export type Stream<T extends {} = {}> = [...UnboundedQueue<T | ((val?: T) => void)>, callback: PromiseFn<T>, queueing: boolean];
-/**
-* Create a stream
-*/
-export declare const init: <T extends {} = {}>() => Stream<T>;
-/**
-* Write a value to the stream
-* @param s
-* @param v
-*/
-export declare const write: <T extends {} = {}>(s: Stream<T>, v: T) => void;
-/**
-* Read a value from the stream
-* @param s
-*/
-export declare const read: <T extends {} = {}>(s: Stream<T>) => Promise<T | undefined>;
-/**
-* Release all pending read with undefined
-*/
-export declare const flush: (s: Stream) => void;

package/stream.js

@@ -1 +0,0 @@
-export let init=()=>{let e=[null];let r=[e,e,e=>{r[0]=r[0][0]=[null,e]},false];return r};export let write=(e,r)=>{if(!e[3]){if(e[1][0]!==null){(e[1]=e[1][0])[1](r);return}e[3]=true}e[0]=e[0][0]=[null,r]};export let read=async e=>{if(e[3]){e[1]=e[1][0];if(e[1][0]===null)e[3]=false;return e[1][1]}return new Promise(e[2])};export let flush=e=>{if(!e[3])while(e[1][0]!==null)(e[1]=e[1][0])[1]()};