@runtime-labs/observer-core 1.0.0

package/LICENSE

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

package/Readme.md

@@ -0,0 +1,25 @@
+# @runtime-labs/composable-core
+
+Runtime engine for Vue Composable Observer.
+
+## Installation
+
+```bash
+pnpm add @runtime-labs/composable-core
+```
+
+## Purpose
+
+This package contains the runtime tracking engine used by Vue Composable Observer.
+
+Most users should install:
+
+```bash
+pnpm add -D @runtime-labs/composable-plugin
+```
+
+instead.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,68 @@
+interface ComposableInstance {
+    id: string;
+    name: string;
+    file: string;
+    createdAt: number;
+    state: unknown;
+    dependencyIds?: Set<string> | null;
+    parentId?: string | null;
+    component?: {
+        uid: number;
+        name: string;
+        file?: string;
+    };
+}
+
+declare function registerInstance(record: ComposableInstance): void;
+declare function unregisterInstance(id: string): void;
+declare function getInstances(): ComposableInstance[];
+declare function clearInstances(): void;
+declare function updateInstanceState(id: string, state: unknown): void;
+declare function getInstanceById(id: ComposableInstance['id']): ComposableInstance | null;
+
+type ObserverEvent = {
+    type: 'instance:registered';
+    instanceId: string;
+} | {
+    type: 'instance:unregistered';
+    instanceId: string;
+} | {
+    type: 'instance:stateUpdated';
+    instanceId: string;
+    state: unknown;
+} | {
+    type: 'instance:dependencyRegistered';
+    instanceId: string;
+    dependencyId: string;
+} | {
+    type: 'instance:cleared';
+};
+type Listener = (event: ObserverEvent) => void;
+declare function subscribe(listener: Listener): () => void;
+declare function notifySubscribers(event: ObserverEvent): void;
+
+declare function createObserver(): {
+    getInstances: typeof getInstances;
+    subscribe: typeof subscribe;
+};
+
+declare global {
+    interface Window {
+        __COMPOSABLE_OBSERVER__?: ReturnType<typeof createObserver>;
+    }
+}
+declare function initComposableObserver(): void;
+
+declare function createInstanceId(): `${string}-${string}-${string}-${string}-${string}`;
+declare function createInstance(id: string, name: string, file: string, parentId?: string | null): ComposableInstance;
+
+declare function trackComposable<TArgs extends unknown[], TResult>(name: string, file: string, fn: (...args: TArgs) => TResult): (...args: TArgs) => TResult;
+
+declare function trackStateChanges(state: unknown, callback: () => void): () => void;
+
+declare function getCurrentComposable(): string | null;
+declare function runWithComposable<T>(composableId: string | null, fn: () => T): T;
+
+declare const version = "0.0.0";
+
+export { clearInstances, createInstance, createInstanceId, createObserver, getCurrentComposable, getInstanceById, getInstances, initComposableObserver, notifySubscribers, registerInstance, runWithComposable, subscribe, trackComposable, trackStateChanges, unregisterInstance, updateInstanceState, version };

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+interface ComposableInstance {
+    id: string;
+    name: string;
+    file: string;
+    createdAt: number;
+    state: unknown;
+    dependencyIds?: Set<string> | null;
+    parentId?: string | null;
+    component?: {
+        uid: number;
+        name: string;
+        file?: string;
+    };
+}
+
+declare function registerInstance(record: ComposableInstance): void;
+declare function unregisterInstance(id: string): void;
+declare function getInstances(): ComposableInstance[];
+declare function clearInstances(): void;
+declare function updateInstanceState(id: string, state: unknown): void;
+declare function getInstanceById(id: ComposableInstance['id']): ComposableInstance | null;
+
+type ObserverEvent = {
+    type: 'instance:registered';
+    instanceId: string;
+} | {
+    type: 'instance:unregistered';
+    instanceId: string;
+} | {
+    type: 'instance:stateUpdated';
+    instanceId: string;
+    state: unknown;
+} | {
+    type: 'instance:dependencyRegistered';
+    instanceId: string;
+    dependencyId: string;
+} | {
+    type: 'instance:cleared';
+};
+type Listener = (event: ObserverEvent) => void;
+declare function subscribe(listener: Listener): () => void;
+declare function notifySubscribers(event: ObserverEvent): void;
+
+declare function createObserver(): {
+    getInstances: typeof getInstances;
+    subscribe: typeof subscribe;
+};
+
+declare global {
+    interface Window {
+        __COMPOSABLE_OBSERVER__?: ReturnType<typeof createObserver>;
+    }
+}
+declare function initComposableObserver(): void;
+
+declare function createInstanceId(): `${string}-${string}-${string}-${string}-${string}`;
+declare function createInstance(id: string, name: string, file: string, parentId?: string | null): ComposableInstance;
+
+declare function trackComposable<TArgs extends unknown[], TResult>(name: string, file: string, fn: (...args: TArgs) => TResult): (...args: TArgs) => TResult;
+
+declare function trackStateChanges(state: unknown, callback: () => void): () => void;
+
+declare function getCurrentComposable(): string | null;
+declare function runWithComposable<T>(composableId: string | null, fn: () => T): T;
+
+declare const version = "0.0.0";
+
+export { clearInstances, createInstance, createInstanceId, createObserver, getCurrentComposable, getInstanceById, getInstances, initComposableObserver, notifySubscribers, registerInstance, runWithComposable, subscribe, trackComposable, trackStateChanges, unregisterInstance, updateInstanceState, version };

package/dist/index.mjs

@@ -0,0 +1,240 @@
+import { isRef, isReactive, watch, toValue, getCurrentScope, getCurrentInstance, onScopeDispose } from 'vue';
+
+const listeners = /* @__PURE__ */ new Set();
+function subscribe(listener) {
+  listeners.add(listener);
+  return () => {
+    unsubscribe(listener);
+  };
+}
+function unsubscribe(listener) {
+  listeners.delete(listener);
+}
+function notifySubscribers(event) {
+  listeners.forEach((listener) => listener(event));
+}
+
+const composables = /* @__PURE__ */ new Map();
+function registerInstance(record) {
+  composables.set(record.id, record);
+  notifySubscribers({
+    type: "instance:registered",
+    instanceId: record.id
+  });
+}
+function unregisterInstance(id) {
+  composables.delete(id);
+  notifySubscribers({
+    type: "instance:unregistered",
+    instanceId: id
+  });
+}
+function getInstances() {
+  return [...composables.values()];
+}
+function clearInstances() {
+  composables.clear();
+  notifySubscribers({
+    type: "instance:cleared"
+  });
+}
+function updateInstanceState(id, state) {
+  const instance = composables.get(id);
+  if (instance) {
+    instance.state = state;
+    notifySubscribers({
+      type: "instance:stateUpdated",
+      instanceId: id,
+      state
+    });
+  }
+}
+function updateInstanceComponent(id, component) {
+  const instance = composables.get(id);
+  if (instance) {
+    instance.component = component;
+  }
+}
+function registerDependency(instanceId, dependencyId) {
+  const instance = composables.get(instanceId);
+  if (!instance) return;
+  if (!instance.dependencyIds) {
+    instance.dependencyIds = /* @__PURE__ */ new Set();
+  }
+  instance.dependencyIds.add(dependencyId);
+  notifySubscribers({
+    type: "instance:dependencyRegistered",
+    instanceId,
+    dependencyId
+  });
+}
+function getInstanceById(id) {
+  return composables.get(id) ?? null;
+}
+
+function createObserver() {
+  return {
+    getInstances,
+    subscribe
+  };
+}
+
+function initComposableObserver() {
+  if (typeof window === "undefined") {
+    return;
+  }
+  if (window.__COMPOSABLE_OBSERVER__) {
+    return;
+  }
+  window.__COMPOSABLE_OBSERVER__ = createObserver();
+}
+
+function createInstanceId() {
+  return crypto.randomUUID();
+}
+function createInstance(id, name, file, parentId = null) {
+  return {
+    id: id || createInstanceId(),
+    name,
+    file,
+    createdAt: Date.now(),
+    state: null,
+    dependencyIds: null,
+    parentId
+  };
+}
+
+let currentComposableId = null;
+function setCurrentComposable(id) {
+  currentComposableId = id;
+}
+function getCurrentComposable() {
+  return currentComposableId;
+}
+function runWithComposable(composableId, fn) {
+  const previousComposable = getCurrentComposable();
+  setCurrentComposable(composableId);
+  try {
+    return fn();
+  } finally {
+    setCurrentComposable(previousComposable);
+  }
+}
+
+function createComposableRuntime(name, file, parentId) {
+  const id = createInstanceId();
+  const instance = createInstance(
+    id,
+    name,
+    file,
+    parentId
+  );
+  registerInstance(instance);
+  return {
+    id,
+    instance,
+    updateState(state) {
+      return updateInstanceState(id, state);
+    },
+    dispose() {
+      unregisterInstance(id);
+    }
+  };
+}
+
+function trackStateChanges(state, callback) {
+  const stops = [];
+  function storeStop(stop) {
+    stops.push(stop);
+  }
+  function track(value) {
+    if (isRef(value) || isReactive(value)) {
+      storeStop(
+        watch(
+          () => toValue(value),
+          () => callback(),
+          {
+            deep: true,
+            flush: "post"
+          }
+        )
+      );
+      return;
+    }
+    if (typeof value === "object" && value !== null) {
+      for (const nested of Object.values(value)) {
+        track(nested);
+      }
+    }
+  }
+  track(state);
+  return () => {
+    for (const stop of stops) {
+      stop();
+    }
+  };
+}
+
+function trackComposable(name, file, fn) {
+  return (...args) => {
+    const parentComposableId = getCurrentComposable();
+    const runtime = createComposableRuntime(
+      name,
+      file,
+      parentComposableId
+    );
+    if (parentComposableId && parentComposableId !== runtime.id) {
+      registerDependency(
+        parentComposableId,
+        runtime.id
+      );
+    }
+    const state = runWithComposable(
+      runtime.id,
+      () => fn(...args)
+    );
+    runtime.updateState(state);
+    const stopTracking = trackStateChanges(
+      state,
+      () => {
+        notifySubscribers({
+          type: "instance:stateUpdated",
+          instanceId: runtime.id,
+          state
+        });
+      }
+    );
+    const scope = getCurrentScope();
+    const vm = getCurrentInstance();
+    if (vm && !parentComposableId) {
+      updateInstanceComponent(
+        runtime.id,
+        {
+          uid: vm.uid,
+          name: vm.type.__name ?? vm.type.name ?? "Anonymous",
+          file: vm.type.__file
+        }
+      );
+    }
+    if (scope) {
+      onScopeDispose(() => {
+        {
+          console.log(`Unregistering composable instance: ${runtime.instance.name} (ID: ${runtime.instance.id})`);
+        }
+        stopTracking();
+        runtime.dispose();
+      });
+    } else {
+      {
+        console.warn(
+          `Composable instance "${runtime.instance.name}" (ID: ${runtime.instance.id}) is not registered to any scope. It will not be automatically unregistered and may lead to memory leaks.`
+        );
+      }
+    }
+    return state;
+  };
+}
+
+const version = "0.0.0";
+
+export { clearInstances, createInstance, createInstanceId, createObserver, getCurrentComposable, getInstanceById, getInstances, initComposableObserver, notifySubscribers, registerInstance, runWithComposable, subscribe, trackComposable, trackStateChanges, unregisterInstance, updateInstanceState, version };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@runtime-labs/observer-core",
+  "version": "1.0.0",
+  "description": "Runtime engine for observing Vue composables and tracking their relationships.",
+  "type": "module",
+  "author": {
+    "name": "Anton Gor",
+    "email": "anton-gor-dev@hotmail.com"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/runtime-labs/vue-composable-observer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/runtime-labs/vue-composable-observer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/runtime-labs/vue-composable-observer/issues"
+  },
+  "keywords": [
+    "vue",
+    "composable",
+    "runtime",
+    "observability",
+    "debugging",
+    "devtools",
+    "vue3"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "vue": "^3.5.0"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "dev": "unbuild --stub",
+    "pack": "pnpm pack"
+  }
+}