@aweebit/react-essentials 0.9.0 → 0.10.0

package/README.md

@@ -2,22 +2,15 @@
 
 [![NPM Version](https://img.shields.io/npm/v/%40aweebit%2Freact-essentials)](https://www.npmjs.com/package/@aweebit/react-essentials)
 
-### Requirements
-
-- React ≥ 18
-- TypeScript ≥ 5.4
-
-### Functions
-
 - [useEventListener()](#useeventlistener)
 - [useReducerWithDeps()](#usereducerwithdeps)
 - [useStateWithDeps()](#usestatewithdeps)
 - [createSafeContext()](#createsafecontext)
 
-### Types
+### Requirements
 
-- [UseEventListener](#useeventlistener-1)
-- [SafeContext](#safecontext)
+- React ≥ 18
+- TypeScript ≥ 5.4
 
 ## useEventListener
 
@@ -25,7 +18,7 @@
 const useEventListener: UseEventListener;
 ```
 
-Defined in: [hooks/useEventListener.ts:135](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L135)
+Defined in: [hooks/useEventListener.ts:135](https://github.com/aweebit/react-essentials/blob/v0.10.0/src/hooks/useEventListener.ts#L135)
 
 Adds `handler` as a listener for the event `eventName` of `target` with the
 provided `options` applied
@@ -76,7 +69,7 @@ function useReducerWithDeps<S, A>(
 ): [S, ActionDispatch<A>];
 ```
 
-Defined in: [hooks/useReducerWithDeps.ts:59](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useReducerWithDeps.ts#L59)
+Defined in: [hooks/useReducerWithDeps.ts:59](https://github.com/aweebit/react-essentials/blob/v0.10.0/src/hooks/useReducerWithDeps.ts#L59)
 
 `useReducer` hook with an additional dependency array `deps` that resets the
 state to `initialState` when dependencies change
@@ -219,7 +212,7 @@ function useStateWithDeps<S>(
 ): [S, Dispatch<SetStateAction<S>>];
 ```
 
-Defined in: [hooks/useStateWithDeps.ts:62](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useStateWithDeps.ts#L62)
+Defined in: [hooks/useStateWithDeps.ts:62](https://github.com/aweebit/react-essentials/blob/v0.10.0/src/hooks/useStateWithDeps.ts#L62)
 
 `useState` hook with an additional dependency array `deps` that resets the
 state to `initialState` when dependencies change
@@ -348,10 +341,12 @@ Dependencies that reset the state to `initialState`
 ```ts
 function createSafeContext<T>(): <DisplayName>(
   displayName,
-) => SafeContext<DisplayName, T>;
+) => { [K in `${string}Context`]: Context<T> } & {
+  [K in `use${string}`]: () => T;
+};
 ```
 
-Defined in: [misc/createSafeContext.ts:95](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/misc/createSafeContext.ts#L95)
+Defined in: [misc/createSafeContext.ts:62](https://github.com/aweebit/react-essentials/blob/v0.10.0/src/misc/createSafeContext.ts#L62)
 
 For a given type `T`, returns a function that produces both a context of that
 type and a hook that returns the current context value if one was provided,
@@ -437,7 +432,7 @@ A function that accepts a single string argument `displayName` (e.g.
   current context value if one was provided, or throws an error otherwise
 
 ```ts
-<DisplayName>(displayName): SafeContext<DisplayName, T>;
+<DisplayName>(displayName): { [K in `${string}Context`]: Context<T> } & { [K in `use${string}`]: () => T };
 ```
 
 #### Type Parameters
@@ -486,11 +481,7 @@ A function that accepts a single string argument `displayName` (e.g.
 
 #### Returns
 
-[`SafeContext`](#safecontext)\<`DisplayName`, `T`\>
-
-### See
-
-[`SafeContext`](#safecontext)
+``{ [K in `${string}Context`]: Context<T> }`` & ``{ [K in `use${string}`]: () => T }``
 
 ---
 
@@ -502,7 +493,7 @@ type UseEventListener = UseEventListenerWithImplicitWindowTarget &
   UseEventListenerWithAnyExplicitTarget;
 ```
 
-Defined in: [hooks/useEventListener.ts:12](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L12)
+Defined in: [hooks/useEventListener.ts:12](https://github.com/aweebit/react-essentials/blob/v0.10.0/src/hooks/useEventListener.ts#L12)
 
 The type of [`useEventListener`](#useeventlistener-1)
 
@@ -521,7 +512,7 @@ The type of [`useEventListener`](#useeventlistener-1)
 type UseEventListenerWithImplicitWindowTarget = <K>(...args) => void;
 ```
 
-Defined in: [hooks/useEventListener.ts:21](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L21)
+Defined in: [hooks/useEventListener.ts:21](https://github.com/aweebit/react-essentials/blob/v0.10.0/src/hooks/useEventListener.ts#L21)
 
 ### Type Parameters
 
@@ -589,7 +580,7 @@ type UseEventListenerWithExplicitGlobalTarget =
     UseEventListenerWithExplicitTarget<MathMLElement, MathMLElementEventMap>;
 ```
 
-Defined in: [hooks/useEventListener.ts:32](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L32)
+Defined in: [hooks/useEventListener.ts:32](https://github.com/aweebit/react-essentials/blob/v0.10.0/src/hooks/useEventListener.ts#L32)
 
 ### See
 
@@ -606,7 +597,7 @@ type UseEventListenerWithExplicitTarget<Target, EventMap> = <T, K>(
 ) => void;
 ```
 
-Defined in: [hooks/useEventListener.ts:44](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L44)
+Defined in: [hooks/useEventListener.ts:44](https://github.com/aweebit/react-essentials/blob/v0.10.0/src/hooks/useEventListener.ts#L44)
 
 ### Type Parameters
 
@@ -705,7 +696,7 @@ type UseEventListenerWithAnyExplicitTarget = UseEventListenerWithExplicitTarget<
 >;
 ```
 
-Defined in: [hooks/useEventListener.ts:56](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L56)
+Defined in: [hooks/useEventListener.ts:56](https://github.com/aweebit/react-essentials/blob/v0.10.0/src/hooks/useEventListener.ts#L56)
 
 ### See
 
@@ -726,7 +717,7 @@ type UseEventListenerWithImplicitWindowTargetArgs<K> =
     : never;
 ```
 
-Defined in: [hooks/useEventListener.ts:64](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L64)
+Defined in: [hooks/useEventListener.ts:64](https://github.com/aweebit/react-essentials/blob/v0.10.0/src/hooks/useEventListener.ts#L64)
 
 ### Type Parameters
 
@@ -771,7 +762,7 @@ type UseEventListenerWithExplicitTargetArgs<EventMap, T, K> = [
 ];
 ```
 
-Defined in: [hooks/useEventListener.ts:78](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/hooks/useEventListener.ts#L78)
+Defined in: [hooks/useEventListener.ts:78](https://github.com/aweebit/react-essentials/blob/v0.10.0/src/hooks/useEventListener.ts#L78)
 
 ### Type Parameters
 
@@ -809,95 +800,3 @@ Defined in: [hooks/useEventListener.ts:78](https://github.com/aweebit/react-esse
 ### See
 
 [`useEventListener`](#useeventlistener-1)
-
----
-
-## SafeContext
-
-```ts
-type SafeContext<DisplayName, T> = {
-  [K in `${DisplayName}Context`]: RestrictedContext<T>;
-} & { [K in `use${DisplayName}`]: () => T };
-```
-
-Defined in: [misc/createSafeContext.ts:13](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/misc/createSafeContext.ts#L13)
-
-The return type of [`createSafeContext`](#createsafecontext)
-
-### Type Parameters
-
-<table>
-<thead>
-<tr>
-<th>Type Parameter</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>
-
-`DisplayName` _extends_ `string`
-
-</td>
-</tr>
-<tr>
-<td>
-
-`T`
-
-</td>
-</tr>
-</tbody>
-</table>
-
-### See
-
-[`createSafeContext`](#createsafecontext),
-[`RestrictedContext`](#restrictedcontext)
-
----
-
-## RestrictedContext
-
-```ts
-type RestrictedContext<T> =
-  Context<T> extends Provider<T>
-    ? {
-        Provider: Provider<T>;
-        displayName: string;
-      } & Provider<T>
-    : {
-        Provider: Provider<T>;
-        displayName: string;
-      };
-```
-
-Defined in: [misc/createSafeContext.ts:31](https://github.com/aweebit/react-essentials/blob/v0.9.0/src/misc/createSafeContext.ts#L31)
-
-A React context with a required `displayName` and the obsolete `Consumer`
-property purposefully omitted so that it is impossible to pass the context
-as an argument to `useContext` or `use` (the hook produced with
-[`createSafeContext`](#createsafecontext) should be used instead)
-
-### Type Parameters
-
-<table>
-<thead>
-<tr>
-<th>Type Parameter</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>
-
-`T`
-
-</td>
-</tr>
-</tbody>
-</table>
-
-### See
-
-[`createSafeContext`](#createsafecontext)

package/dist/misc/createSafeContext.d.ts

@@ -1,33 +1,5 @@
-import { type Context, type Provider } from 'react';
+import { type Context } from 'react';
 import type { ArgumentFallback } from '../utils.js';
-/**
- * The return type of {@linkcode createSafeContext}
- *
- * @see
- * {@linkcode createSafeContext},
- * {@linkcode RestrictedContext}
- */
-export type SafeContext<DisplayName extends string, T> = {
-    [K in `${DisplayName}Context`]: RestrictedContext<T>;
-} & {
-    [K in `use${DisplayName}`]: () => T;
-};
-/**
- * A React context with a required `displayName` and the obsolete `Consumer`
- * property purposefully omitted so that it is impossible to pass the context
- * as an argument to `useContext` or `use` (the hook produced with
- * {@linkcode createSafeContext} should be used instead)
- *
- * @see
- * {@linkcode createSafeContext}
- */
-export type RestrictedContext<T> = Context<T> extends Provider<T> ? {
-    Provider: Provider<T>;
-    displayName: string;
-} & Provider<T> : {
-    Provider: Provider<T>;
-    displayName: string;
-};
 /**
  * For a given type `T`, returns a function that produces both a context of that
  * type and a hook that returns the current context value if one was provided,
@@ -83,9 +55,6 @@ export type RestrictedContext<T> = Context<T> extends Provider<T> ? {
  * - ``` `${displayName}Context` ``` (e.g. `DirectionContext`): the context
  * - ``` `use${displayName}` ``` (e.g. `useDirection`): a hook that returns the
  *   current context value if one was provided, or throws an error otherwise
- *
- * @see
- * {@linkcode SafeContext}
  */
-export declare function createSafeContext<T = never>(): <DisplayName extends string>(displayName: [T] extends [never] ? never : ArgumentFallback<DisplayName, never, string>) => SafeContext<DisplayName, T>;
+export declare function createSafeContext<T = never>(): <DisplayName extends string>(displayName: [T] extends [never] ? never : ArgumentFallback<DisplayName, never, string>) => { [K in `${DisplayName}Context`]: Context<T>; } & { [K in `use${DisplayName}`]: () => T; };
 //# sourceMappingURL=createSafeContext.d.ts.map

package/dist/misc/createSafeContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createSafeContext.d.ts","sourceRoot":"","sources":["../../src/misc/createSafeContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAA6B,MAAM,OAAO,CAAC;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,CAAC,WAAW,SAAS,MAAM,EAAE,CAAC,IAAI;KACtD,CAAC,IAAI,GAAG,WAAW,SAAS,GAAG,iBAAiB,CAAC,CAAC,CAAC;CACrD,GAAG;KACD,CAAC,IAAI,MAAM,WAAW,EAAE,GAAG,MAAM,CAAC;CACpC,CAAC;AAEF;;;;;;;;GAQG;AAIH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC7B,OAAO,CAAC,CAAC,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,GAC1B;IAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,GAC5D;IAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,KAAK,MACjC,WAAW,SAAS,MAAM,EAChC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC5B,KAAK,GACL,gBAAgB,CAAC,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC,KAC/C,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC,CAsB/B"}
+{"version":3,"file":"createSafeContext.d.ts","sourceRoot":"","sources":["../../src/misc/createSafeContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAA6B,MAAM,OAAO,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,KAAK,MACjC,WAAW,SAAS,MAAM,EAChC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC5B,KAAK,GACL,gBAAgB,CAAC,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC,KAC/C,GAAG,CAAC,IAAI,GAAG,WAAW,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,GAAE,GAAG,GACjD,CAAC,IAAI,MAAM,WAAW,EAAE,GAAG,MAAM,CAAC,GACpC,CAsBF"}

package/dist/misc/createSafeContext.js

@@ -55,9 +55,6 @@ const moValueSymbol = Symbol('noValue');
  * - ``` `${displayName}Context` ``` (e.g. `DirectionContext`): the context
  * - ``` `use${displayName}` ``` (e.g. `useDirection`): a hook that returns the
  *   current context value if one was provided, or throws an error otherwise
- *
- * @see
- * {@linkcode SafeContext}
  */
 export function createSafeContext() {
     return (displayName) => {

package/dist/misc/createSafeContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"createSafeContext.js","sourceRoot":"","sources":["../../src/misc/createSafeContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAG/E,MAAM,aAAa,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;AAgCxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,CACL,WAEgD,EACnB,EAAE;QAC/B,MAAM,WAAW,GAAG,GAAG,WAA0B,SAAkB,CAAC;QACpE,MAAM,QAAQ,GAAG,MAAM,WAA0B,EAAW,CAAC;QAE7D,MAAM,OAAO,GAAG,aAAa,CAA2B,aAAa,CAAC,CAAC;QACvE,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC;QAElC,OAAO;YACL,CAAC,WAAW,CAAC,EAAE,OAA+B;YAC9C,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE;gBACf,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;gBAClC,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;oBAC5B,MAAM,IAAI,KAAK,CAAC,MAAM,WAAW,qBAAqB,CAAC,CAAC;gBAC1D,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC;SAKF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"createSafeContext.js","sourceRoot":"","sources":["../../src/misc/createSafeContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGhE,MAAM,aAAa,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,CACL,WAEgD,EAGhD,EAAE;QACF,MAAM,WAAW,GAAG,GAAG,WAA0B,SAAkB,CAAC;QACpE,MAAM,QAAQ,GAAG,MAAM,WAA0B,EAAW,CAAC;QAE7D,MAAM,OAAO,GAAG,aAAa,CAA2B,aAAa,CAAC,CAAC;QACvE,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC;QAElC,OAAO;YACL,CAAC,WAAW,CAAC,EAAE,OAAqB;YACpC,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE;gBACf,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;gBAClC,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;oBAC5B,MAAM,IAAI,KAAK,CAAC,MAAM,WAAW,qBAAqB,CAAC,CAAC;gBAC1D,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC;SAKF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aweebit/react-essentials",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "repository": "github:aweebit/react-essentials",
   "main": "dist/index.js",

package/src/misc/createSafeContext.ts

@@ -1,38 +1,8 @@
-import { type Context, type Provider, createContext, useContext } from 'react';
+import { type Context, createContext, useContext } from 'react';
 import type { ArgumentFallback } from '../utils.js';
 
 const moValueSymbol = Symbol('noValue');
 
-/**
- * The return type of {@linkcode createSafeContext}
- *
- * @see
- * {@linkcode createSafeContext},
- * {@linkcode RestrictedContext}
- */
-export type SafeContext<DisplayName extends string, T> = {
-  [K in `${DisplayName}Context`]: RestrictedContext<T>;
-} & {
-  [K in `use${DisplayName}`]: () => T;
-};
-
-/**
- * A React context with a required `displayName` and the obsolete `Consumer`
- * property purposefully omitted so that it is impossible to pass the context
- * as an argument to `useContext` or `use` (the hook produced with
- * {@linkcode createSafeContext} should be used instead)
- *
- * @see
- * {@linkcode createSafeContext}
- */
-// The type is conditional so that both React 18 and 19 are correctly supported.
-// The code duplication is necessary for the type to be displayed correctly by
-// TypeDoc.
-export type RestrictedContext<T> =
-  Context<T> extends Provider<T>
-    ? { Provider: Provider<T>; displayName: string } & Provider<T>
-    : { Provider: Provider<T>; displayName: string };
-
 /**
  * For a given type `T`, returns a function that produces both a context of that
  * type and a hook that returns the current context value if one was provided,
@@ -88,16 +58,15 @@ export type RestrictedContext<T> =
  * - ``` `${displayName}Context` ``` (e.g. `DirectionContext`): the context
  * - ``` `use${displayName}` ``` (e.g. `useDirection`): a hook that returns the
  *   current context value if one was provided, or throws an error otherwise
- *
- * @see
- * {@linkcode SafeContext}
  */
 export function createSafeContext<T = never>() {
   return <DisplayName extends string>(
     displayName: [T] extends [never]
       ? never
       : ArgumentFallback<DisplayName, never, string>,
-  ): SafeContext<DisplayName, T> => {
+  ): { [K in `${DisplayName}Context`]: Context<T> } & {
+    [K in `use${DisplayName}`]: () => T;
+  } => {
     const contextName = `${displayName as DisplayName}Context` as const;
     const hookName = `use${displayName as DisplayName}` as const;
 
@@ -105,7 +74,7 @@ export function createSafeContext<T = never>() {
     Context.displayName = contextName;
 
     return {
-      [contextName]: Context as RestrictedContext<T>,
+      [contextName]: Context as Context<T>,
       [hookName]: () => {
         const value = useContext(Context);
         if (value === moValueSymbol) {
@@ -114,7 +83,7 @@ export function createSafeContext<T = never>() {
         return value;
       },
     } as {
-      [K in typeof contextName]: RestrictedContext<T>;
+      [K in typeof contextName]: Context<T>;
     } & {
       [K in typeof hookName]: () => T;
     };