@ecosy/core 0.1.0

package/README.md

@@ -0,0 +1,237 @@
+# @ecosy/core
+
+Lightweight utilities, pub/sub subscriber, and types for TypeScript applications.
+
+## Installation
+
+```bash
+npm install @ecosy/core
+# or
+yarn add @ecosy/core
+```
+
+## Modules
+
+| Entry point | Description |
+|--|--|
+| `@ecosy/core` | Re-exports utilities + subscriber |
+| `@ecosy/core/types` | TypeScript type utilities |
+| `@ecosy/core/utilities` | Runtime utility functions |
+| `@ecosy/core/subscriber` | Pub/sub event emitter with state |
+
+---
+
+## Types
+
+```ts
+import type {
+  primitive,
+  LiteralObject,
+  LiteralFunction,
+  Objectable,
+  Freezable,
+  PartialLiteral,
+  ToString,
+  Promisable,
+  AtomicObject,
+} from "@ecosy/core/types";
+```
+
+| Type | Description |
+|--|--|
+| `primitive` | `string \| number \| boolean \| bigint \| symbol \| undefined \| null` |
+| `LiteralObject` | Plain object type (`Record<PropertyKey, unknown> \| object`) |
+| `LiteralFunction<R, A>` | Generic function type `(...args: A) => R` |
+| `Objectable` | `LiteralObject \| Array \| LiteralFunction` |
+| `Freezable<T>` | Recursively readonly version of `T` |
+| `PartialLiteral<T>` | Deep partial that respects built-in types (Map, Set, Promise, etc.) |
+| `ToString<T>` | Converts type to its string literal representation |
+| `Promisable<V>` | `V \| Promise<V>` |
+| `AtomicObject<K, V>` | `{ [K]: V }` |
+
+---
+
+## Utilities
+
+```ts
+import {
+  clone,
+  freeze,
+  isEqual,
+  isFunction,
+  isObject,
+  isLiteralObject,
+  isComplexObject,
+  isObjectable,
+  hasOwnProperty,
+  merge,
+  toString,
+  ucfirst,
+} from "@ecosy/core/utilities";
+```
+
+### `clone<T>(data: T): T`
+
+Deep clones a value. Handles circular references, Date, RegExp, Map, Set, ArrayBuffer, TypedArrays, arrays, and plain objects. Skips non-cloneable types (Error, Promise, WeakMap, DOM nodes, etc.).
+
+```ts
+const original = { a: 1, b: { c: [2, 3] } };
+const cloned = clone(original);
+cloned.b.c.push(4);
+original.b.c.length; // 3 — unaffected
+```
+
+### `freeze<T>(data: T): Freezable<T>`
+
+Deep freezes a value by cloning first, then recursively calling `Object.freeze`.
+
+```ts
+const frozen = freeze({ a: { b: 1 } });
+frozen.a.b = 2; // throws in strict mode
+```
+
+### `isEqual(a: unknown, b: unknown): boolean`
+
+Deep structural equality check. Supports primitives, arrays, plain objects, Date, RegExp, Map, Set, ArrayBuffer, and TypedArrays.
+
+```ts
+isEqual({ a: [1, 2] }, { a: [1, 2] }); // true
+isEqual(new Date(0), new Date(0));      // true
+```
+
+### `merge<T>(source, target, cloneDeep?): T`
+
+Deep merges `target` into `source`. Prototype-polluting keys (`__proto__`, `constructor`, `prototype`) are rejected.
+
+```ts
+merge({ a: 1, b: { c: 2 } }, { b: { d: 3 } });
+// { a: 1, b: { c: 2, d: 3 } }
+```
+
+### `isFunction(value): value is LiteralFunction`
+
+Checks if a value is a function (sync, async, or generator).
+
+### `isObject(value): value is object`
+
+Checks if a value is a non-null object.
+
+### `isLiteralObject(value): value is LiteralObject`
+
+Checks if a value is a plain object (`{}` or `Object.create(null)`).
+
+### `isComplexObject<T>(value): value is T`
+
+Checks if a value is a non-array object (e.g., class instance).
+
+### `isObjectable(value): value is Objectable`
+
+Checks if a value is an object, array, or function.
+
+### `hasOwnProperty(obj, key): boolean`
+
+Type-safe `Object.prototype.hasOwnProperty.call()`.
+
+### `toString(value): string`
+
+Returns the internal `[[Class]]` tag via `Object.prototype.toString`.
+
+```ts
+toString([]);   // "[object Array]"
+toString(null); // "[object Null]"
+```
+
+### `ucfirst<T>(str: T): Capitalize<T>`
+
+Capitalizes the first character of a string.
+
+---
+
+## Subscriber
+
+A pub/sub event emitter with built-in state management.
+
+```ts
+import { Subscriber } from "@ecosy/core/subscriber";
+```
+
+### Basic usage
+
+```ts
+const sub = new Subscriber({ count: 0 });
+
+// Subscribe to state changes
+const unsub = sub.onStateChange((state) => {
+  console.log("Count:", state.count);
+});
+
+// Update state
+sub.setState({ count: 1 }); // logs "Count: 1"
+
+// Cleanup
+unsub();
+```
+
+### Custom channels
+
+```ts
+sub.subscribe("user:login", (user) => {
+  console.log("Logged in:", user.name);
+});
+
+sub.dispatch("user:login", { name: "Alice" });
+```
+
+### Async once
+
+```ts
+const payload = await sub.subscribeAsyncOnce("data:ready");
+```
+
+> [!WARNING]
+> If the channel is never dispatched and no `AbortSignal` is provided, the returned Promise will never resolve, causing a **memory leak**. Always pass an `AbortSignal` or ensure the channel will eventually be dispatched.
+
+```ts
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 5000); // timeout after 5s
+
+try {
+  const payload = await sub.subscribeAsyncOnce("data:ready", undefined, controller.signal);
+} catch {
+  console.log("Timed out or cancelled");
+}
+```
+
+### Wiring events
+
+```ts
+const events = {
+  auth: {
+    login: "$auth:login",
+    logout: "$auth:logout",
+  },
+} as const;
+
+const wired = Subscriber.wire(sub, events);
+
+// Dispatch
+wired.auth.login({ user: "Alice" });
+
+// Listen
+wired.auth.onLogin((payload) => {
+  console.log(payload.user);
+});
+```
+
+---
+
+## Related packages
+
+| Package | Description |
+|--|--|
+| [`@ecosy/store`](https://github.com/material-atomic/ecosy-store) | State management with slices and reducers |
+| [`@ecosy/react`](https://github.com/material-atomic/ecosy-react) | React hooks for `@ecosy/store` |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./subscriber";
+export * from "./utilities";
+export type * from "./subscriber";
+export type * from "./utilities";

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var e=require("./subscriber.js"),i=require("./utilities/clone.js"),r=require("./utilities/freeze.js"),s=require("./utilities/is-equal.js"),t=require("./utilities/is-function.js"),u=require("./utilities/object.js"),o=require("./utilities/merge.js"),c=require("./utilities/to-string.js"),l=require("./utilities/ucfirst.js");exports.Subscriber=e.Subscriber,exports.clone=i.clone,exports.freeze=r.freeze,exports.isEqual=s.isEqual,exports.isFunction=t.isFunction,exports.hasOwnProperty=u.hasOwnProperty,exports.isComplexObject=u.isComplexObject,exports.isLiteralObject=u.isLiteralObject,exports.isObject=u.isObject,exports.isObjectable=u.isObjectable,exports.merge=o.merge,exports.toString=c.toString,exports.ucfirst=l.ucfirst;

package/dist/index.mjs

@@ -0,0 +1 @@
+export{Subscriber}from"./subscriber.mjs";export{clone}from"./utilities/clone.mjs";export{freeze}from"./utilities/freeze.mjs";export{isEqual}from"./utilities/is-equal.mjs";export{isFunction}from"./utilities/is-function.mjs";export{hasOwnProperty,isComplexObject,isLiteralObject,isObject,isObjectable}from"./utilities/object.mjs";export{merge}from"./utilities/merge.mjs";export{toString}from"./utilities/to-string.mjs";export{ucfirst}from"./utilities/ucfirst.mjs";

package/dist/subscriber.d.ts

@@ -0,0 +1,99 @@
+import type { Freezable, LiteralObject, PartialLiteral, ToString } from "@ecosy/core/types";
+export type SubscribeChannel = string;
+export type SubcribeHandler<Payload = never> = [Payload] extends [never] ? () => void : (payload: Payload) => void;
+export interface Shallow {
+    merge<AsType>(source: unknown, target: unknown, cloneDeep?: (data: unknown) => unknown): AsType;
+    clone<DataType>(data: DataType): DataType;
+    isEqual(value1: unknown, value2: unknown): boolean;
+}
+export type ExtendedEventExpect = {
+    readonly [key: string]: {
+        readonly [key: string]: SubscribeChannel;
+    };
+};
+export type WiredEventDomain<Domain extends Record<string, SubscribeChannel>> = {
+    [K in keyof Domain]: <Payload>(payload?: Payload) => void;
+} & {
+    [K in keyof Domain as `on${Capitalize<ToString<K>>}`]: <Payload>(handler: SubcribeHandler<Payload>) => () => void;
+};
+export type WiredEvents<Events extends ExtendedEventExpect> = {
+    readonly [K in keyof Events]: Readonly<WiredEventDomain<Events[K]>>;
+};
+declare const defaultEvents: {
+    readonly state: {
+        readonly change: string;
+    };
+};
+type DefaultEvents = typeof defaultEvents;
+export type SubscriberInstance<State extends LiteralObject = LiteralObject, Events = {}> = InstanceType<typeof Subscriber<State, Events>>;
+/**
+ * Generic pub/sub event emitter with built-in state management.
+ * Provides subscribe/dispatch for arbitrary channels and state change notifications.
+ *
+ * @typeParam State - The shape of the internal state object.
+ * @typeParam Events - Extended event definitions to wire onto the instance.
+ */
+export declare class Subscriber<State extends LiteralObject, Events = {}> {
+    private _state;
+    private listeners;
+    private _shallow;
+    readonly _events: Freezable<DefaultEvents & Events>;
+    get shallow(): Freezable<Shallow>;
+    set shallow(shallow: Shallow | Partial<Shallow>);
+    constructor(initialState?: State | PartialLiteral<State>, events?: Events);
+    /**
+     * Subscribes a handler to a named channel.
+     *
+     * @param channel - The event channel name.
+     * @param handler - Callback invoked when the channel is dispatched.
+     * @returns An unsubscribe function.
+     */
+    subscribe<Payload = never>(channel: SubscribeChannel, handler: SubcribeHandler<Payload>): () => void;
+    /**
+     * Dispatches a payload to all handlers subscribed to the given channel.
+     *
+     * @param channel - The event channel name.
+     * @param payload - Optional data to pass to each handler.
+     */
+    dispatch<Payload = unknown>(channel: SubscribeChannel, payload?: Payload): void;
+    /** Returns the current state. */
+    getState(): State;
+    /**
+     * Merges new state and dispatches a state change event if the state has changed.
+     *
+     * @param state - Full or partial state to merge.
+     */
+    setState(state: State | PartialLiteral<State>): void;
+    /**
+     * Shorthand to subscribe to state change events.
+     *
+     * @param handler - Callback receiving the new state.
+     * @returns An unsubscribe function.
+     */
+    onStateChange(handler: SubcribeHandler<State>): () => void;
+    /**
+     * Subscribes to a channel, resolving a Promise with the first dispatched payload.
+     * Supports cancellation via an `AbortSignal`.
+     *
+     * @warning If the channel is never dispatched and no `AbortSignal` is provided,
+     * the returned Promise will never resolve, causing a memory leak. Always pass an
+     * `AbortSignal` or ensure the channel will eventually be dispatched.
+     *
+     * @param channel - The event channel name.
+     * @param handler - Optional callback invoked on payload.
+     * @param signal - Optional AbortSignal to cancel the subscription.
+     * @returns A promise that resolves with the first payload dispatched to the channel.
+     */
+    subscribeAsyncOnce<Payload = never>(channel: SubscribeChannel, handler?: SubcribeHandler<Payload>, signal?: AbortSignal): Promise<Payload>;
+    /**
+     * Wires event domains onto a `Subscriber` instance, creating typed dispatch and
+     * listener methods (e.g. `instance.domainName.eventName()` and
+     * `instance.domainName.onEventName()`).
+     *
+     * @param $instance - The subscriber instance to extend.
+     * @param events - Event definitions mapping domain → channel names.
+     * @returns The instance with wired event methods.
+     */
+    static wire<ExtendedEvents extends ExtendedEventExpect, State extends LiteralObject, Instance extends SubscriberInstance<State, ExtendedEvents>>($instance: Instance, events: ExtendedEvents): Instance & Freezable<WiredEvents<ExtendedEvents>>;
+}
+export {};

package/dist/subscriber.js

@@ -0,0 +1 @@
+"use strict";var e=require("./utilities/clone.js"),s=require("./utilities/freeze.js"),t=require("./utilities/is-equal.js"),i=require("./utilities/object.js"),r=require("./utilities/merge.js"),l=require("./utilities/ucfirst.js");class n extends Set{}class a extends Map{}const h=s.freeze({state:{change:"$state:change"}});exports.Subscriber=class{get shallow(){return s.freeze({merge:this._shallow.merge,clone:this._shallow.clone,isEqual:this._shallow.isEqual})}set shallow(e){this._shallow=this._shallow.merge(this._shallow,e)}constructor(i,l){this._state={},this.listeners=new a,this._shallow={merge:r.merge,clone:e.clone,isEqual:t.isEqual},this._events=s.freeze(h),this._state=null!=i?i:{},this._events=s.freeze(Object.assign(Object.assign({},this._events),l))}subscribe(e,s){return this.listeners.has(e)||this.listeners.set(e,new n),this.listeners.get(e).add(s),()=>{var t;null===(t=this.listeners.get(e))||void 0===t||t.delete(s)}}dispatch(e,s){this.listeners.has(e)&&this.listeners.get(e).forEach(e=>{e(...void 0===s?[]:[s])})}getState(){return this._state}setState(e){const s=this._shallow.merge(this._state,e);this._shallow.isEqual(this._state,s)||(this._state=s,this.dispatch(this._events.state.change,this._shallow.clone(s)))}onStateChange(e){return this.subscribe(this._events.state.change,e)}async subscribeAsyncOnce(e,s,t){let i,r;try{return await new Promise((l,n)=>{if(null==t?void 0:t.aborted)return n(new Error("Operation cancelled"));i=this.subscribe(e,e=>{null==s||s(e),l(e)}),t&&(r=()=>n(new Error("Operation cancelled")),t.addEventListener("abort",r,{once:!0}))})}finally{null==i||i(),t&&r&&t.removeEventListener("abort",r)}}static wire(e,t){for(const r in t){if(r in e)throw new Error(`[Subscriber.wire] "${r}" is invalid.`);const n=t[r];if(!i.isLiteralObject(n))continue;const a=Object.keys(n).reduce((s,t)=>{const i=n[t];return s[t]=s=>{e.dispatch(i,s)},s[`on${l.ucfirst(t)}`]=s=>e.subscribe(i,s),s},{});Object.defineProperty(e,r,{value:s.freeze(a),writable:!1,enumerable:!0,configurable:!1})}return e}};

package/dist/subscriber.mjs

@@ -0,0 +1 @@
+import{clone as e}from"./utilities/clone.mjs";import{freeze as t}from"./utilities/freeze.mjs";import{isEqual as s}from"./utilities/is-equal.mjs";import{isLiteralObject as i}from"./utilities/object.mjs";import{merge as r}from"./utilities/merge.mjs";import{ucfirst as n}from"./utilities/ucfirst.mjs";class l extends Set{}class a extends Map{}const o=t({state:{change:"$state:change"}});class h{get shallow(){return t({merge:this._shallow.merge,clone:this._shallow.clone,isEqual:this._shallow.isEqual})}set shallow(e){this._shallow=this._shallow.merge(this._shallow,e)}constructor(i,n){this._state={},this.listeners=new a,this._shallow={merge:r,clone:e,isEqual:s},this._events=t(o),this._state=null!=i?i:{},this._events=t(Object.assign(Object.assign({},this._events),n))}subscribe(e,t){return this.listeners.has(e)||this.listeners.set(e,new l),this.listeners.get(e).add(t),()=>{var s;null===(s=this.listeners.get(e))||void 0===s||s.delete(t)}}dispatch(e,t){this.listeners.has(e)&&this.listeners.get(e).forEach(e=>{e(...void 0===t?[]:[t])})}getState(){return this._state}setState(e){const t=this._shallow.merge(this._state,e);this._shallow.isEqual(this._state,t)||(this._state=t,this.dispatch(this._events.state.change,this._shallow.clone(t)))}onStateChange(e){return this.subscribe(this._events.state.change,e)}async subscribeAsyncOnce(e,t,s){let i,r;try{return await new Promise((n,l)=>{if(null==s?void 0:s.aborted)return l(new Error("Operation cancelled"));i=this.subscribe(e,e=>{null==t||t(e),n(e)}),s&&(r=()=>l(new Error("Operation cancelled")),s.addEventListener("abort",r,{once:!0}))})}finally{null==i||i(),s&&r&&s.removeEventListener("abort",r)}}static wire(e,s){for(const r in s){if(r in e)throw new Error(`[Subscriber.wire] "${r}" is invalid.`);const l=s[r];if(!i(l))continue;const a=Object.keys(l).reduce((t,s)=>{const i=l[s];return t[s]=t=>{e.dispatch(i,t)},t[`on${n(s)}`]=t=>e.subscribe(i,t),t},{});Object.defineProperty(e,r,{value:t(a),writable:!1,enumerable:!0,configurable:!1})}return e}}export{h as Subscriber};

package/dist/types/built-in.d.ts

@@ -0,0 +1,22 @@
+export type primitive = string | number | boolean | bigint | symbol | undefined | null;
+export type PrimitiveClass = Date | RegExp | File | FileList | URL | Blob | ArrayBuffer | SharedArrayBuffer | DataView | Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array | FormData | Headers | Request | Response | URLSearchParams | AbortController | AbortSignal | ReadableStream | WritableStream | TransformStream | Event | CustomEvent | EventTarget | MutationObserver | IntersectionObserver | ResizeObserver | Worker | MessageChannel | MessagePort | BroadcastChannel | Generator | AsyncGenerator | Element | HTMLElement | Node | Document | Window | Error | TypeError | RangeError | SyntaxError | ReferenceError | EvalError | AggregateError | URIError;
+export type BuiltInPrimitive = primitive | PrimitiveClass;
+export type LiteralObject<Keys extends PropertyKey = PropertyKey> = Record<Keys, unknown> | {
+    [K in Keys]: unknown;
+} | object;
+export type AtomicObject<Key extends PropertyKey = PropertyKey, Value = unknown> = {
+    [K in Key]: Value;
+};
+export type LiteralFunction<R = unknown, A extends unknown[] = unknown[]> = (...args: A) => R;
+export type Objectable = LiteralObject | Array<unknown> | LiteralFunction;
+export type Promisable<Value> = Value | Promise<Value>;
+export type ExtendedFunction<F = LiteralFunction, O = LiteralObject> = F & O;
+export type Freezable<T> = T extends primitive ? T : T extends (...args: unknown[]) => unknown ? T : T extends Array<infer U> ? ReadonlyArray<Freezable<U>> : T extends object ? {
+    readonly [K in keyof T]: Freezable<T[K]>;
+} : T;
+export type PartialLiteral<T> = T extends Map<infer K, infer V> ? Map<PartialLiteral<K>, PartialLiteral<V>> : T extends WeakMap<infer K, infer V> ? WeakMap<PartialLiteral<K>, PartialLiteral<V>> : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<PartialLiteral<K>, PartialLiteral<V>> : T extends Set<infer U> ? Set<PartialLiteral<U>> : T extends WeakSet<infer U> ? WeakSet<PartialLiteral<U>> : T extends ReadonlySet<infer U> ? ReadonlySet<PartialLiteral<U>> : T extends Promise<infer U> ? Promise<PartialLiteral<U>> : T extends WeakRef<infer U> ? WeakRef<PartialLiteral<U>> : T extends FinalizationRegistry<infer U> ? FinalizationRegistry<PartialLiteral<U>> : T extends BuiltInPrimitive ? T : T extends ExtendedFunction ? T extends ExtendedFunction<infer F> ? F & {
+    [K in keyof T]?: PartialLiteral<T[K]>;
+} : T : T extends LiteralObject ? {
+    [K in keyof T]?: PartialLiteral<T[K]>;
+} : T extends Array<infer U> ? Array<PartialLiteral<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<PartialLiteral<U>> : T;
+export type ToString<T> = T extends string | number | bigint | boolean ? `${T}` : T extends symbol ? string : T extends null ? "null" : T extends undefined ? "undefined" : never;

package/dist/types/built-in.js

@@ -0,0 +1 @@
+"use strict";

package/dist/types/built-in.mjs

@@ -0,0 +1 @@
+

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export type * from "./built-in";

package/dist/types/index.js

@@ -0,0 +1 @@
+"use strict";

package/dist/types/index.mjs

@@ -0,0 +1 @@
+

package/dist/utilities/clone.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Deep clones a value, handling circular references, built-in types (Date, RegExp, Map, Set,
+ * ArrayBuffer, TypedArrays), arrays, and plain objects. Skips non-cloneable types like
+ * Error, Promise, WeakMap, DOM nodes, etc.
+ *
+ * @param data - The value to clone.
+ * @param cache - Internal WeakMap used to track circular references.
+ * @returns A deep copy of the input value.
+ *
+ * @example
+ * ```ts
+ * const original = { a: 1, b: { c: 2 } };
+ * const cloned = clone(original);
+ * cloned.b.c = 3;
+ * original.b.c; // still 2
+ * ```
+ */
+export declare function clone<DataType>(data: DataType, cache?: WeakMap<object, unknown>): DataType;

package/dist/utilities/clone.js

@@ -0,0 +1 @@
+"use strict";var e=require("./is-function.js"),t=require("./object.js");const r={[Date.toString()]:e=>new Date(e.getTime()),[RegExp.toString()]:e=>new RegExp(e.source,e.flags),[Map.toString()]:(e,t)=>{const r=new Map;return t.set(e,r),e.forEach((e,n)=>{r.set(s(n,t),s(e,t))}),r},[Set.toString()]:(e,t)=>{const r=new Set;return t.set(e,r),e.forEach(e=>{r.add(s(e,t))}),r},[ArrayBuffer.toString()]:e=>e.slice(0)},n=[Date,RegExp,Map,Set,ArrayBuffer],o=[Int8Array,Uint8Array,Uint8ClampedArray,Int16Array,Uint16Array,Int32Array,Uint32Array,Float32Array,Float64Array,BigInt64Array,BigUint64Array,DataView],i=Array.from(new Set([Error,Promise,Blob,"undefined"!=typeof WeakMap&&WeakMap,"undefined"!=typeof WeakSet&&WeakSet,"undefined"!=typeof Symbol&&Symbol,"undefined"!=typeof Window&&Window,"undefined"!=typeof File&&File,"undefined"!=typeof FormData&&FormData,"undefined"!=typeof Headers&&Headers,"undefined"!=typeof Request&&Request,"undefined"!=typeof Response&&Response,"undefined"!=typeof Worker&&Worker,"undefined"!=typeof AbortController&&AbortController,"undefined"!=typeof Node&&Node,"undefined"!=typeof FileList&&FileList]));function a(e,t){return t.includes(e)}function s(f,c=new WeakMap){var u;if(!t.isObjectable(f)||e.isFunction(f)||t.hasOwnProperty(f,"$$typeof")||f.constructor&&a(f.constructor,i))return f;if(c.has(f))return c.get(f);if(f.constructor&&a(f.constructor,o)){const e=f,t=new(0,f.constructor)(e.buffer.slice(0),e.byteOffset,e.byteLength);return c.set(f,t),t}const y=f.constructor;if(n.includes(y)){const e=y.toString(),t=(0,r[e])(f,c);return c.set(f,t),t}const d=Array.isArray(f)?new((null===(u=Object.getPrototypeOf(f))||void 0===u?void 0:u.constructor)||Array):Object.create(Object.getPrototypeOf(f));c.set(f,d);const p=Reflect.ownKeys(f);for(const e of p){const t=Object.getOwnPropertyDescriptor(f,e);t&&("value"in t&&(t.value=s(t.value,c)),Object.defineProperty(d,e,t))}return d}exports.clone=s;

package/dist/utilities/clone.mjs

@@ -0,0 +1 @@
+import{isFunction as e}from"./is-function.mjs";import{isObjectable as t,hasOwnProperty as r}from"./object.mjs";const n={[Date.toString()]:e=>new Date(e.getTime()),[RegExp.toString()]:e=>new RegExp(e.source,e.flags),[Map.toString()]:(e,t)=>{const r=new Map;return t.set(e,r),e.forEach((e,n)=>{r.set(s(n,t),s(e,t))}),r},[Set.toString()]:(e,t)=>{const r=new Set;return t.set(e,r),e.forEach(e=>{r.add(s(e,t))}),r},[ArrayBuffer.toString()]:e=>e.slice(0)},o=[Date,RegExp,Map,Set,ArrayBuffer],i=[Int8Array,Uint8Array,Uint8ClampedArray,Int16Array,Uint16Array,Int32Array,Uint32Array,Float32Array,Float64Array,BigInt64Array,BigUint64Array,DataView],f=Array.from(new Set([Error,Promise,Blob,"undefined"!=typeof WeakMap&&WeakMap,"undefined"!=typeof WeakSet&&WeakSet,"undefined"!=typeof Symbol&&Symbol,"undefined"!=typeof Window&&Window,"undefined"!=typeof File&&File,"undefined"!=typeof FormData&&FormData,"undefined"!=typeof Headers&&Headers,"undefined"!=typeof Request&&Request,"undefined"!=typeof Response&&Response,"undefined"!=typeof Worker&&Worker,"undefined"!=typeof AbortController&&AbortController,"undefined"!=typeof Node&&Node,"undefined"!=typeof FileList&&FileList]));function a(e,t){return t.includes(e)}function s(c,u=new WeakMap){var d;if(!t(c)||e(c)||r(c,"$$typeof")||c.constructor&&a(c.constructor,f))return c;if(u.has(c))return u.get(c);if(c.constructor&&a(c.constructor,i)){const e=c,t=new(0,c.constructor)(e.buffer.slice(0),e.byteOffset,e.byteLength);return u.set(c,t),t}const y=c.constructor;if(o.includes(y)){const e=y.toString(),t=(0,n[e])(c,u);return u.set(c,t),t}const p=Array.isArray(c)?new((null===(d=Object.getPrototypeOf(c))||void 0===d?void 0:d.constructor)||Array):Object.create(Object.getPrototypeOf(c));u.set(c,p);const l=Reflect.ownKeys(c);for(const e of l){const t=Object.getOwnPropertyDescriptor(c,e);t&&("value"in t&&(t.value=s(t.value,u)),Object.defineProperty(p,e,t))}return p}export{s as clone};

package/dist/utilities/freeze.d.ts

@@ -0,0 +1,17 @@
+import type { Freezable } from "../types";
+import { clone } from "./clone";
+/**
+ * Deep freezes a value by first cloning it, then recursively calling `Object.freeze`.
+ * Primitives are returned as-is.
+ *
+ * @param data - The value to freeze.
+ * @param cloneDeep - Custom clone function (defaults to `clone`).
+ * @returns A deeply frozen copy of the input.
+ *
+ * @example
+ * ```ts
+ * const frozen = freeze({ a: { b: 1 } });
+ * frozen.a.b = 2; // throws in strict mode
+ * ```
+ */
+export declare function freeze<DataType>(data: DataType, cloneDeep?: typeof clone): Freezable<DataType>;

package/dist/utilities/freeze.js

@@ -0,0 +1 @@
+"use strict";var e=require("./clone.js"),t=require("./object.js");function r(e){const c=Reflect.ownKeys(e);for(const n of c){const c=e[n];t.isObject(c)&&r(c)}return Object.freeze(e)}exports.freeze=function(c,n=e.clone){return t.isObject(c)?r(n(c)):c};

package/dist/utilities/freeze.mjs

@@ -0,0 +1 @@
+import{clone as o}from"./clone.mjs";import{isObject as t}from"./object.mjs";function e(o){const r=Reflect.ownKeys(o);for(const n of r){const r=o[n];t(r)&&e(r)}return Object.freeze(o)}function r(r,n=o){if(!t(r))return r;return e(n(r))}export{r as freeze};

package/dist/utilities/index.d.ts

@@ -0,0 +1,8 @@
+export { clone } from "./clone";
+export { freeze } from "./freeze";
+export { isEqual } from "./is-equal";
+export { isFunction } from "./is-function";
+export { isLiteralObject, isComplexObject, isObject, isObjectable, hasOwnProperty } from "./object";
+export { merge } from "./merge";
+export { toString } from "./to-string";
+export { ucfirst } from "./ucfirst";

package/dist/utilities/index.js

@@ -0,0 +1 @@
+"use strict";var e=require("./clone.js"),r=require("./freeze.js"),s=require("./is-equal.js"),t=require("./is-function.js"),i=require("./object.js"),o=require("./merge.js"),c=require("./to-string.js"),u=require("./ucfirst.js");exports.clone=e.clone,exports.freeze=r.freeze,exports.isEqual=s.isEqual,exports.isFunction=t.isFunction,exports.hasOwnProperty=i.hasOwnProperty,exports.isComplexObject=i.isComplexObject,exports.isLiteralObject=i.isLiteralObject,exports.isObject=i.isObject,exports.isObjectable=i.isObjectable,exports.merge=o.merge,exports.toString=c.toString,exports.ucfirst=u.ucfirst;

package/dist/utilities/index.mjs

@@ -0,0 +1 @@
+export{clone}from"./clone.mjs";export{freeze}from"./freeze.mjs";export{isEqual}from"./is-equal.mjs";export{isFunction}from"./is-function.mjs";export{hasOwnProperty,isComplexObject,isLiteralObject,isObject,isObjectable}from"./object.mjs";export{merge}from"./merge.mjs";export{toString}from"./to-string.mjs";export{ucfirst}from"./ucfirst.mjs";

package/dist/utilities/is-equal.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Performs a deep structural equality check between two values.
+ * Supports primitives, arrays, plain objects, Date, RegExp, Map, Set,
+ * ArrayBuffer, and TypedArrays.
+ *
+ * @param value1 - The first value to compare.
+ * @param value2 - The second value to compare.
+ * @returns `true` if both values are deeply equal.
+ *
+ * @example
+ * ```ts
+ * isEqual({ a: 1 }, { a: 1 }); // true
+ * isEqual([1, 2], [1, 3]); // false
+ * isEqual(new Date(0), new Date(0)); // true
+ * ```
+ */
+export declare function isEqual(value1: unknown, value2: unknown): boolean;

package/dist/utilities/is-equal.js

@@ -0,0 +1 @@
+"use strict";var r=require("./object.js");function e(r,e){if(r.byteLength!==e.byteLength)return!1;const t=ArrayBuffer.isView(r)?r.buffer:r,i=ArrayBuffer.isView(r)?r.byteOffset:0,f=ArrayBuffer.isView(e)?e.buffer:e,n=ArrayBuffer.isView(e)?e.byteOffset:0,s=new Uint8Array(t,i,r.byteLength),u=new Uint8Array(f,n,e.byteLength);for(let r=0;r<s.length;r++)if(s[r]!==u[r])return!1;return!0}const t=new Map([[Date,(r,e)=>Object.is(r.getTime(),e.getTime())],[RegExp,(r,e)=>Object.is(r.source,e.source)&&Object.is(r.flags,e.flags)],[ArrayBuffer,e],[Map,(r,e)=>{if(r.size!==e.size)return!1;for(const[t,f]of r)if(!e.has(t)||!i(f,e.get(t)))return!1;return!0}],[Set,(r,e)=>{if(r.size!==e.size)return!1;for(const t of r){let r=!1;for(const f of e)if(i(t,f)){r=!0;break}if(!r)return!1}return!0}]]);function i(f,n){if(!r.isObject(f)||!r.isObject(n))return Object.is(f,n);if(f.constructor!==n.constructor)return!1;if(Array.isArray(f)){if(!Array.isArray(n)||f.length!==n.length)return!1;for(let r=0;r<f.length;r++)if(!i(f[r],n[r]))return!1;return!0}if(ArrayBuffer.isView(f)&&ArrayBuffer.isView(n))return e(f,n);if(f.constructor&&t.has(f.constructor))return t.get(f.constructor)(f,n);if(!r.isLiteralObject(f)||!r.isLiteralObject(n))return f===n;const s=Object.keys(f),u=Object.keys(n);if(s.length!==u.length)return!1;for(const e of s)if(!r.hasOwnProperty(n,e)||!i(f[e],n[e]))return!1;return!0}exports.isEqual=i;

package/dist/utilities/is-equal.mjs

@@ -0,0 +1 @@
+import{isObject as r,isLiteralObject as e,hasOwnProperty as t}from"./object.mjs";function f(r,e){if(r.byteLength!==e.byteLength)return!1;const t=ArrayBuffer.isView(r)?r.buffer:r,f=ArrayBuffer.isView(r)?r.byteOffset:0,n=ArrayBuffer.isView(e)?e.buffer:e,i=ArrayBuffer.isView(e)?e.byteOffset:0,s=new Uint8Array(t,f,r.byteLength),u=new Uint8Array(n,i,e.byteLength);for(let r=0;r<s.length;r++)if(s[r]!==u[r])return!1;return!0}const n=new Map([[Date,(r,e)=>Object.is(r.getTime(),e.getTime())],[RegExp,(r,e)=>Object.is(r.source,e.source)&&Object.is(r.flags,e.flags)],[ArrayBuffer,f],[Map,(r,e)=>{if(r.size!==e.size)return!1;for(const[t,f]of r)if(!e.has(t)||!i(f,e.get(t)))return!1;return!0}],[Set,(r,e)=>{if(r.size!==e.size)return!1;for(const t of r){let r=!1;for(const f of e)if(i(t,f)){r=!0;break}if(!r)return!1}return!0}]]);function i(s,u){if(!r(s)||!r(u))return Object.is(s,u);if(s.constructor!==u.constructor)return!1;if(Array.isArray(s)){if(!Array.isArray(u)||s.length!==u.length)return!1;for(let r=0;r<s.length;r++)if(!i(s[r],u[r]))return!1;return!0}if(ArrayBuffer.isView(s)&&ArrayBuffer.isView(u))return f(s,u);if(s.constructor&&n.has(s.constructor))return n.get(s.constructor)(s,u);if(!e(s)||!e(u))return s===u;const o=Object.keys(s),c=Object.keys(u);if(o.length!==c.length)return!1;for(const r of o)if(!t(u,r)||!i(s[r],u[r]))return!1;return!0}export{i as isEqual};

package/dist/utilities/is-function.d.ts

@@ -0,0 +1,15 @@
+import type { LiteralFunction } from "@ecosy/core/types";
+/**
+ * Checks whether a value is a function (including async and generator functions).
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a function.
+ *
+ * @example
+ * ```ts
+ * isFunction(() => {}); // true
+ * isFunction(async () => {}); // true
+ * isFunction(42); // false
+ * ```
+ */
+export declare function isFunction(value: unknown): value is LiteralFunction;

package/dist/utilities/is-function.js

@@ -0,0 +1 @@
+"use strict";var t=require("./to-string.js");exports.isFunction=function(n){return"function"==typeof n||["[object Function]","[object AsyncFunction]","[object GeneratorFunction]"].includes(t.toString(n))};

package/dist/utilities/is-function.mjs

@@ -0,0 +1 @@
+import{toString as n}from"./to-string.mjs";function t(t){return"function"==typeof t||["[object Function]","[object AsyncFunction]","[object GeneratorFunction]"].includes(n(t))}export{t as isFunction};

package/dist/utilities/merge.d.ts

@@ -0,0 +1,18 @@
+import { clone } from "./clone";
+/**
+ * Deep merges `target` into `source`. If both are plain objects, properties are merged
+ * recursively. Otherwise, `target` replaces `source`. Prototype-polluting keys
+ * (`__proto__`, `constructor`, `prototype`) are rejected.
+ *
+ * @param source - The base object.
+ * @param target - The object whose values are merged into `source`.
+ * @param cloneDeep - Custom deep clone function (defaults to `clone`).
+ * @returns The merged result.
+ *
+ * @example
+ * ```ts
+ * merge({ a: 1, b: { c: 2 } }, { b: { d: 3 } });
+ * // { a: 1, b: { c: 2, d: 3 } }
+ * ```
+ */
+export declare function merge<AsType>(source: unknown, target: unknown, cloneDeep?: typeof clone): AsType;

package/dist/utilities/merge.js

@@ -0,0 +1 @@
+"use strict";var e=require("./clone.js"),t=require("./object.js");exports.merge=function r(i,c,o=e.clone){if(void 0===c)return o(i);if(t.isLiteralObject(i)&&t.isLiteralObject(c)){const e=Object.assign({},i);return Object.keys(c).forEach(i=>{if(!function(e){return"__proto__"!==e&&"constructor"!==e&&"prototype"!==e}(i))return;const n=e[i],s=c[i];t.isLiteralObject(n)&&t.isLiteralObject(s)?e[i]=r(n,s,o):e[i]=o(s)}),e}return o(c)};

package/dist/utilities/merge.mjs

@@ -0,0 +1 @@
+import{clone as r}from"./clone.mjs";import{isLiteralObject as t}from"./object.mjs";function o(n,e,c=r){if(void 0===e)return c(n);if(t(n)&&t(e)){const r=Object.assign({},n);return Object.keys(e).forEach(n=>{if(!function(r){return"__proto__"!==r&&"constructor"!==r&&"prototype"!==r}(n))return;const i=r[n],f=e[n];t(i)&&t(f)?r[n]=o(i,f,c):r[n]=c(f)}),r}return c(e)}export{o as merge};

package/dist/utilities/object.d.ts

@@ -0,0 +1,43 @@
+import type { LiteralObject, Objectable } from "@ecosy/core/types";
+/**
+ * Checks whether a value is a non-null object.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is of type `object` and is not `null`.
+ */
+export declare function isObject(value: unknown): value is object;
+/**
+ * Checks whether a value is a plain object (created by `{}` or `Object.create(null)`).
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a plain literal object.
+ */
+export declare function isLiteralObject(value: unknown): value is LiteralObject;
+/**
+ * Checks whether a value is a complex (non-array) object, such as a class instance.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a non-array object.
+ */
+export declare function isComplexObject<Target extends LiteralObject>(value: unknown): value is Target;
+/**
+ * Checks whether a value is an object, array, or function.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is "objectable" (object, array, or function).
+ */
+export declare function isObjectable(value: unknown): value is Objectable;
+/**
+ * Type-safe check for own property existence on an object.
+ *
+ * @param obj - The object to check.
+ * @param key - The property key to look for.
+ * @returns `true` if the object has the specified own property.
+ *
+ * @example
+ * ```ts
+ * hasOwnProperty({ a: 1 }, "a"); // true
+ * hasOwnProperty({ a: 1 }, "b"); // false
+ * ```
+ */
+export declare function hasOwnProperty<Obj, Key extends PropertyKey, As = unknown>(obj: Obj, key: Key): obj is Obj & Record<Key, As>;

package/dist/utilities/object.js

@@ -0,0 +1 @@
+"use strict";var t=require("./is-function.js");function r(t){return"object"==typeof t&&null!==t}exports.hasOwnProperty=function(t,r){return Object.prototype.hasOwnProperty.call(t,r)},exports.isComplexObject=function(t){return r(t)&&!Array.isArray(t)},exports.isLiteralObject=function(t){if(!r(t)||Array.isArray(t))return!1;const e=Object.getPrototypeOf(t);return null===e||e===Object.prototype},exports.isObject=r,exports.isObjectable=function(e){return r(e)||t.isFunction(e)};

package/dist/utilities/object.mjs

@@ -0,0 +1 @@
+import{isFunction as r}from"./is-function.mjs";function t(r){return"object"==typeof r&&null!==r}function n(r){if(!t(r)||Array.isArray(r))return!1;const n=Object.getPrototypeOf(r);return null===n||n===Object.prototype}function o(r){return t(r)&&!Array.isArray(r)}function e(n){return t(n)||r(n)}function u(r,t){return Object.prototype.hasOwnProperty.call(r,t)}export{u as hasOwnProperty,o as isComplexObject,n as isLiteralObject,t as isObject,e as isObjectable};

package/dist/utilities/to-string.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns the internal `[[Class]]` tag of a value using `Object.prototype.toString`.
+ *
+ * @param value - The value to get the string tag for.
+ * @returns A string like `"[object Type]"`.
+ *
+ * @example
+ * ```ts
+ * toString([]); // "[object Array]"
+ * toString(null); // "[object Null]"
+ * ```
+ */
+export declare function toString(value: unknown): string;

package/dist/utilities/to-string.js

@@ -0,0 +1 @@
+"use strict";exports.toString=function(t){return Object.prototype.toString.call(t)};

package/dist/utilities/to-string.mjs

@@ -0,0 +1 @@
+function t(t){return Object.prototype.toString.call(t)}export{t as toString};

package/dist/utilities/ucfirst.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Capitalizes the first character of a string.
+ *
+ * @param str - The string to capitalize.
+ * @returns The string with its first character in uppercase.
+ *
+ * @example
+ * ```ts
+ * ucfirst("hello"); // "Hello"
+ * ```
+ */
+export declare function ucfirst<T extends string>(str: T): Capitalize<T>;

package/dist/utilities/ucfirst.js

@@ -0,0 +1 @@
+"use strict";exports.ucfirst=function(t){return t.charAt(0).toUpperCase()+t.slice(1)};

package/dist/utilities/ucfirst.mjs

@@ -0,0 +1 @@
+function e(e){return e.charAt(0).toUpperCase()+e.slice(1)}export{e as ucfirst};

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@ecosy/core",
+  "version": "0.1.0",
+  "description": "Lightweight utilities, pub/sub subscriber, and types for TypeScript applications",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.mjs",
+      "require": "./dist/types/index.js"
+    },
+    "./utilities": {
+      "types": "./dist/utilities/index.d.ts",
+      "import": "./dist/utilities/index.mjs",
+      "require": "./dist/utilities/index.js"
+    },
+    "./subscriber": {
+      "types": "./dist/subscriber.d.ts",
+      "import": "./dist/subscriber.mjs",
+      "require": "./dist/subscriber.js"
+    }
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "eslint src/ && rollup -c",
+    "prepublishOnly": "yarn clean && yarn build",
+    "dev": "rollup -c --watch",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/material-atomic/ecosy-core.git"
+  },
+  "keywords": [
+    "ecosy",
+    "core",
+    "subscriber",
+    "utilities"
+  ],
+  "author": "material-atomic",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@rollup/plugin-terser": "^1.0.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.1",
+    "@typescript-eslint/parser": "^8.57.1",
+    "eslint": "^10.1.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "glob": "^13.0.6",
+    "prettier": "^3.8.1",
+    "rimraf": "^6.1.3",
+    "rollup": "^4.59.1",
+    "typescript": "^5.9.3"
+  }
+}