@develia/commons 0.4.12 → 0.4.14

package/src/browser/native-bridge.ts

@@ -1,117 +1,117 @@
-// ─── Tipos ───────────────────────────────────────────────
-interface BridgeOptions {
-    channel: Channel;
-    timeout?: number | null;
-    callbackName?: string;        // ← nuevo
-}
-interface PendingCall {
-    resolve: (value: unknown) => void;
-    reject: (reason: Error) => void;
-    timer: ReturnType<typeof setTimeout> | null;
-}
-
-interface Channel {
-    postMessage: (message: string) => void;
-}
-
-
-
-// ─── Clase ──────────────────────────────────────────────
-
-export default class NativeBridge {
-    private _pending = new Map<number, PendingCall>();
-    private _callId = 0;
-    private readonly _defaultTimeout: number | null;
-    private readonly _channel: Channel;
-
-
-    constructor({ channel, timeout = 3000, callbackName = '__nativeResponseHandler' }: BridgeOptions) {
-        this._defaultTimeout = timeout;
-        this._channel = channel;
-
-        if (!this._channel) {
-            throw new Error('Channel not found');
-        }
-
-        (window as any)[callbackName] = this._callback;
-
-        // Proxy: cualquier propiedad no existente se convierte en call()
-        return new Proxy(this, {
-            get(target: NativeBridge, prop: string | symbol) {
-                if (prop in target) {
-                    return (target as any)[prop];
-                }
-                return (data?: unknown, timeout?: number | null) => target.call(String(prop), data, timeout);
-            },
-        }) as unknown as NativeBridge;
-    }
-
-
-    private _callback(id: number, error: any, result: any) {
-
-        const pending = this._pending.get(id);
-        if (!pending) {
-            return;
-        }
-
-        if (pending.timer !== null) {
-            clearTimeout(pending.timer);
-        }
-
-        this._pending.delete(id);
-
-        if (error) {
-            pending.reject(error instanceof Error? error : new Error(String(error)));
-        } else {
-            pending.resolve(result);
-        }
-    }
-
-    call(method: string, data: unknown = null, timeout?: number | null): Promise<unknown> {
-
-
-        const effectiveTimeout = timeout !== undefined ? timeout : this._defaultTimeout;
-
-        return new Promise<unknown>((resolve, reject) => {
-            const id = this._callId++;
-
-            let timer: ReturnType<typeof setTimeout> | null = null;
-
-            // Solo crear timer si hay timeout
-            if (effectiveTimeout !== null && effectiveTimeout > 0) {
-                timer = setTimeout(() => {
-                    this._pending.delete(id);
-                    reject(new Error(`Timeout (${effectiveTimeout}ms): ${method}`));
-                }, effectiveTimeout);
-            }
-
-            this._pending.set(id, { resolve, reject, timer });
-            this._channel!.postMessage(JSON.stringify({ id, method, data }));
-        });
-    }
-
-
-    send(method: string, data: unknown = null): void {
-        this._channel!.postMessage(JSON.stringify({ method, data }));
-    }
-
-    /**
-     * Número de llamadas pendientes
-     */
-    get pendingCount(): number {
-        return this._pending.size;
-    }
-
-    /**
-     * Cancela todas las llamadas pendientes
-     */
-    cancelAll(): void {
-        for (const [, { reject, timer }] of this._pending) {
-            if (timer !== null) {
-                clearTimeout(timer);
-            }
-            reject(new Error('Cancelled'));
-        }
-        this._pending.clear();
-    }
+// ─── Tipos ───────────────────────────────────────────────
+interface BridgeOptions {
+    channel: Channel;
+    timeout?: number | null;
+    callbackName?: string;        // ← nuevo
+}
+interface PendingCall {
+    resolve: (value: unknown) => void;
+    reject: (reason: Error) => void;
+    timer: ReturnType<typeof setTimeout> | null;
+}
+
+interface Channel {
+    postMessage: (message: string) => void;
+}
+
+
+
+// ─── Clase ──────────────────────────────────────────────
+
+export default class NativeBridge {
+    private _pending = new Map<number, PendingCall>();
+    private _callId = 0;
+    private readonly _defaultTimeout: number | null;
+    private readonly _channel: Channel;
+
+
+    constructor({ channel, timeout = 3000, callbackName = '__nativeResponseHandler' }: BridgeOptions) {
+        this._defaultTimeout = timeout;
+        this._channel = channel;
+
+        if (!this._channel) {
+            throw new Error('Channel not found');
+        }
+
+        (window as any)[callbackName] = this._callback;
+
+        // Proxy: cualquier propiedad no existente se convierte en call()
+        return new Proxy(this, {
+            get(target: NativeBridge, prop: string | symbol) {
+                if (prop in target) {
+                    return (target as any)[prop];
+                }
+                return (data?: unknown, timeout?: number | null) => target.call(String(prop), data, timeout);
+            },
+        }) as unknown as NativeBridge;
+    }
+
+
+    private _callback(id: number, error: any, result: any) {
+
+        const pending = this._pending.get(id);
+        if (!pending) {
+            return;
+        }
+
+        if (pending.timer !== null) {
+            clearTimeout(pending.timer);
+        }
+
+        this._pending.delete(id);
+
+        if (error) {
+            pending.reject(error instanceof Error? error : new Error(String(error)));
+        } else {
+            pending.resolve(result);
+        }
+    }
+
+    call(method: string, data: unknown = null, timeout?: number | null): Promise<unknown> {
+
+
+        const effectiveTimeout = timeout !== undefined ? timeout : this._defaultTimeout;
+
+        return new Promise<unknown>((resolve, reject) => {
+            const id = this._callId++;
+
+            let timer: ReturnType<typeof setTimeout> | null = null;
+
+            // Solo crear timer si hay timeout
+            if (effectiveTimeout !== null && effectiveTimeout > 0) {
+                timer = setTimeout(() => {
+                    this._pending.delete(id);
+                    reject(new Error(`Timeout (${effectiveTimeout}ms): ${method}`));
+                }, effectiveTimeout);
+            }
+
+            this._pending.set(id, { resolve, reject, timer });
+            this._channel!.postMessage(JSON.stringify({ id, method, data }));
+        });
+    }
+
+
+    send(method: string, data: unknown = null): void {
+        this._channel!.postMessage(JSON.stringify({ method, data }));
+    }
+
+    /**
+     * Número de llamadas pendientes
+     */
+    get pendingCount(): number {
+        return this._pending.size;
+    }
+
+    /**
+     * Cancela todas las llamadas pendientes
+     */
+    cancelAll(): void {
+        for (const [, { reject, timer }] of this._pending) {
+            if (timer !== null) {
+                clearTimeout(timer);
+            }
+            reject(new Error('Cancelled'));
+        }
+        this._pending.clear();
+    }
 }

package/src/cancellable-promise.ts

@@ -1,77 +1,77 @@
-type CancellablePromiseExecutor<T> = (
-    resolve: (value: T | PromiseLike<T>) => void,
-    reject: (reason?: unknown) => void,
-    signal: AbortSignal
-) => void;
-
-export default class CancellablePromise<T> extends Promise<T> {
-
-    private _controller: AbortController;
-
-    static get [Symbol.species]() {
-        return Promise;
-    }
-
-    constructor(executor: CancellablePromiseExecutor<T>) {
-        const controller = new AbortController();
-
-        super((resolve, reject) => {
-            controller.signal.addEventListener("abort", () => {
-                reject(controller.signal.reason);
-            });
-
-            executor(resolve, reject, controller.signal);
-        });
-
-        this._controller = controller;
-    }
-
-    get cancelled(): boolean {
-        return this._controller.signal.aborted;
-    }
-
-    cancel(reason: unknown = new Error("Promesa cancelada")): void {
-        if (!this.cancelled) {
-            this._controller.abort(reason);
-        }
-    }
-
-    static async compete<T>(promises: CancellablePromise<T>[]): Promise<T> {
-        return await Promise.race(promises).then(
-            (resultado) => {
-                for (const p of promises) {
-                    p.cancel();
-                }
-                return resultado;
-            },
-            (error) => {
-                for (const p of promises) {
-                    p.cancel();
-                }
-                throw error;
-            }
-        );
-    }
-
-    static async cooperate<T>(promises: CancellablePromise<T>[]): Promise<T[]> {
-        try {
-            return await Promise.all(promises);
-        } catch (error) {
-            for (const p of promises) {
-                p.cancel();
-            }
-            throw error;
-        }
-    }
-
-    static withTimeout<T>(executor: CancellablePromiseExecutor<T>, ms: number): CancellablePromise<T> {
-        return new CancellablePromise<T>((resolve, reject, signal) => {
-            const timer = setTimeout(() => {
-                reject(new Error(`Timeout: ${ms}ms`));
-            }, ms);
-
-            signal.addEventListener("abort", () => clearTimeout(timer));
-            executor(resolve, reject, signal);
-        });
-    }
+type CancellablePromiseExecutor<T> = (
+    resolve: (value: T | PromiseLike<T>) => void,
+    reject: (reason?: unknown) => void,
+    signal: AbortSignal
+) => void;
+
+export default class CancellablePromise<T> extends Promise<T> {
+
+    private _controller: AbortController;
+
+    static get [Symbol.species]() {
+        return Promise;
+    }
+
+    constructor(executor: CancellablePromiseExecutor<T>) {
+        const controller = new AbortController();
+
+        super((resolve, reject) => {
+            controller.signal.addEventListener("abort", () => {
+                reject(controller.signal.reason);
+            });
+
+            executor(resolve, reject, controller.signal);
+        });
+
+        this._controller = controller;
+    }
+
+    get cancelled(): boolean {
+        return this._controller.signal.aborted;
+    }
+
+    cancel(reason: unknown = new Error("Promesa cancelada")): void {
+        if (!this.cancelled) {
+            this._controller.abort(reason);
+        }
+    }
+
+    static async compete<T>(promises: CancellablePromise<T>[]): Promise<T> {
+        return await Promise.race(promises).then(
+            (resultado) => {
+                for (const p of promises) {
+                    p.cancel();
+                }
+                return resultado;
+            },
+            (error) => {
+                for (const p of promises) {
+                    p.cancel();
+                }
+                throw error;
+            }
+        );
+    }
+
+    static async cooperate<T>(promises: CancellablePromise<T>[]): Promise<T[]> {
+        try {
+            return await Promise.all(promises);
+        } catch (error) {
+            for (const p of promises) {
+                p.cancel();
+            }
+            throw error;
+        }
+    }
+
+    static withTimeout<T>(executor: CancellablePromiseExecutor<T>, ms: number): CancellablePromise<T> {
+        return new CancellablePromise<T>((resolve, reject, signal) => {
+            const timer = setTimeout(() => {
+                reject(new Error(`Timeout: ${ms}ms`));
+            }, ms);
+
+            signal.addEventListener("abort", () => clearTimeout(timer));
+            executor(resolve, reject, signal);
+        });
+    }
 }

package/src/collections/index.ts

@@ -1,3 +1,3 @@
-export {default as DefaultWeakMap} from './default-weak-map.js'
-export {default as DefaultMap} from './default-map.js'
+export {default as DefaultWeakMap} from './default-weak-map.js'
+export {default as DefaultMap} from './default-map.js'
 export {default as CacheDictionary} from './cache-dictionary.js';

package/src/draft.ts

@@ -0,0 +1,268 @@
+/**
+ * Methods injected into a draft proxy in addition to the original object's properties.
+ *
+ * @template T - The shape of the wrapped object.
+ */
+type DraftMethods<T> = {
+    /**
+     * Apply pending changes to the original object.
+     *
+     * @param key - Optional property key. If provided, commits only that property.
+     *              If omitted, commits every modified property recursively.
+     * @returns `true` when a single-property commit was applied,
+     *          `false` when the property was not modified,
+     *          `void` when committing the whole draft.
+     */
+    commit(key?: keyof T): boolean | void;
+
+    /**
+     * Discard pending changes, restoring values from the original object.
+     *
+     * @param key - Optional property key. If provided, rolls back only that property.
+     *              If omitted, rolls back every modified property recursively.
+     * @returns `true` when a single-property rollback was applied,
+     *          `false` when the property was not modified,
+     *          `void` when rolling back the whole draft.
+     */
+    rollback(key?: keyof T): boolean | void;
+
+    /**
+     * Check whether the draft (or a specific property) has pending changes.
+     *
+     * @param key - Optional property key. If omitted, checks the whole draft.
+     * @returns `true` if there are pending changes.
+     */
+    isModified(key?: keyof T): boolean;
+
+    /**
+     * Get the list of property keys with pending changes at this draft level.
+     *
+     * @returns Array of modified property keys (does not recurse into children).
+     */
+    modifiedProps(): (keyof T)[];
+
+    /**
+     * Manually mark (or unmark) a property as modified.
+     * Primarily used by child drafts to notify their parent, but also
+     * available for advanced manual control.
+     *
+     * @param key - Property key to flag.
+     * @param modified - `true` to mark as modified (default), `false` to clear.
+     */
+    setModified(key: keyof T, modified?: boolean): void;
+};
+
+/**
+ * A draft proxy: the original object's properties plus draft control methods.
+ *
+ * @template T - The shape of the wrapped object.
+ */
+export type Draft<T extends object> = T & DraftMethods<T>;
+
+/**
+ * Link from a child draft to its parent, used to propagate modification status.
+ */
+type ParentLink = {
+    /** Parent draft methods reference (we only need `setModified`). */
+    parent: { setModified(key: PropertyKey, modified?: boolean): void };
+    /** Key under which this draft is stored in the parent. */
+    keyInParent: PropertyKey;
+};
+
+// ─────────────────────────────────────────────
+// deepDraft (internal)
+// ─────────────────────────────────────────────
+
+/**
+ * Recursively wrap a value so that nested objects/arrays become child drafts
+ * linked to a parent. Primitives, `Date`, `RegExp`, `Map` and `Set` instances
+ * are cloned but not wrapped.
+ *
+ * @param value - The value to process.
+ * @param parentLink - Optional link to a parent draft for change propagation.
+ * @returns A drafted value (or a plain clone for non-wrappable types).
+ */
+function deepDraft(value: any, parentLink?: ParentLink): any {
+    if (value === null || typeof value !== "object") return value;
+    if (value instanceof Date) return new Date(value);
+    if (value instanceof RegExp) return new RegExp(value);
+
+    if (value instanceof Map) {
+        const copy = new Map();
+        for (const [k, v] of value) {
+            copy.set(deepDraft(k), deepDraft(v));
+        }
+        return copy;
+    }
+    if (value instanceof Set) {
+        const copy = new Set();
+        for (const v of value) {
+            copy.add(deepDraft(v));
+        }
+        return copy;
+    }
+
+    return draft(value, parentLink);
+}
+
+/**
+ * Create a draft proxy over `original`. The proxy exposes the same properties
+ * as the original (with nested objects wrapped as child drafts) plus the
+ * control methods `commit`, `rollback`, `isModified`, `modifiedProps` and
+ * `setModified`.
+ *
+ * Mutations on the draft do not affect the original until `commit()` is called.
+ * Nested mutations bubble up: modifying a deep property marks every ancestor
+ * draft as modified at the corresponding key.
+ *
+ * @template T - The shape of the wrapped object.
+ * @param original - The object to wrap. It will only be mutated on `commit()`.
+ * @param parentLink - Internal link used when this draft is a child of another.
+ *                     Do not pass manually.
+ * @returns A draft proxy over a deep copy of `original`.
+ */
+export default function draft<T extends object>(
+    original: T,
+    parentLink?: ParentLink
+): Draft<T> {
+    const copy: any = Array.isArray(original)
+        ? []
+        : Object.create(Object.getPrototypeOf(original));
+
+    const touched = new Set<PropertyKey>();
+
+    const notifyParent = (modified: boolean): void => {
+        if (parentLink) {
+            parentLink.parent.setModified(parentLink.keyInParent, modified);
+        }
+    };
+
+    /**
+     * Apply commit for a single key: delegate to the child draft if present,
+     * otherwise copy the value into `original`.
+     */
+    const applyCommit = (key: PropertyKey): void => {
+        const val = copy[key];
+        if (
+            val !== null &&
+            typeof val === "object" &&
+            "commit" in val
+        ) {
+            (val as Draft<any>).commit();
+            return;
+        }
+        if (key in copy) {
+            (original as any)[key] = copy[key];
+        } else {
+            delete (original as any)[key];
+        }
+    };
+    /**
+     * Apply rollback for a single key: delegate to the child draft if present,
+     * otherwise restore the value from `original`.
+     */
+    const applyRollback = (key: PropertyKey): void => {
+        const val = copy[key];
+        if (
+            val !== null &&
+            typeof val === "object" &&
+            "rollback" in val
+        ) {
+            (val as Draft<any>).rollback();
+            return;
+        }
+        if (key in original) {
+            copy[key] = (original as any)[key];
+        } else {
+            delete copy[key];
+        }
+    };
+
+    const methods: DraftMethods<T> = {
+        commit(key) {
+            if (key === undefined) {
+                for (const k of touched) applyCommit(k);
+                touched.clear();
+                notifyParent(false);
+                return;
+            }
+            if (!touched.has(key)) return false;
+            applyCommit(key);
+            touched.delete(key);
+            if (touched.size === 0) notifyParent(false);
+            return true;
+        },
+
+        rollback(key) {
+            if (key === undefined) {
+                for (const k of touched) applyRollback(k);
+                touched.clear();
+                notifyParent(false);
+                return;
+            }
+            if (!touched.has(key)) return false;
+            applyRollback(key);
+            touched.delete(key);
+            if (touched.size === 0) notifyParent(false);
+            return true;
+        },
+
+        isModified(key) {
+            return key === undefined ? touched.size > 0 : touched.has(key);
+        },
+
+        modifiedProps() {
+            return [...touched] as (keyof T)[];
+        },
+
+        setModified(key, modified = true) {
+            if (modified) {
+                touched.add(key);
+                notifyParent(true);
+            } else {
+                touched.delete(key);
+                if (touched.size === 0) notifyParent(false);
+            }
+        },
+    };
+
+    const isMethodKey = (prop: PropertyKey): prop is keyof DraftMethods<T> =>
+        typeof prop === "string" && prop in methods;
+
+    // Populate `copy` with child drafts linked to this draft.
+    for (const key of Reflect.ownKeys(original)) {
+        copy[key] = deepDraft((original as any)[key], {
+            parent: methods,
+            keyInParent: key,
+        });
+    }
+
+    return new Proxy(copy, {
+        get(target, prop, receiver) {
+            if (isMethodKey(prop)) return (methods as any)[prop];
+            return Reflect.get(target, prop, receiver);
+        },
+
+        set(target, prop, value, receiver) {
+            if (isMethodKey(prop)) {
+                throw new Error(`"${String(prop)}" is a reserved draft property`);
+            }
+            const wrapped = deepDraft(value, {
+                parent: methods,
+                keyInParent: prop,
+            });
+            touched.add(prop);
+            notifyParent(true);
+            return Reflect.set(target, prop, wrapped, receiver);
+        },
+
+        deleteProperty(target, prop) {
+            if (isMethodKey(prop)) {
+                throw new Error(`"${String(prop)}" is a reserved draft property`);
+            }
+            touched.add(prop);
+            notifyParent(true);
+            return Reflect.deleteProperty(target, prop);
+        },
+    }) as Draft<T>;
+}