scope-state 0.1.0

package/dist/src/types/index.d.ts

@@ -0,0 +1,175 @@
+/// <reference types="node" />
+export interface CustomMethods<T> {
+    /**
+     * Merges new properties into the current object without removing existing properties.
+     * Triggers reactive updates for all components using this data.
+     */
+    $merge: (newProps: Partial<T>) => T;
+    /**
+     * Completely replaces the current object with new properties.
+     * Removes all existing properties and adds only the new ones.
+     */
+    $set: (newProps: Partial<T>) => T;
+    /**
+     * Deletes one or more properties from the current object.
+     * ⚠️ DANGER: This completely removes properties from the object.
+     */
+    $delete: (keys: keyof T | Array<keyof T>) => T;
+    /**
+     * Updates a specific property using an updater function.
+     */
+    $update: <K extends keyof T>(key: K, updater: (value: T[K]) => T[K]) => T;
+    /**
+     * Resets the object to its initial state as defined in store.ts.
+     */
+    $reset: () => T;
+    /**
+     * Returns a pure JavaScript object without proxies or custom methods.
+     */
+    raw: () => DeepUnproxied<T>;
+}
+export interface CustomArrayMethods<T> {
+    /**
+     * Adds one or more elements to the end of an array and returns the new length.
+     */
+    push: (...items: T[]) => number;
+    /**
+     * Changes the contents of an array by removing or replacing existing elements
+     * and/or adding new elements in place.
+     */
+    splice: (start: number, deleteCount?: number, ...items: T[]) => T[];
+    /**
+     * Returns a pure JavaScript array without proxies or custom methods.
+     */
+    raw: () => DeepUnproxied<T[]>;
+}
+export type EnhancedObject<T> = T & CustomMethods<T>;
+export type EnhancedArray<T> = Array<T> & CustomArrayMethods<T>;
+export type DeepUnproxied<T> = T extends Array<infer U> ? DeepUnproxied<U>[] : T extends object ? {
+    [K in keyof T]: T[K] extends Function ? never : DeepUnproxied<T[K]>;
+} : T;
+/**
+ * The main type for the global store that adds custom methods to all nested objects and arrays.
+ */
+export type StoreType<T> = {
+    [K in keyof T]: T[K] extends Array<infer U> ? EnhancedArray<U> : T[K] extends object ? StoreType<T[K]> & CustomMethods<T[K]> : T[K];
+} & CustomMethods<T>;
+export interface ProxyConfig {
+    /** Whether state tracking is enabled.
+     * NOTE: Setting to ```false``` will disable reactive updates for all states.
+     *  @default true */
+    enabled: boolean;
+    /** The maximum depth of nested objects to proxy.
+     *  Higher values will increase memory usage (intended for large, complex state objects where you want to track all properties).
+     *  Lower values will reduce memory usage (intended for simple state objects where you only want to track a few properties).
+     *  In general, Scope works best when tracking shallow state objects.
+     *  @summary { user: { name: string, age: number }, todos: Array<{ id: number, text: string, done: boolean }> }
+     *  @default 5
+     */
+    maxDepth: number;
+    /** Whether selective proxying is enabled.
+     *  @default false @example true
+     */
+    selectiveProxying: boolean;
+    trackPathUsage: boolean;
+    lazyProxyDeepObjects: boolean;
+    preProxyPaths: string[];
+    maxPathLength: number;
+    smartArrayTracking: boolean;
+    nonBlockingProxyCreation: boolean;
+    batchSize: number;
+    prioritizeUIObjects: boolean;
+    maxQueueSize: number;
+    memoryLimit: boolean;
+    memoryThreshold: number;
+    targetMemoryUsage: number;
+    proxyEvictionStrategy: 'lru';
+    disableProxyingUnderPressure: boolean;
+    maxProxyCacheSize: number;
+    ultraSelectiveProxying: boolean;
+    proxySelectorPaths: boolean;
+    forceMemoryCheck: boolean;
+    aggressiveMemoryManagement: boolean;
+    priorityPaths: string[];
+}
+export interface MonitoringConfig {
+    enabled: boolean;
+    verboseLogging: boolean;
+    logSubscriptions: boolean;
+    logProxyCreation: boolean;
+    logStateChanges: boolean;
+    logPersistence: boolean;
+    logTimings: boolean;
+    autoLeakDetection: boolean;
+    leakDetectionInterval: number;
+    leakAlertThreshold: number;
+    leakScanMinimumRenderCycles: number;
+}
+export interface PersistenceConfig {
+    /** Whether persistence is enabled */
+    enabled: boolean;
+    /** The paths to persist. Set to ```undefined``` to persist all paths.
+     *  @default undefined @example ['user.name', 'theme']
+     */
+    paths: string[] | undefined;
+    /** The paths to never persist to storage.
+     *  @default [] @example ['user.password', 'world_map.large_array_of_all_cities']
+     */
+    blacklist: string[];
+    /** The delay in milliseconds before persisting changes.
+     * All changes are non-blocking and will be persisted in the background.
+     *  @default 300
+     */
+    batchDelay: number;
+}
+export interface ScopeConfig<T extends Record<string, any> = Record<string, any>> {
+    /** Initial store state */
+    initialState?: T;
+    /** Proxy configuration */
+    proxy?: Partial<ProxyConfig>;
+    /** Monitoring and debugging configuration */
+    monitoring?: Partial<MonitoringConfig>;
+    /** Persistence configuration */
+    persistence?: Partial<PersistenceConfig>;
+    /** Storage instance for persistence */
+    storage?: any;
+}
+export type Listener = () => void;
+export type PathListeners = Map<string, Set<Listener>>;
+export interface MonitoringStats {
+    proxyCount: number;
+    totalSubscriptionsCreated: number;
+    totalSubscriptionsRemoved: number;
+    activeSubscriptions: number;
+    pathSubscriptionCounts: Record<string, number>;
+    timings: {
+        lastNotifyTime: number;
+        lastPersistTime: number;
+        averageNotifyTime: number;
+        averagePersistTime: number;
+        notifyTimeTotal: number;
+        persistTimeTotal: number;
+        notifyCount: number;
+        persistCount: number;
+    };
+    leakDetection: {
+        lastCheckTime: number;
+        totalChecks: number;
+        leaksDetected: number;
+        renderCyclesSinceCheck: number;
+        isLeakDetectionRunning: boolean;
+        leakDetectionTimer: NodeJS.Timeout | null;
+    };
+}
+export interface ProxyCacheStats {
+    cacheHits: number;
+    cacheMisses: number;
+    totalProxiesCreated: number;
+    activeCachedProxies: number;
+}
+export interface PathUsageStats {
+    accessedPaths: Set<string>;
+    modifiedPaths: Set<string>;
+    subscribedPaths: Set<string>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/src/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,69 @@
+{
+	"name": "scope-state",
+	"version": "0.1.0",
+	"description": "Scope State is the simplest global state system for React that you've ever used — no boilerplate, no spreading, no mental overhead.",
+	"main": "dist/index.js",
+	"module": "dist/index.esm.js",
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist/index.js",
+		"dist/index.esm.js",
+		"dist/index.d.ts",
+		"dist/src",
+		"README.md"
+	],
+	"scripts": {
+		"build": "rollup -c",
+		"dev": "rollup -c -w",
+		"test": "jest",
+		"test:watch": "jest --watch",
+		"type-check": "tsc --noEmit",
+		"lint": "eslint src --ext .ts,.tsx",
+		"prepublishOnly": "npm run build"
+	},
+	"keywords": [
+		"react",
+		"state-management",
+		"global-state",
+		"reactive",
+		"proxy",
+		"hooks",
+		"signals",
+		"state",
+		"persistence",
+		"redux",
+		"zustand",
+		"mobx",
+		"xstate",
+		"recoil",
+		"jotai",
+		"valtio",
+		"next"
+	],
+	"author": "Dalton Letorney",
+	"license": "MIT",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/daltonlet/scope-state.git"
+	},
+	"peerDependencies": {
+		"react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+	},
+	"devDependencies": {
+		"@rollup/plugin-commonjs": "^24.1.0",
+		"@rollup/plugin-node-resolve": "^15.3.1",
+		"@rollup/plugin-typescript": "^11.1.6",
+		"@types/jest": "^29.5.14",
+		"@types/node": "^18.19.111",
+		"@types/react": "^18.3.23",
+		"jest": "^29.7.0",
+		"rollup": "^3.29.5",
+		"tslib": "^2.8.1",
+		"typescript": "^4.9.5"
+	},
+	"dependencies": {
+		"localforage": "^1.10.0",
+		"localforage-driver-memory": "^1.0.5"
+	}
+}