@lsdsoftware/utils 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sarsa Parilla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# Useful JavaScript utilities
+
+
+## State Machine
+Make implementing state machines less error prone.
+
+```typescript
+import { makeStateMachine } from "@lsdsoftware/utils"
+
+const sm = makeStateMachine({
+  IDLE: {
+    startIt() {
+      //do something
+      return "BUSY"
+    }
+  },
+  BUSY: {
+    stopIt() {
+      //stop doing it
+      return "IDLE"
+    },
+    stopAfterDelay() {
+      return "STOPPING"
+    }
+  },
+  STOPPING: {
+    onTransitionIn(this: any) {
+      //do some clean up
+      this.timer = setTimeout(() => sm.trigger("onDone"), 3000)
+    },
+    onDone() {
+      return "IDLE"
+    },
+    stopIt() {
+      console.log("Already stopping, be patient!")
+      //return void to stay in same state
+    },
+    forceIt(this: any) {
+      clearTimeout(this.timer)
+      return "IDLE"
+    }
+  }
+})
+
+sm.trigger("startIt")
+sm.getState()   //BUSY
+```
+
+
+
+## Message Dispatcher
+Dispatch messages to handlers.  This utility assumes messages are one of three types: request, response, or notification, and follow a predefined format (see type definition below).
+
+Requests and notifications are dispatched to provided request handlers, and responses are generated from their return values.  Responses are dispatched to response listeners.  The caller registers a response listener by calling the waitForResponse method, which returns a promise.
+
+When constructing a dispatcher, caller provides a _myAddress_ parameter used to filter messages.  Only requests and notifications whose _to_ attribute matches _myAddress_ will be processed.
+
+```typescript
+import { makeMessageDispatcher } from "@lsdsoftware/utils"
+
+const requestHandlers = {
+  method1({paramA, paramB}, sender) {
+    //do something
+    return result
+  },
+  async method2({x, y, z}, sender) {
+    //do something
+    return result
+  }
+}
+
+const dispatcher = makeMessageDispatcher("myAddress", requestHandlers)
+
+//sample usage
+
+//processing requests and responses
+window.addEventListener("message", event => {
+  const sender = {window: event.source, origin: event.origin}
+  const sendResponse = response => sender.window.postMessage(response, sender.origin)
+  dispatcher.dispatch(event.data, sender, sendResponse)
+})
+
+//sending requests
+const id = String(Math.random())
+const request = {to: "someAddress", type: "request", id, method: "someMethod", args: {}}
+iframeWindow.postMessage(request, "*")
+dispatcher.waitForResponse(id)
+  .then(result => console.log(result))
+  .catch(console.error)
+```
+
+
+
+## Rate Limiter
+Basic rate limiter using the token bucket algorithm.
+
+```typescript
+import { RateLimiter } from "@lsdsoftware/utils"
+
+const limiter = new RateLimiter({tokensPerInterval: 5, interval: 60*1000})
+
+function handleRequest(userId, req) {
+  if (limiter.tryRemoveTokens(userId, 1)) return processRequest(req)
+  else throw "Rate limit exceeded"
+}
+```
+
+
+
+## Connection Manager
+Takes a connect() method and:
+- Only call it to create a connection when needed
+- Automatically retry on failure
+- Automatically reconnect if the previous connection was closed
+- Properly handle shutdown sequence
+
+```typescript
+import { makeConnectionManager } from "@lsdsoftware/utils"
+
+const conMgr = new ConnectionManager({
+  async connect() {
+    //...
+    return connection
+  },
+  retryDelay: 10*1000
+})
+
+//wherever you need the connection
+const connection = await conMgr.get()
+
+//shutdown
+conMgr.shutdown()
+```
+
+
+
+## Line Split Stream
+A Transform stream that transforms a byte stream into lines of text (by GPT-4)
+
+```typescript
+import { makeLineSplitStream } from "@lsdsoftware/utils"
+
+const splitter = makeLineSplitStream()
+splitter.on('data', line => console.log('Received line:', line))
+
+// Simulating input
+splitter.write('This is a line\nThis is another line\nAnd this is a line as well')
+splitter.end() // End the stream to see the _flush effect.
+```

package/dist/connection-manager.d.ts

@@ -0,0 +1,13 @@
+interface Closeable {
+    close(): void;
+    once(event: "close", callback: Function): void;
+}
+export interface ConnectionManager<Connection> {
+    get(): Promise<Connection>;
+    shutdown(): void;
+}
+export declare function makeConnectionManager<Connection extends Closeable>({ connect, retryDelay }: {
+    connect(): Promise<Connection>;
+    retryDelay: number;
+}): ConnectionManager<Connection>;
+export {};

package/dist/connection-manager.js

@@ -0,0 +1,70 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeConnectionManager = void 0;
+function makeConnectionManager({ connect, retryDelay }) {
+    let connectionPromise;
+    let shutdownFlag = false;
+    return {
+        get() {
+            if (!connectionPromise)
+                connectionPromise = start();
+            return connectionPromise;
+        },
+        shutdown() {
+            shutdownFlag = true;
+            connectionPromise === null || connectionPromise === void 0 ? void 0 : connectionPromise.then(con => con.close()).catch(err => "OK");
+        }
+    };
+    function start() {
+        return new Promise(fulfill => {
+            let firstTime = true;
+            keepAlive(promise => {
+                if (firstTime) {
+                    fulfill(promise);
+                    firstTime = false;
+                }
+                else {
+                    connectionPromise = promise;
+                }
+            });
+        });
+    }
+    function keepAlive(onUpdate) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                while (true) {
+                    const promise = connectUntilSucceed();
+                    onUpdate(promise);
+                    const connection = yield promise;
+                    yield new Promise(f => connection.once("close", f));
+                }
+            }
+            catch (err) {
+            }
+        });
+    }
+    function connectUntilSucceed() {
+        return __awaiter(this, void 0, void 0, function* () {
+            while (true) {
+                if (shutdownFlag)
+                    throw new Error("Shutting down");
+                try {
+                    return yield connect();
+                }
+                catch (err) {
+                    yield new Promise(f => setTimeout(f, retryDelay));
+                }
+            }
+        });
+    }
+}
+exports.makeConnectionManager = makeConnectionManager;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { makeLineSplitStream } from "./line-split-stream";
+import { makeStateMachine } from "./state-machine";
+import { makeConnectionManager } from "./connection-manager";
+import { makeMessageDispatcher } from "./message-dispatcher";
+import { makeRateLimiter } from "./rate-limiter";
+export { makeLineSplitStream, makeStateMachine, makeConnectionManager, makeMessageDispatcher, makeRateLimiter, };

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeRateLimiter = exports.makeMessageDispatcher = exports.makeConnectionManager = exports.makeStateMachine = exports.makeLineSplitStream = void 0;
+const line_split_stream_1 = require("./line-split-stream");
+Object.defineProperty(exports, "makeLineSplitStream", { enumerable: true, get: function () { return line_split_stream_1.makeLineSplitStream; } });
+const state_machine_1 = require("./state-machine");
+Object.defineProperty(exports, "makeStateMachine", { enumerable: true, get: function () { return state_machine_1.makeStateMachine; } });
+const connection_manager_1 = require("./connection-manager");
+Object.defineProperty(exports, "makeConnectionManager", { enumerable: true, get: function () { return connection_manager_1.makeConnectionManager; } });
+const message_dispatcher_1 = require("./message-dispatcher");
+Object.defineProperty(exports, "makeMessageDispatcher", { enumerable: true, get: function () { return message_dispatcher_1.makeMessageDispatcher; } });
+const rate_limiter_1 = require("./rate-limiter");
+Object.defineProperty(exports, "makeRateLimiter", { enumerable: true, get: function () { return rate_limiter_1.makeRateLimiter; } });

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,24 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const line_split_stream_test_1 = require("./line-split-stream.test");
+const rate_limiter_test_1 = require("./rate-limiter.test");
+const state_machine_test_1 = require("./state-machine.test");
+run(Object.assign(Object.assign(Object.assign({}, line_split_stream_test_1.default), rate_limiter_test_1.default), state_machine_test_1.default))
+    .catch(console.error);
+function run(tests) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (const name in tests) {
+            console.log("Running test", name);
+            yield tests[name]();
+        }
+    });
+}

package/dist/line-split-stream.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="node" />
+import { Transform } from "stream";
+export declare function makeLineSplitStream(): Transform;

package/dist/line-split-stream.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeLineSplitStream = void 0;
+const stream_1 = require("stream");
+function makeLineSplitStream() {
+    // Buffer for the part of the chunk that doesn't form a complete line.
+    let remainder = '';
+    return new stream_1.Transform({
+        transform(chunk, encoding, callback) {
+            // Convert chunk to string and add it to the remainder.
+            const chunkStr = remainder + chunk.toString();
+            const lines = chunkStr.split('\n');
+            // Keep the last line in remainder if it doesn't end with a newline character.
+            remainder = lines.pop();
+            // Push each complete line.
+            for (const line of lines)
+                this.push(line + '\n');
+            callback();
+        },
+        flush(callback) {
+            // When the stream is ending, push any remainder as a line if it's not empty.
+            if (remainder)
+                this.push(remainder + '\n');
+            callback();
+        },
+    });
+}
+exports.makeLineSplitStream = makeLineSplitStream;

package/dist/line-split-stream.test.d.ts

@@ -0,0 +1,6 @@
+declare const _default: {
+    lineSplitStream1(): Promise<void>;
+    lineSplitStream2(): Promise<void>;
+    lineSplitStream3(): Promise<void>;
+};
+export default _default;

package/dist/line-split-stream.test.js

@@ -0,0 +1,58 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const line_split_stream_1 = require("./line-split-stream");
+const assert = require("assert");
+exports.default = {
+    lineSplitStream1() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const splitter = (0, line_split_stream_1.makeLineSplitStream)();
+            splitter.write('This is a line\nThis is another line\nAnd this is a line as well');
+            splitter.end();
+            const lines = yield new Promise(fulfill => {
+                let accum = [];
+                splitter.on('data', line => accum.push(line));
+                splitter.on('end', () => fulfill(accum));
+            });
+            assert(lines[0] == "This is a line\n" &&
+                lines[1] == "This is another line\n" &&
+                lines[2] == "And this is a line as well\n");
+        });
+    },
+    lineSplitStream2() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const splitter = (0, line_split_stream_1.makeLineSplitStream)();
+            splitter.write('\nThis is a line\n');
+            splitter.end();
+            const lines = yield new Promise(fulfill => {
+                let accum = [];
+                splitter.on('data', line => accum.push(line));
+                splitter.on('end', () => fulfill(accum));
+            });
+            assert(lines[0] == "\n" &&
+                lines[1] == "This is a line\n");
+        });
+    },
+    lineSplitStream3() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const splitter = (0, line_split_stream_1.makeLineSplitStream)();
+            splitter.write('\n\n');
+            splitter.end();
+            const lines = yield new Promise(fulfill => {
+                let accum = [];
+                splitter.on('data', line => accum.push(line));
+                splitter.on('end', () => fulfill(accum));
+            });
+            assert(lines[0] == "\n" &&
+                lines[1] == "\n");
+        });
+    },
+};

package/dist/message-dispatcher.d.ts

@@ -0,0 +1,29 @@
+export type Message = Request | Notification | Response;
+interface Request {
+    to: string;
+    type: "request";
+    id: "string";
+    method: string;
+    args: Record<string, unknown>;
+}
+interface Notification {
+    to: string;
+    type: "notification";
+    method: string;
+    args: Record<string, unknown>;
+}
+interface Response {
+    type: "response";
+    id: string;
+    error: unknown;
+    result: unknown;
+}
+interface RequestHandler {
+    (args: Record<string, unknown>, sender: unknown): unknown;
+}
+export declare function makeMessageDispatcher(myAddress: string, requestHandlers: Record<string, RequestHandler>): {
+    waitForResponse<T>(requestId: string): Promise<T>;
+    dispatch(message: Message, sender: unknown, sendResponse: (res: Response) => void): boolean | void;
+    updateRequestHandlers(newHandlers: typeof requestHandlers): void;
+};
+export {};

package/dist/message-dispatcher.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeMessageDispatcher = void 0;
+function makeMessageDispatcher(myAddress, requestHandlers) {
+    const pendingRequests = new Map();
+    return {
+        waitForResponse(requestId) {
+            let pending = pendingRequests.get(requestId);
+            if (!pending)
+                pendingRequests.set(requestId, pending = makePending());
+            return pending.promise;
+        },
+        dispatch(message, sender, sendResponse) {
+            switch (message.type) {
+                case "request": return handleRequest(message, sender, sendResponse);
+                case "notification": return handleNotification(message, sender);
+                case "response": return handleResponse(message);
+            }
+        },
+        updateRequestHandlers(newHandlers) {
+            requestHandlers = newHandlers;
+        }
+    };
+    function makePending() {
+        const pending = {};
+        pending.promise = new Promise((fulfill, reject) => {
+            pending.fulfill = fulfill;
+            pending.reject = reject;
+        });
+        return pending;
+    }
+    function handleRequest(req, sender, sendResponse) {
+        if (req.to == myAddress) {
+            if (requestHandlers[req.method]) {
+                Promise.resolve()
+                    .then(() => requestHandlers[req.method](req.args, sender))
+                    .then(result => sendResponse({ type: "response", id: req.id, result, error: undefined }), error => sendResponse({ type: "response", id: req.id, result: undefined, error }));
+                //let caller know that sendResponse will be called asynchronously
+                return true;
+            }
+            else {
+                console.error("No handler for method", req);
+            }
+        }
+    }
+    function handleNotification(ntf, sender) {
+        if (ntf.to == myAddress) {
+            if (requestHandlers[ntf.method]) {
+                Promise.resolve()
+                    .then(() => requestHandlers[ntf.method](ntf.args, sender))
+                    .catch(error => console.error("Failed to handle notification", ntf, error));
+            }
+            else {
+                console.error("No handler for method", ntf);
+            }
+        }
+    }
+    function handleResponse(res) {
+        const pending = pendingRequests.get(res.id);
+        if (pending) {
+            pendingRequests.delete(res.id);
+            if (res.error)
+                pending.reject(res.error);
+            else
+                pending.fulfill(res.result);
+        }
+        else {
+            console.error("Stray response", res);
+        }
+    }
+}
+exports.makeMessageDispatcher = makeMessageDispatcher;

package/dist/rate-limiter.d.ts

@@ -0,0 +1,7 @@
+export declare function makeRateLimiter({ interval, tokensPerInterval }: {
+    interval: number;
+    tokensPerInterval: number;
+}): {
+    getTokensRemaining(key: unknown): number;
+    tryRemoveTokens(key: unknown, numTokens: number): boolean;
+};

package/dist/rate-limiter.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeRateLimiter = void 0;
+class Bucket {
+    constructor(count, expire) {
+        this.count = count;
+        this.expire = expire;
+    }
+    isValid() {
+        return this.expire > Date.now();
+    }
+}
+function makeRateLimiter({ interval, tokensPerInterval }) {
+    const buckets = new Map();
+    let lastCleanup = Date.now();
+    return {
+        getTokensRemaining(key) {
+            const bucket = buckets.get(key);
+            return (bucket === null || bucket === void 0 ? void 0 : bucket.isValid()) ? bucket.count : tokensPerInterval;
+        },
+        tryRemoveTokens(key, numTokens) {
+            if (Date.now() - lastCleanup > 2 * interval) {
+                lastCleanup = Date.now();
+                for (const [key, bucket] of buckets)
+                    if (!bucket.isValid())
+                        buckets.delete(key);
+            }
+            let bucket = buckets.get(key);
+            if (!(bucket === null || bucket === void 0 ? void 0 : bucket.isValid())) {
+                bucket = new Bucket(tokensPerInterval, Date.now() + interval);
+                buckets.set(key, bucket);
+            }
+            if (numTokens <= bucket.count) {
+                bucket.count -= numTokens;
+                return true;
+            }
+            else {
+                return false;
+            }
+        }
+    };
+}
+exports.makeRateLimiter = makeRateLimiter;

package/dist/rate-limiter.test.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    rateLimiter1(): Promise<void>;
+};
+export default _default;

package/dist/rate-limiter.test.js

@@ -0,0 +1,39 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const rate_limiter_1 = require("./rate-limiter");
+const assert = require("assert");
+exports.default = {
+    rateLimiter1() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const limiter = (0, rate_limiter_1.makeRateLimiter)({ tokensPerInterval: 5, interval: 2000 });
+            assert(limiter.getTokensRemaining("k1") == 5);
+            assert(limiter.tryRemoveTokens("k1", 3) == true);
+            assert(limiter.getTokensRemaining("k1") == 2);
+            assert(limiter.tryRemoveTokens("k1", 4) == false);
+            assert(limiter.tryRemoveTokens("k2", 4) == true);
+            yield new Promise(f => setTimeout(f, 1500));
+            assert(limiter.tryRemoveTokens("k1", 4) == false);
+            assert(limiter.getTokensRemaining("k1") == 2);
+            yield new Promise(f => setTimeout(f, 1000));
+            assert(limiter.tryRemoveTokens("k1", 4) == true);
+            //new bucket, won't expire until 2 seconds from now
+            assert(limiter.getTokensRemaining("k1") == 1);
+            assert(limiter.tryRemoveTokens("k1", 2) == false);
+            yield new Promise(f => setTimeout(f, 1900));
+            assert(limiter.tryRemoveTokens("k1", 2) == false);
+            assert(limiter.getTokensRemaining("k1") == 1);
+            yield new Promise(f => setTimeout(f, 200));
+            assert(limiter.tryRemoveTokens("k1", 2) == true);
+            assert(limiter.getTokensRemaining("k1") == 3);
+        });
+    }
+};

package/dist/state-machine.d.ts

@@ -0,0 +1,7 @@
+type EventHandler<StateName> = (...args: any) => StateName | void;
+export type State<StateName extends string, EventName extends string> = Partial<Record<EventName | "onTransitionIn", EventHandler<StateName>>>;
+export declare function makeStateMachine<StateName extends string, EventName extends string>(states: Record<StateName | "IDLE", State<StateName, EventName>>): {
+    trigger(eventName: EventName, ...args: any): void;
+    getState(): StateName | "IDLE";
+};
+export {};

package/dist/state-machine.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeStateMachine = void 0;
+function makeStateMachine(states) {
+    var _a, _b;
+    let currentStateName = "IDLE";
+    (_b = (_a = states[currentStateName]).onTransitionIn) === null || _b === void 0 ? void 0 : _b.call(_a);
+    let lock = 0;
+    return {
+        trigger(eventName, ...args) {
+            var _a, _b;
+            if (lock)
+                throw new Error("Cannot trigger an event synchronously while inside an event handler");
+            lock++;
+            try {
+                const currentState = states[currentStateName];
+                if (!(eventName in currentState))
+                    throw new Error("Missing handler " + currentStateName + "." + eventName);
+                const nextStateName = currentState[eventName](...args);
+                if (nextStateName) {
+                    if (!(nextStateName in states))
+                        throw new Error("Missing state " + nextStateName);
+                    currentStateName = nextStateName;
+                    (_b = (_a = states[currentStateName]).onTransitionIn) === null || _b === void 0 ? void 0 : _b.call(_a);
+                }
+            }
+            finally {
+                lock--;
+            }
+        },
+        getState() {
+            return currentStateName;
+        }
+    };
+}
+exports.makeStateMachine = makeStateMachine;

package/dist/state-machine.test.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    stateMachine1(): Promise<void>;
+};
+export default _default;

package/dist/state-machine.test.js

@@ -0,0 +1,69 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const state_machine_1 = require("./state-machine");
+const assert = require("assert");
+exports.default = {
+    stateMachine1() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const sm = (0, state_machine_1.makeStateMachine)({
+                IDLE: {
+                    play() {
+                        return "PLAYING";
+                    },
+                    stop() { },
+                    goto(state) {
+                        return state;
+                    }
+                },
+                PLAYING: {
+                    play() { },
+                    stop() {
+                        return "STOPPING";
+                    }
+                },
+                STOPPING: {
+                    onTransitionIn() {
+                        this.timer = setTimeout(() => sm.trigger("onStop"), 2000);
+                    },
+                    onStop() {
+                        return "IDLE";
+                    },
+                    play() {
+                        clearTimeout(this.timer);
+                        return "PLAYING";
+                    },
+                    stop() { }
+                },
+                STUCK: {}
+            });
+            assert(sm.getState() == "IDLE");
+            sm.trigger("play");
+            assert(sm.getState() == "PLAYING");
+            sm.trigger("stop");
+            assert(sm.getState() == "STOPPING");
+            yield sleep(1000);
+            sm.trigger("play");
+            assert(sm.getState() == "PLAYING");
+            yield sleep(3000);
+            assert(sm.getState() == "PLAYING");
+            sm.trigger("stop");
+            assert(sm.getState() == "STOPPING");
+            yield sleep(3000);
+            assert(sm.getState() == "IDLE");
+            sm.trigger("goto", "STUCK");
+            assert(sm.getState() == "STUCK");
+        });
+    },
+};
+function sleep(ms) {
+    return new Promise(f => setTimeout(f, ms));
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@lsdsoftware/utils",
+  "version": "1.0.0",
+  "description": "Useful JavaScript utilities",
+  "main": "dist/index.js",
+  "files": [
+    "dist/*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node dist/index.test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lsdsoftware/utils.git"
+  },
+  "author": "Hai Phan <hai.phan@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/lsdsoftware/utils/issues"
+  },
+  "homepage": "https://github.com/lsdsoftware/utils#readme",
+  "devDependencies": {
+    "@types/node": "^20.11.20",
+    "typescript": "^5.3.3"
+  }
+}