@code-essentials/utils 1.0.0

package/.vscode/launch.json

@@ -0,0 +1,21 @@
+{
+    "configurations": [
+        {
+            "name": "test",
+            "request": "launch",
+            "runtimeArgs": [
+                "run-script",
+                "test"
+            ],
+            "runtimeExecutable": "pnpm",
+            "sourceMaps": true,
+            "pauseForSourceMap": true,
+            "preLaunchTask": "npm: build:debug",
+            "internalConsoleOptions": "neverOpen",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "type": "node"
+        }
+    ]
+}

package/.vscode/tasks.json

@@ -0,0 +1,22 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "npm: build:debug",
+            "type": "shell",
+            "command": "npm",
+            "args": [
+                "run-script",
+                "build:debug",
+            ],
+            "problemMatcher": [
+                "$tsc"
+            ],
+            "presentation": {
+                "reveal": "silent",
+                "close": true,
+            },
+            "group": "build"
+        }
+    ]
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@code-essentials/utils",
+  "version": "1.0.0",
+  "description": "",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "clean": "rm -rf dist",
+    "prebuild": "pnpm run clean",
+    "prebuild:debug": "pnpm run clean",
+    "build": "tsc",
+    "build:debug": "tsc -p tsconfig.debug.json",
+    "pretest": "pnpm run build:debug",
+    "test": "ava"
+  },
+  "devDependencies": {
+    "@ava/typescript": "^6.0.0",
+    "@code-essentials/tsconfig": "^1.0.1",
+    "@types/node": "^24.5.2",
+    "ava": "^6.4.1",
+    "typescript": "^5.9.2"
+  },
+  "ava": {
+    "files": [
+      "src/**/*.spec.ts"
+    ],
+    "typescript": {
+      "rewritePaths": {
+        "src/": "dist/"
+      },
+      "extensions": [
+        "ts"
+      ],
+      "compile": false
+    }
+  },
+  "author": {
+    "name": "Isaac Valdez",
+    "email": "isaac_valdez@msn.com",
+    "url": "https://i12345.github.io"
+  },
+  "license": "MIT"
+}

package/src/async-variable.ts

@@ -0,0 +1,146 @@
+interface AsyncVariableResultBase<Type> {
+    readonly type: Type
+}
+
+interface AsyncVariableResultResolved<T> extends AsyncVariableResultBase<"resolved"> {
+    readonly value: T
+}
+
+interface AsyncVariableResultRejected extends AsyncVariableResultBase<"rejected"> {
+    readonly error: any
+}
+
+type AsyncVariableResult<T> =
+    | AsyncVariableResultResolved<T>
+    | AsyncVariableResultRejected
+
+export class AsyncVariable<T> implements PromiseLike<T> {
+    #result: AsyncVariableResult<T> | undefined
+    #result_res!: (res: AsyncVariableResult<T>) => void
+    #result_p!: Promise<AsyncVariableResult<T>>
+    readonly #initialization: Promise<void>
+
+    get value(): T {
+        if (!this.#result)
+            throw new Error('incomplete')
+
+        if (this.#result.type === "rejected")
+            throw this.#result.error
+
+        return this.#result.value
+    }
+
+    set value(value) {
+        this.set(value)
+    }
+
+    get error() {
+        if (!this.#result)
+            throw new Error('incomplete')
+
+        if (this.#result.type === "resolved")
+            throw new Error(this.#result.type)
+
+        return this.#result.error
+    }
+
+    set error(error) {
+        this.reject(error)
+    }
+
+    get complete() {
+        return this.#result !== undefined
+    }
+
+    constructor() {
+        this.#initialization = new Promise(initialized =>
+            // prevents unhandled rejection
+            this.#result_p = new Promise(res => {
+                this.#result_res = res
+                initialized()
+            })
+        )
+    }
+
+    async init() {
+        await this.#initialization
+    }
+
+    async read() {
+        await this.#initialization
+        await this.#result_p
+        return this.value
+    }
+
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): PromiseLike<TResult1 | TResult2> {
+        return this.read().then(onfulfilled, onrejected)
+    }
+
+    async #complete(throw_if_set = true) {
+        await this.#initialization
+        if (this.complete) {
+            if (throw_if_set)
+                throw new Error('already set')
+            else
+                return false
+        }
+
+        return true
+    }
+
+    async set(value: T, throw_if_set = true) {
+        if (await this.#complete(throw_if_set)) {
+            this.#result_res(this.#result = {
+                type: "resolved",
+                value
+            })
+        }
+    }
+
+    async reject(error: unknown, throw_if_set = true) {
+        if (await this.#complete(throw_if_set)) {
+            this.#result_res(this.#result = {
+                type: "rejected",
+                error
+            })
+        }
+    }
+
+    static performCallback<R = void>(fn: (cb: (err?: unknown, res?: R) => void) => void): AsyncVariable<R> {
+        const av = new AsyncVariable<R>()
+
+        fn(async (err, res) => {
+            if (err)
+                await av.error(err)
+            else
+                await av.set(<R>res)
+        })
+
+        return av
+    }
+
+    perform(fn: () => Promise<T>): this {
+        fn().then(value => this.set(value)).catch(error => this.reject(error))
+
+        return this
+    }
+
+    timeout(milliseconds: number): this {
+        AsyncVariable.wait(milliseconds).then(() => {
+            if (!this.complete)
+                this.reject("timeout")
+        })
+
+        return this
+    }
+
+    static perform<T>(fn: () => Promise<T>): AsyncVariable<T> {
+        return new AsyncVariable<T>().perform(fn)
+    }
+
+    static wait(milliseconds: number) {
+        const res = new AsyncVariable<void>()
+        setTimeout(() => res.set(), milliseconds)
+        return res
+    }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './types.js'
+export * from './async-variable.js'
+export * from './observable-list.js'
+export * from './object.js'
+export * from './lock.js'

package/src/lock.spec.ts

@@ -0,0 +1,38 @@
+import test from "ava"
+import { Lock } from "./lock.js"
+
+test('acquire when free', t => {
+    const lock = new Lock()
+    const context = lock.acquire()
+    context.release()
+    t.pass()
+})
+
+test('fail to acquire when already acquired', t => {
+    const lock = new Lock()
+    lock.acquire()
+    t.throws(() => lock.acquire(), { message: Lock.ERR_ACQUIRED })
+})
+
+test('disposable release', t => {
+    const lock = new Lock()
+
+    function acquire(pass: boolean) {
+        if (pass)
+            t.notThrows(() => lock.acquire())
+        else
+            t.throws(() => lock.acquire(), { message: Lock.ERR_ACQUIRED })
+    }
+
+    function acquire_0() {
+        using _context1 = lock.acquire()
+        acquire(false)
+    }
+
+    function acquire_1() {
+        acquire(true)
+    }
+
+    acquire_0()
+    acquire_1()
+})

package/src/lock.ts

@@ -0,0 +1,50 @@
+export class Lock<Of = void> {
+    #isAcquired = false
+
+    get isAcquired() {
+        return this.#isAcquired
+    }
+
+    acquire(of: Of): LockContext<Of> {
+        if (this.#isAcquired)
+            throw new Error(Lock.ERR_ACQUIRED)
+        this.#isAcquired = true
+        return new LockContext(this, of, this.release.bind(this))
+    }
+
+    protected release(_context: LockContext<Of>) {
+        if (!this.isAcquired)
+            throw new Error()
+
+        this.#isAcquired = false
+    }
+
+    static readonly ERR_ACQUIRED = 'lock currently acquired'
+}
+
+export class LockContext<Of> implements Disposable {
+    readonly #release: (conext: LockContext<Of>) => void
+    #isAcquired = true
+
+    constructor(
+            readonly lock: Lock<Of>,
+            readonly of: Of,
+            release: (conext: LockContext<Of>) => void
+        ) {
+        this.#release = release
+    }
+
+    release() {
+        if (!this.#isAcquired)
+            throw new Error(LockContext.ERR_LOCK_RELEASED)
+
+        this.#isAcquired = false
+        this.#release(this)
+    }
+
+    [Symbol.dispose]() {
+        this.release()
+    }
+
+    static readonly ERR_LOCK_RELEASED = "lock context already released"
+}

package/src/object.spec.ts

@@ -0,0 +1,39 @@
+import test from "ava"
+import { replaceProperty } from "./object.js"
+
+test("replace", t => {
+    interface A {
+        i: number
+        b: B
+    }
+    
+    interface B {
+        j: number
+        c: C
+    }
+
+    interface C {
+        k: number
+    }
+
+    const a0: A = {
+        i: 0,
+        b: {
+            j: 0,
+            c: {
+                k: 0
+            },
+        }
+    }
+
+    t.is(a0.i, 0)
+
+    const a1 = replaceProperty(a0, ["i"], 1)
+
+    t.is(a0.i, 0)
+    t.is(a1.i, 1)
+
+    a0.b.j++
+    t.is(a0.b.j, 1)
+    t.is(a1.b.j, 1)
+})

package/src/object.ts

@@ -0,0 +1,60 @@
+export type Values<T extends object> = T[keyof T]
+
+export type PropertyPath<T> = 
+    | []
+    | T extends object ? Values<{
+        [K in keyof T]: [K] | [K, Values<PropertyPath<T[K]>>]
+    }> : []
+
+export type PropertyType<T, Property extends PropertyPath<T>> = PropertyType_<T, Property>
+type PropertyType_<T, Property extends any[], Constructed extends any[] = []> =
+    (Property & Constructed) extends never ?
+    Values<{
+        [K in keyof T as Property extends [...Constructed, K, ...any[]] ? K : never]:
+        PropertyType_<T[K], Property, [...Constructed, K]>
+    }> :
+    T
+
+// export type PropertyType<T, Property extends PropertyPath<T> & PropertyKey[]> = PropertyType_<T, Property>
+// type PropertyType_<T, Property extends PropertyKey[], Constructed extends PropertyKey[] = []> =
+//     (Property & Constructed) extends never ?
+//     Values<{
+//         [K in keyof T as Property extends [...Constructed, K, ...PropertyKey[]] ? K : never]:
+//         PropertyType_<T[K], Property, [...Constructed, K]>
+//     }> :
+//     T
+
+// type A = {
+//     a: {
+//         a: 10,
+//         b: 1
+//         c: 2
+//     }
+//     b: {
+//         a: {
+//             c: 1
+//         }
+//     }
+// }
+
+// type a_path = PropertyPath<A>
+// const ac = ["a", "c"] satisfies a_path
+// // type a1 = (typeof ac) extends ["a", "c", ...PropertyKey[]] ? true : false
+// type ac_type = PropertyType_<A, typeof ac>
+
+export function replaceProperty<T, Property extends PropertyPath<T> = PropertyPath<T>>(
+        obj: T,
+        property: Property,
+        value: any
+    ): T {
+    if (property.length === 0)
+        return <T>((<any>value) ?? obj)
+
+    if (typeof obj !== 'object')
+        throw new Error()
+
+    const prototype = Object.create(obj)
+    const property0 = property[0]!
+    prototype[property0] = replaceProperty<any>((<any>obj)[property0]!, <any>property.slice(1), value)
+    return <T>prototype
+}

package/src/observable-list.spec.ts

@@ -0,0 +1,25 @@
+import { ObservableList, ObservableListProtocols } from "./observable-list.js"
+import test from "ava"
+
+test("insert", t => {
+    const list = new ObservableList<string>()
+    
+    const words = ["keyboard", "mouse", "display"]
+    t.plan(words.length)
+
+    let itemInserted = ""
+    const responder: ObservableListProtocols<string>["insert"] = (item) => t.is(item, itemInserted)
+    
+    list.on("insert", responder)
+    
+    list.push(itemInserted = words[0]!)
+    list.push(itemInserted = words[1]!)
+
+    list.off("insert", responder)
+
+    list.push("unrelated")
+
+    list.on("insert", responder)
+
+    list.push(itemInserted = words[2]!)
+})

package/src/observable-list.ts

@@ -0,0 +1,114 @@
+export interface ObservableListProtocols<T> {
+    insert(item: T, index: number): void
+    delete(item: T, index: number): void
+    reorder(item: T, index1: number): void
+}
+
+export class ObservableList<T> extends Array<T> {
+    constructor(length: number)
+    constructor(...items: T[])
+    constructor(...itemsOrArrayLength: any[]) {
+        super(...itemsOrArrayLength)
+    }
+
+    override push(...items: T[]): number {
+        const length0 = this.length
+        const result = super.push(...items)
+
+        items.forEach((item, i) => this.#emit("insert", item, length0 + i))
+
+        return result
+    }
+
+    override pop(): T | undefined {
+        const index = this.length - 1
+        const result = super.pop()
+
+        if (index >= 0)
+            this.#emit("delete", result!, index)
+
+        return result
+    }
+
+    override reverse(): T[] {
+        const final_index = this.length - 1
+        const result = super.reverse()
+
+        this.forEach((item, i) => {
+            const index0 = final_index - i
+            const index1 = i
+
+            if (index0 !== index1)
+                this.#emit("reorder", item, index1)
+        })
+
+        return result
+    }
+
+    override sort(compareFn?: ((a: T, b: T) => number) | undefined): this {
+        const result = super.sort(compareFn)
+
+        this.forEach((item, i) => this.#emit("reorder", item, i))
+
+        return result
+    }
+
+    override shift(): T | undefined {
+        const length0 = this.length
+        const result = super.shift()
+
+        if (length0 > 0)
+            this.#emit("delete", result!, 0)
+
+        this.forEach((item, i) => this.#emit("reorder", item, i))
+
+        return result
+    }
+
+    override splice(start: number, deleteCount = 0, ...items: T[]): T[] {
+        const deleted = super.splice(start, deleteCount, ...items)
+
+        deleted.forEach((item, i) => this.#emit("delete", item, start + i))
+
+        if ((deleteCount ?? 0) !== (items?.length ?? 0))
+            for (let i = start + (items?.length ?? 0); i < this.length; i++)
+                this.#emit("reorder", this[i]!, i)
+        
+        items.forEach((item, i) => this.#emit("insert", item, start + i))
+
+        return deleted
+    }
+
+    override unshift(...items: T[]): number {
+        const result = super.unshift(...items)
+
+        for (let i = items.length; i < this.length; i++)
+            this.#emit("reorder", this[i]!, i)
+
+        items.forEach((item, i) => this.#emit("insert", item, i))
+
+        return result
+    }
+
+    #responders: { [Protocol in keyof ObservableListProtocols<T>]: Set<ObservableListProtocols<T>[Protocol]> } = {
+        insert: new Set(),
+        delete: new Set(),
+        reorder: new Set(),
+    }
+
+    #emit<Protocol extends keyof ObservableListProtocols<T>>(protocol: Protocol, ...parameters: Parameters<ObservableListProtocols<T>[Protocol]>): ReturnType<ObservableListProtocols<T>[Protocol]>[] {
+        return [...this.#responders[protocol]].map(responder => (<any>responder)(...parameters))
+    }
+
+    on<Protocol extends keyof ObservableListProtocols<T>>(protocol: Protocol, responder: ObservableListProtocols<T>[Protocol]) {
+        this.#responders[protocol].add(responder)
+    }
+
+    off<Protocol extends keyof ObservableListProtocols<T>>(protocol: Protocol, responder: ObservableListProtocols<T>[Protocol]) {
+        this.#responders[protocol].delete(responder)
+    }
+
+    responders<Protocol extends keyof ObservableListProtocols<T>>(protocol: Protocol) {
+        return this.#responders[protocol]
+    }
+}

package/src/types.ts

@@ -0,0 +1,21 @@
+export type Deleteable<T, K extends keyof T = keyof T> = {
+    -readonly [K1 in K]?: T[K1]
+}
+
+export type PartlyDeleteable<T, K extends keyof T> = {
+    [K1 in keyof T as (K1 extends K ? never : K1)]: T[K1]
+} & Deleteable<T, K>
+
+export type UndefinedIf<T, Condition extends boolean = boolean> = Condition extends true ? undefined : T
+
+export function undefinedIf<T, Condition extends boolean = boolean>(condition: Condition, item: () => T): UndefinedIf<T, Condition> {
+    return <UndefinedIf<T, Condition>>(condition ? undefined : item())
+}
+
+export type Prefixed<Prefix extends string, T extends object> = {
+    [K in string & keyof T as `${Prefix}${K}`]: T[K]
+}
+
+export function prefixed<Prefix extends string, T extends object>(prefix: Prefix, o: T): Prefixed<Prefix, T> {
+    return <Prefixed<Prefix, T>>Object.fromEntries(Object.entries(o).map(([k, v]) => [`${prefix}${k}`, v] as const))
+}

package/tsconfig.debug.json

@@ -0,0 +1,9 @@
+{
+    "extends": "@code-essentials/tsconfig/tsconfig.debug.json",
+    "compilerOptions": {
+        "outDir": "dist",
+        "rootDir": "src",
+    },
+    "include": ["src", "src/**/*.spec.ts"],
+    "exclude": ["node_modules"],
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+    "extends": "@code-essentials/tsconfig/tsconfig.json",
+    "compilerOptions": {
+        "outDir": "dist",
+        "rootDir": "src",
+    },
+    "include": ["src"],
+    "exclude": ["node_modules", "src/**/*.spec.ts"],
+}