rc-js-util-globals - npm Package Compare versions

Comparing version 1.0.0 to 2.0.0

index.d.ts

 /**
- * This can be set in dead code removal tools to trim debug code.
+ * @public
+ * A weakmap store available in debug contexts only.
  */
-declare const DEBUG_MODE: boolean;
+export interface IDebugWeakStore<T>
+{
+    setValue(key: object, value: T): void;
+    getValue(key: object): T;
+}
+
 /**
- * Prevents hitting assert / error breakpoints, useful when debugging tests.
+ * @public
+ * See {@link ISharedObject}.
  */
-declare const DEBUG_DISABLE_BREAKPOINT: boolean;
+export interface IDebugSharedObject
+{
+    isStatic: boolean;
+    getPtr(): number;
+}
+
 /**
- * Enable verbose logging.
+ * @public
  */
-declare const DEBUG_VERBOSE: boolean;
+export type TDebugListener<K extends string, TArgs extends unknown[]> = {
+    [P in K]?: (...args: TArgs) => void;
+};
+
 /**
- * Disable debug checks that do not run in constant time.
+ * @public
+ * Like {@link IBroadcastEvent} but without holding strong references. Available in debug contexts only.
  */
-declare const DEBUG_DISABLE_EXPENSIVE_CHECKS: boolean;
+export interface IDebugWeakBroadcastEvent<K extends string, TArgs extends unknown[]>
+{
+    /**
+     * The listener will be retained as long as the key hasn't been garbage collected.
+     * @param key - Stronlgy refrenced.
+     * @param listener - Weakly referenced.
+     */
+    addListener(listener: TDebugListener<K, TArgs>): void;
+    removeListener(listener: TDebugListener<K, TArgs>): void;
+    emit(...args: TArgs): void;
+}
+
 /**
- * Checks that are a wee bit autistic.
+ * @public
+ * Wrapper of {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry|FinalizationRegistry} for shared objects, useful for checking if the shared object was properly disposed.
+ * Available in debug contexts only.
+ *
+ * @remarks
+ * The FinalizationRegistry's behavior is very unpredictable (and where exceptions are concerned, seemingly prone to race conditions),
+ * by default suspected leaks are not reported. You can opt-in to these checks by enabling `DEBUG_PEDANTIC` (error on leak) or `DEBUG_VERBOSE` (log on error).
  */
-declare const DEBUG_PEDANTIC: boolean;
+export interface IDebugSharedObjectLifeCycleChecks
+{
+    registerFinalizationCheck(sharedObject: IDebugSharedObject): void;
+    markReadyForFinalize(sharedObject: IDebugSharedObject): void;
+}
+
 /**
- * Enable verbose logging of memory allocations, very chatty.
+ * @public
+ * Factory for creating proxy objects that can be invalidated later. Once invalidated any property
+ * read that wasn't explicity marked safe will cause a debug error. Available in debug contexts only.
  */
-declare const DEBUG_VERBOSE_MEMORY_MANAGEMENT: boolean;
+export interface IDebugProtectedView<_T extends object>
+{
+    /**
+     * Invalidates all previous views.
+     */
+    invalidate(): void;
+    /**
+     * Create a proxy to the view, if invalidate called then access of non `safeKeys` will cause a debug error.
+     */
+    createProtectedView<T extends object>(view: T): T;
+}
 
-declare namespace RcJsUtilDebug
+declare global
 {
-    export interface IStore<T>
-    {
-        setValue(listener: object, value: T): void;
-        getValue(listener: object): T;
-    }
+    /**
+     * This can be set in dead code removal tools to trim debug code.
+     */
+    const DEBUG_MODE: boolean;
+    /**
+     * Prevents hitting assert / error breakpoints, useful when debugging tests.
+     */
+    const DEBUG_DISABLE_BREAKPOINT: boolean;
+    /**
+     * Enable verbose logging.
+     */
+    const DEBUG_VERBOSE: boolean;
+    /**
+     * Disable debug checks that do not run in constant time.
+     */
+    const DEBUG_DISABLE_EXPENSIVE_CHECKS: boolean;
+    /**
+     * Checks that are a wee bit autistic.
+     */
+    const DEBUG_PEDANTIC: boolean;
+    /**
+     * Enable verbose logging of memory allocations, very chatty.
+     */
+    const DEBUG_VERBOSE_MEMORY_MANAGEMENT: boolean;
 
-    export interface ISharedObject
+    /**
+     * Debug state, only present in debug builds. All accesses should be hidden behind DEBUG_MODE checks.
+     */
+    namespace RcJsUtilDebug
     {
-        isStatic: boolean;
-        getPtr(): number;
+        export const onAllocate: IDebugWeakBroadcastEvent<"debugOnAllocate", []>;
+        export const protectedViews: IDebugWeakStore<IDebugProtectedView<object>>;
+        export const error: (message: string) => void;
+        export const sharedObjectLifeCycleChecks: IDebugSharedObjectLifeCycleChecks;
     }
-
-    export type TListener<TArgs extends unknown[]> = (...args: TArgs) => void;
-
-    export interface IMulticastEvent<TArgs extends unknown[]>
-    {
-        addListener(listener: TListener<TArgs>): void;
-        removeListener(listener: TListener<TArgs>): void;
-        emit(...args: TArgs): void;
-    }
-
-    export interface IDebugSharedObjectLifeCycleChecks
-    {
-        registerFinalizationCheck(sharedObject: ISharedObject): void;
-        markReadyForFinalize(sharedObject: ISharedObject): void;
-    }
-
-    interface IDebugProtectedView<_T extends object>
-    {
-        /**
-         * Invalidates all previous views.
-         */
-        invalidate(): void;
-        /**
-         * Create a proxy to the view, if invalidate called then access of non `safeKeys` will cause a debug error.
-         */
-        createProtectedView<T extends object>(view: T): T;
-    }
-
-    export const onAllocate: IMulticastEvent<[]>;
-    export const protectedViews: IStore<IDebugProtectedView<object>>;
-    export const error: (message: string) => boolean;
-    export const sharedObjectLifeCycleChecks: IDebugSharedObjectLifeCycleChecks;
 }

package.json

 {
   "name": "rc-js-util-globals",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "license": "MIT"
 }

No alert changes

Improved metrics

Total package byte prevSize

3722

increased by69.41%

Lines of code

106

increased by65.63%

No dependency changes