@develia/commons 0.4.9 → 0.4.13

package/src/draft.ts

@@ -0,0 +1,264 @@
+/**
+ * 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();
+        value.forEach((v, k) => copy.set(deepDraft(k), deepDraft(v)));
+        return copy;
+    }
+    if (value instanceof Set) {
+        const copy = new Set();
+        value.forEach((v) => 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>;
+}

package/src/event-bus.ts

@@ -0,0 +1,84 @@
+// event.ts
+
+export abstract class Event {
+    readonly timestamp: Date;
+
+    protected constructor() {
+        this.timestamp = new Date();
+    }
+
+    toString(): string {
+        return `${this.constructor.name}(${this.timestamp.toISOString()})`;
+    }
+}
+
+type EventClass<T extends Event> = new (...args: any[]) => T;
+type Handler<T extends Event> = (event: T) => void;
+
+interface HandlerWrapper {
+    original: Function;
+    wrapped: (event: Event) => void;
+}
+
+export class EventBus {
+    private static _instance: EventBus | null = null;
+
+    static get shared(): EventBus {
+        return this._instance ??= new EventBus();
+    }
+
+    private _handlers = new Map<Function, HandlerWrapper[]>();
+
+    on<T extends Event>(type: EventClass<T>, handler: Handler<T>): void {
+        if (!this._handlers.has(type)) {
+            this._handlers.set(type, []);
+        }
+        this._handlers.get(type)!.push({
+            original: handler,
+            wrapped: (event: Event) => handler(event as T),
+        });
+    }
+
+    off<T extends Event>(type: EventClass<T>, handler: Handler<T>): void {
+        const handlers = this._handlers.get(type);
+        if (!handlers) return;
+
+        let index = handlers.findIndex((h) => h.original === handler);
+        if (index !== -1) {
+            handlers.splice(index, 1);
+        }
+    }
+
+    emit<T extends Event>(event: T): void {
+        const handlers = this._handlers.get(event.constructor);
+        if (!handlers) return;
+
+        for (const handler of [...handlers]) {
+            try {
+                handler.wrapped(event);
+            } catch (e) {
+                console.error(`[EventBus] Error en handler de ${event.constructor.name}:`, e);
+            }
+        }
+    }
+
+    once<T extends Event>(type: EventClass<T>, handler: Handler<T>): void {
+        const wrapper: Handler<T> = (event: T) => {
+            handler(event);
+            this.off(type, wrapper);
+        };
+        this.on(type, wrapper);
+    }
+
+    clear<T extends Event>(type: EventClass<T>): void {
+        this._handlers.delete(type);
+    }
+
+    clearAll(): void {
+        this._handlers.clear();
+    }
+
+    hasListeners<T extends Event>(type: EventClass<T>): boolean {
+        return (this._handlers.get(type)?.length ?? 0) > 0;
+    }
+}

package/src/index.ts

@@ -24,12 +24,18 @@ export {default as AsyncPoolExecutor} from './async-pool-executor.js';
 // ─── Patterns ────────────────────────────────────────
 export {default as Lazy} from './lazy.js';
 export {default as from, From} from './from.js';
+export {EventBus, Event} from './event-bus.js';
+
+// ─── Draft ────────────────────────────────────────
+export {default as draft} from './draft.js';
 
 // ─── Web ─────────────────────────────────────────────
 export {default as CleanURLSearchParams} from './clean-url-search-params.js';
 /** @deprecated  */
 export {ajaxSubmit, ajaxSubmission, submitForm, formToObject} from './browser/index.js';
 
+
+
 // ─── Deprecated ──────────────────────────────────────
 /** @deprecated  */
 export * from './array.js';

package/src/string.ts

@@ -1,49 +1,129 @@
-
-/**
- * Ensures that a given string has a specific prefix.
- *
- * @param {string} str - The string to ensure the prefix on.
- * @param {string} prefix - The prefix to ensure on the string.
- * @return {string} - The resulting string with the ensured prefix.
- */
-export function ensurePrefix(str: string, prefix: string) {
-    if (!str.startsWith(prefix))
-        return prefix + str
-    return str
-}
-
-
-/**
- * Ensures that a string ends with a specified suffix.
- *
- * @param {string} str - The original string.
- * @param {string} suffix - The suffix to ensure.
- * @return {string} - The modified string with the suffix added if it was not already present.
- */
-export function ensureSuffix(str: string, suffix: string) {
-    if (!str.endsWith(suffix))
-        return str + suffix
-    return str
-}
-
-/**
- * Formats a string using a template and provided arguments.
- *
- * @param {string} template - The template string containing placeholders.
- * @param {any[]} args - Optional arguments to replace the placeholders in the template.
- * @return {string} The formatted string.
- */
-export function format(template: string, ...args: any[]): string {
-
-    let regex: RegExp;
-    if (args.length === 1 && typeof args[0] === 'object') {
-        args = args[0];
-        regex = /{(.+?)}/g;
-    } else {
-        regex = /{(\d+?)}/g;
-    }
-
-    return template.replace(regex, (match, key) => {
-        return typeof args[key] !== 'undefined' ? args[key] : "";
-    });
+
+/**
+ * Ensures that a given string has a specific prefix.
+ *
+ * @param {string} str - The string to ensure the prefix on.
+ * @param {string} prefix - The prefix to ensure on the string.
+ * @return {string} - The resulting string with the ensured prefix.
+ */
+export function ensurePrefix(str: string, prefix: string): string {
+    if (!str.startsWith(prefix))
+        return prefix + str
+    return str
+}
+
+
+/**
+ * Ensures that a string ends with a specified suffix.
+ *
+ * @param {string} str - The original string.
+ * @param {string} suffix - The suffix to ensure.
+ * @return {string} - The modified string with the suffix added if it was not already present.
+ */
+export function ensureSuffix(str: string, suffix: string): string {
+    if (!str.endsWith(suffix))
+        return str + suffix
+    return str
+}
+
+/**
+ * Formats a string using a template and provided arguments.
+ *
+ * @param {string} template - The template string containing placeholders.
+ * @param {any[]} args - Optional arguments to replace the placeholders in the template.
+ * @return {string} The formatted string.
+ */
+export function format(template: string, ...args: any[]): string {
+
+    let regex: RegExp;
+    if (args.length === 1 && typeof args[0] === 'object') {
+        args = args[0];
+        regex = /{(.+?)}/g;
+    } else {
+        regex = /{(\d+?)}/g;
+    }
+
+    return template.replace(regex, (match, key) => {
+        return typeof args[key] !== 'undefined' ? args[key] : "";
+    });
+}
+
+/**
+ * Splits a string into its constituent words, regardless of the original case
+ * style (camelCase, PascalCase, snake_case, kebab-case, CONSTANT_CASE,
+ * space-separated, etc.).
+ *
+ * @param {string} str - The string to split into words.
+ * @return {string[]} - The list of lowercase words extracted from the input.
+ */
+function toWords(str: string): string[] {
+    if (!str) return [];
+
+    return str
+        // Insert a space between a lowercase/digit and an uppercase letter (camelCase -> camel Case)
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        // Insert a space between consecutive uppercase letters followed by a lowercase letter (XMLParser -> XML Parser)
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        // Replace any non-alphanumeric character with a space
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .trim()
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean);
+}
+
+/**
+ * Converts a string to snake_case.
+ *
+ * @param {string} str - The string to convert.
+ * @return {string} - The string converted to snake_case.
+ */
+export function toSnakeCase(str: string): string {
+    return toWords(str).join('_');
+}
+
+/**
+ * Converts a string to kebab-case.
+ *
+ * @param {string} str - The string to convert.
+ * @return {string} - The string converted to kebab-case.
+ */
+export function toKebabCase(str: string): string {
+    return toWords(str).join('-');
+}
+
+/**
+ * Converts a string to camelCase.
+ *
+ * @param {string} str - The string to convert.
+ * @return {string} - The string converted to camelCase.
+ */
+export function toCamelCase(str: string): string {
+    const words = toWords(str);
+    if (words.length === 0) return '';
+    return words
+        .map((word, i) => i === 0 ? word : word.charAt(0).toUpperCase() + word.slice(1))
+        .join('');
+}
+
+/**
+ * Converts a string to PascalCase.
+ *
+ * @param {string} str - The string to convert.
+ * @return {string} - The string converted to PascalCase.
+ */
+export function toPascalCase(str: string): string {
+    return toWords(str)
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+        .join('');
+}
+
+/**
+ * Converts a string to CONSTANT_CASE (a.k.a. SCREAMING_SNAKE_CASE).
+ *
+ * @param {string} str - The string to convert.
+ * @return {string} - The string converted to CONSTANT_CASE.
+ */
+export function toConstantCase(str: string): string {
+    return toWords(str).join('_').toUpperCase();
 }