ciorent 0.1.4 → 0.1.5

package/README.md

@@ -1,34 +1,13 @@
 A lightweight, low-overhead concurrency library.
-## Semaphore
-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.pause(sem);
-
-  console.log('Task', id, 'started');
-
-  // Let the main thread schedules other tasks
-  for (let i = 1; i <= 5; i++) await co.pause;
+## Features
+- Micro-optimized utilities.
+- Performance-oriented API design.
+- Small bundle size.
+- Fully type-safe.
 
-  console.log('Task', id, 'end');
-
-  // Release the semaphore
-  semaphore.signal(sem);
-}
-
-// Try to run 5 tasks concurrently
-co.spawn(5, task);
-```
-
-## Fibers
+## Examples
+### Fibers
 Virtual threads with more controlled execution.
 
 ```ts
@@ -36,31 +15,57 @@ import * as co from 'ciorent';
 import * as fiber from 'ciorent/fiber';
 
 const f1 = fiber.fn(function* () {
-  console.log('Fiber 1 started');
-
   // Wait for a promise
   yield co.sleep(1000);
 
-  console.log('Fiber 1 done');
+  // 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();
 });
 
-fiber.spawn(function* (proc) {
-  console.log('Fiber 2 started');
+{
+  const main = fiber.spawn(function* (proc) {
+    // Start f1, wait for it to finish and get the result
+    const res = yield* fiber.join(fiber.spawn(f1));
+    console.log('Fiber 2 recieved:', res);
 
-  // Start f1, wait for it to finish and get the result
-  const res = yield* fiber.join(fiber.spawn(f1));
-  console.log('Fiber 1 result:', res);
+    // Start f1 and make its lifetime depends on current fiber
+    const childProc = fiber.spawn(f1);
+    fiber.mount(childProc, proc);
+  });
 
-  // Start f1 and make its lifetime depends on current fiber
-  fiber.mount(fiber.spawn(f1), proc);
+  console.log('Fiber 2 started:', fiber.resumed(main));
 
-  // The runtime will interrupt f1
-  console.log('Fiber 2 done');
-});
+  // Pause the current fiber process
+  fiber.pause(main);
+  console.log('Fiber 2 is paused:', fiber.paused(main));
+
+  // Resume the fiber
+  fiber.resume(main);
+  console.log('Fiber 2 is resumed:', fiber.resumed(main));
+
+  // Wait for the fiber process to finish
+  await fiber.done(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.resumed(main));
+
+  // Stop a fiber
+  fiber.stop(main);
+  console.log('Fiber 1 stopped:', fiber.stopped(main));
+}
 ```
 
-## Latch
+### Latch
 Latch is a synchronization primitive that allows one process to wait until another completes an operation before continuing execution.
 
 ```ts
@@ -87,7 +92,45 @@ task();
 prepare();
 ```
 
-## Pubsub
+### Channel
+Channel is a synchronization primitive via message passing. A message may be sent over a channel, and another process is able to receive messages sent over a channel it has a reference to.
+
+```ts
+import * as channel from 'ciorent/channel';
+import * as co from 'ciorent';
+
+const c = channel.init<number>();
+
+const run = async () => {
+  for (let i = 0; i < 5; i++) {
+    await co.sleep(100);
+    channel.send(c, i);
+    console.log('Sent', i);
+  }
+
+  // Resolve all waiting promises with `undefined`
+  // This is a way to tell the reciever to not listen to more data
+  channel.flush(c);
+};
+
+const log = async () => {
+  while (true) {
+    // Wait until a value is sent to the channel
+    const x = await channel.recieve(c);
+    if (x == null) break;
+
+    console.log('Recieved', x);
+  };
+}
+
+log();
+run();
+
+// This runs first
+console.log('Starting...');
+```
+
+### Pubsub
 A fast, simple publish-subscribe API.
 
 ```ts
@@ -123,46 +166,37 @@ co.spawn(3, async (id: number) => {
 publisher();
 ```
 
-## Channel
-Channel is a synchronization primitive via message passing. A message may be sent over a channel, and another process is able to receive messages sent over a channel it has a reference to.
+### Semaphore
+Semaphore is a concurrency primitive used to control access to a common resource by multiple processes.
 
 ```ts
-import * as channel from 'ciorent/channel';
+import * as semaphore from 'ciorent/semaphore';
 import * as co from 'ciorent';
 
-const c = channel.init<number>();
+// Only allow 2 task to run concurrently
+const sem = semaphore.init(2);
 
-const run = async () => {
-  for (let i = 0; i < 5; i++) {
-    await co.sleep(100);
-    channel.send(c, i);
-    console.log('Sent', i);
-  }
+const task = async (id: number) => {
+  // Acquire the semaphore or wait for the semaphore to be available
+  await semaphore.pause(sem);
 
-  // Resolve all waiting promises with `undefined`
-  // This is a way to tell the reciever to not listen to more data
-  channel.flush(c);
-};
+  console.log('Task', id, 'started');
 
-const log = async () => {
-  while (true) {
-    // Wait until a value is sent to the channel
-    const x = await channel.recieve(c);
-    if (x == null) break;
+  // Let the main thread schedules other tasks
+  for (let i = 1; i <= 5; i++) await co.pause;
 
-    console.log('Recieved', x);
-  };
-}
+  console.log('Task', id, 'end');
 
-log();
-run();
+  // Release the semaphore
+  semaphore.signal(sem);
+}
 
-// This runs first
-console.log('Starting...');
+// Try to run 5 tasks concurrently
+co.spawn(5, task);
 ```
 
-## Utilities
-### Pausing
+### Utilities
+#### Pausing
 Delay the execution of a function for other asynchronous tasks to run.
 ```ts
 import * as co from 'ciorent';
@@ -194,7 +228,7 @@ task1();
 task2();
 ```
 
-### Sleep
+#### Sleep
 Cross-runtime synchronous and asynchronous sleep functions.
 ```ts
 import * as co from 'ciorent';
@@ -213,7 +247,7 @@ co.sleepSync(500);
 logTime('After another 0.5s');
 ```
 
-### Spawning tasks
+#### Spawning tasks
 Utilities to create and run tasks.
 ```ts
 import * as co from 'ciorent';
@@ -232,7 +266,7 @@ console.log('Running 5 tasks concurrently:');
 await Promise.all(co.spawn(5, task));
 ```
 
-### Debounce
+#### Debounce
 Postpones execution until after an idle period.
 ```ts
 import * as co from 'ciorent';
@@ -246,24 +280,7 @@ await co.sleep(100);
 fn(2); // fn(2) gets executed
 ```
 
-### Rate Limit
-Limits the number of calls within a time window.
-```ts
-import * as co from 'ciorent';
-
-// Allow 2 calls in 500ms, other calls are dropped
-const fn = co.rateLimit((id: number) => {
-  console.log('Call ' + id + ':', Math.floor(performance.now()) + 'ms');
-}, 500, 2);
-
-// Some calls will be dropped
-for (let i = 0; i < 8; i++) {
-  fn(i);
-  await co.sleep(400);
-}
-```
-
-### Throttle
+#### Throttle
 Executes a function at a regular interval.
 ```ts
 import * as co from 'ciorent';

package/fiber.d.ts

@@ -35,9 +35,9 @@ export declare const paused: (t: Process) => boolean;
  */
 export declare const resumed: (t: Process) => boolean;
 /**
- * Check whether the fiber has finished
+ * Check whether the fiber has completed
  */
-export declare const done: (t: Process) => boolean;
+export declare const completed: (t: Process) => boolean;
 /**
  * Check whether the fiber has been interrupted
  */
@@ -76,7 +76,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 finish: <T extends Process>(t: T) => T[3];
+export declare const done: <T extends Process>(t: T) => T[0];
 /**
  * Mount child fiber lifetime to parent lifetime
  * @param child

package/fiber.js

@@ -1 +1 @@
-export let paused=(t)=>t[1]===0;export let resumed=(t)=>t[1]===1;export let done=(t)=>t[1]===2;export let stopped=(t)=>t[1]===3;let invoke=async(g,thread)=>{try{let t=g.next();while(!t.done){let v=await t.value;if(thread[1]===0){let r;let p=new Promise((res)=>{r=res});thread[2]=r;await p}if(thread[1]===3)return;t=g.next(v)}thread[1]=2;return t.value}finally{thread[3].forEach(stop)}};export let fn=(f)=>f;export let spawn=(f,...args)=>{let thread=[null,1,null,[]];thread[0]=invoke(f(thread,...args),thread);return thread};export let pause=(t)=>{if(t[1]===1)t[1]=0};export let resume=(t)=>{if(t[1]===0){t[1]=1;t[2]?.()}};export let stop=(t)=>{if(t[1]===0)t[2]?.();t[1]=3};export function*join(t){return yield t[0]}export let finish=(t)=>t[3];export let mount=(child,parent)=>{parent[3].push(child)};export let control=(t,signal)=>{signal.addEventListener("abort",()=>{stop(t)})};export function*unwrap(t){return yield t}
+export let paused=(t)=>t[1]===0;export let resumed=(t)=>t[1]===1;export let completed=(t)=>t[1]===2;export let stopped=(t)=>t[1]===3;let invoke=async(g,thread)=>{try{let t=g.next();while(!t.done){let v=await t.value;if(thread[1]===0){let r;let p=new Promise((res)=>{r=res});thread[2]=r;await p}if(thread[1]===3)return;t=g.next(v)}thread[1]=2;return t.value}finally{if(thread[1]!==2)thread[1]=3;thread[3].forEach(stop)}};export let fn=(f)=>f;export let spawn=(f,...args)=>{let thread=[null,1,null,[]];thread[0]=invoke(f(thread,...args),thread);return thread};export let pause=(t)=>{if(t[1]===1)t[1]=0};export let resume=(t)=>{if(t[1]===0){t[1]=1;t[2]?.()}};export let stop=(t)=>{if(t[1]!==2){if(t[1]===0)t[2]?.();t[1]=3}};export function*join(t){return yield t[0]}export let done=(t)=>t[0];export let mount=(child,parent)=>{parent[3].push(child)};export let control=(t,signal)=>{signal.addEventListener("abort",()=>{stop(t)})};export function*unwrap(t){return yield t}

package/index.d.ts

@@ -41,13 +41,6 @@ export declare const spawn: <const T extends any[], const R>(n: number, task: (.
  * @param ms - The time period in milliseconds
  */
 export declare const debounce: <const Args extends any[]>(f: (...args: Args) => any, ms: number) => ((...args: Args) => void);
-/**
- * Drop function calls for a specific period
- * @param f - The target function to rate limit (it must not throw errors)
- * @param ms - The time period in milliseconds
- * @param limit - The call limit in the time period
- */
-export declare const rateLimit: <const Args extends any[]>(f: (...args: Args) => any, ms: number, limit: number) => ((...args: Args) => void);
 /**
  * Throttle function execution for a time period
  * @param f - The function to throttle (it must not throw errors)

package/index.js

@@ -1 +1 @@
-export let pause=Promise.resolve();export let sleep=globalThis.Bun?.sleep??globalThis.process?.getBuiltinModule?.("timers/promises").setTimeout??((ms)=>new Promise((res)=>{setTimeout(res,ms)}));let sharedBuf=new Int32Array(new SharedArrayBuffer(4));export let sleepSync=globalThis.Bun?.sleepSync??((ms)=>{Atomics.wait(sharedBuf,0,0,ms)});export let sequential=async(n,task,...args)=>{for(let i=0;i<n;i++)await task(...args,i)};export let spawn=(n,task,...args)=>{let arr=new Array(n);for(let i=0;i<n;i++)arr[i]=task(...args,i);return arr};export let debounce=(f,ms)=>{let id;return(...a)=>{clearTimeout(id);id=setTimeout(f,ms,...a)}};export let rateLimit=(f,ms,limit)=>{let cur=limit;let unlock=()=>{cur=limit};return(...a)=>{if(cur>0){if(cur===1)setTimeout(unlock,ms);cur--;f(...a)}}};export let throttle=(f,ms,limit)=>{let head=[null];let tail=head;let cur=limit;let unlock=()=>{cur=limit;while(cur>0){if(tail===head)return;cur--;tail=tail[0];tail[1](f(...tail[2]))}setTimeout(unlock,ms)};return(...a)=>{if(cur===1){setTimeout(unlock,ms)}else if(cur===0){let r;let p=new Promise((res)=>{r=res});head=head[0]=[null,r,a];return p}cur--;return f(...a)}};
+export let pause=Promise.resolve();export let sleep=globalThis.Bun?.sleep??globalThis.process?.getBuiltinModule?.("timers/promises").setTimeout??((ms)=>new Promise((res)=>{setTimeout(res,ms)}));let sharedBuf=new Int32Array(new SharedArrayBuffer(4));export let sleepSync=globalThis.Bun?.sleepSync??((ms)=>{Atomics.wait(sharedBuf,0,0,ms)});export let sequential=async(n,task,...args)=>{for(let i=0;i<n;i++)await task(...args,i)};export let spawn=(n,task,...args)=>{let arr=new Array(n);for(let i=0;i<n;i++)arr[i]=task(...args,i);return arr};export let debounce=(f,ms)=>{let id;return(...a)=>{clearTimeout(id);id=setTimeout(f,ms,...a)}};export let throttle=(f,ms,limit)=>{let head=[null];let tail=head;let cur=limit;let scheduled=false;let unlock=()=>{cur=limit;while(cur>0){if(tail===head){scheduled=false;return}cur--;tail=tail[0];tail[1](f(...tail[2]))}setTimeout(unlock,ms)};return(...a)=>{if(cur===0){let r;let p=new Promise((res)=>{r=res});head=head[0]=[null,r,a];return p}if(!scheduled){scheduled=true;setTimeout(unlock,ms)}cur--;return f(...a)}};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ciorent",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "A lightweight, low-overhead concurrency library",
   "homepage": "https://ciorent.netlify.app",
   "repository": {
@@ -19,13 +19,13 @@
   "types": "./index.d.ts",
   "exports": {
     "./fixed-queue": "./fixed-queue.js",
-    "./dropping-queue": "./dropping-queue.js",
     "./sliding-queue": "./sliding-queue.js",
-    ".": "./index.js",
-    "./topic": "./topic.js",
-    "./semaphore": "./semaphore.js",
+    "./latch": "./latch.js",
     "./channel": "./channel.js",
     "./fiber": "./fiber.js",
-    "./latch": "./latch.js"
+    "./dropping-queue": "./dropping-queue.js",
+    ".": "./index.js",
+    "./topic": "./topic.js",
+    "./semaphore": "./semaphore.js"
   }
 }