@fane_the_divine/react-signal 0.0.0

package/README.md

@@ -0,0 +1,135 @@
+# react-signal
+
+在react里使用signal, API参考solid,使用方法见[demo](src/index.tsx).
+
+## API介绍
+
+### defineComponent
+
+```tsx
+type CompProps = {
+  num: number
+}
+const Comp = defineComponent<CompProps>((props) => {
+  return () => <span>{props().num}</span>
+})
+```
+
+defineComponent接受一个setup函数 这个函数在组件整个生命周期内只执行一次(不包括热重载)  
+setup应当返回一个render函数 这个函数会执行多次
+
+### createSignal
+
+创建signal
+
+```ts
+const [count, setCount] = createSignal(0)
+
+// 使用signal
+count()
+
+// 不具有响应性地获取signal里的值
+count.value
+```
+
+可以在任何位置使用createSignal
+
+### createMemo
+
+创建一个派生signal
+
+```ts
+// 参数为上一次的memo值
+const double = createMemo((prev) => {
+  return count() * 2
+  // 第二个参数是自定义的比较眼熟
+}, Object.is)
+
+// 访问其值
+double()
+
+// 不具有响应性地获取其值
+double.value
+```
+
+可以在任何位置使用createMemo  
+派生signal会记录当前值是否过期 直到值被访问的时候才实际进行计算
+
+### createEffect
+
+创建基于signal的副作用,它们在react的useEffect阶段执行
+
+```ts
+defineComponent(() => {
+  createEffect(
+    // 允许effect函数返回一个值 并会输入到下一次effect函数
+    // 可以从参数判断是否第一次调用
+    (prev, isFirst) => {
+      // 以非.value方式使用的signal会被收集 在其变化后 触发副作用
+      signal1()
+      return (prev ?? 0) + 1
+    },
+    // 允许提供一个signal数组作为额外的依赖
+    [signal2],
+    {
+      // 在useLayoutEffect阶段执行副作用
+      layoutEffect: true,
+    },
+  )
+})
+```
+
+createEffect应当在defineComponent内部调用  
+关于它的清理函数 参考下一节
+
+### onCleanup
+
+提供清理函数
+
+```ts
+defineComponent(() => {
+  createMemo(() => {
+    onCleanup(() => console.log('memo cleanup'))
+  })
+  createEffect(() => {
+    onCleanup(() => console.log('effect cleanup'))
+  })
+  onCleanup(() => console.log('component cleanup'))
+})
+```
+
+onCleanup可以在defineComponent createMemo createEffect内部调用 作用不同
+
+- 在defineComponent内调用时 cleanup函数在组件销毁后调用
+- createEffect/createMemo内调用时 cleanup会在effect/memo函数调用前调用
+
+### createRef
+
+创建一个react ref
+
+```tsx
+defineComponent(() => {
+  const spanRef = createRef<HTMLSpanElement>()
+  return () => <span ref={spanRef} />
+})
+```
+
+不提供参数时 类型是`RefObject<T|null>` 可以直接用到html上
+
+## 实现原理简述
+
+在[reactivity.ts](src/react-signal/reactivity.ts)定义了`响应式作用域`和`组件作用域`相关内容.
+
+通过全局变量的方式，可以注册一个`响应式作用域`。在它内部使用的signal变化后，`响应式作用域`可以感知这一变化并做出反应。例如组件会更新，派生signal将自身标记为已过期等。响应式作用域还可以感知内部的`onCleanup`调用，收集清理函数，并在自身销毁时调用清理函数。
+
+`组件作用域`同样通过全局变量实现，它可以让函数在本组件的下一次useEffect阶段调用被调用.
+
+defineComponent会创建响应式作用域和组件作用域。它会收集setup函数中的`onCleanup`调用，以及render函数中对signal的使用。
+
+createMemo会创建响应式作用域。它不会立刻调用memo函数，而是在`signal()`或`signal.value`时才执行。在memo函数执行后，它会收集其使用到的signal，每次memo函数执行前都会清空上次收集的signal。在其依赖的signal变化后，它将自身标记为已过期，直到下一次自身的值被访问时才计算新值，然后向所有使用自身的`响应式作用域`发消息。值得注意的是，如果在render函数中访问了值过期的派生signal，它向组件的响应式作用域发消息，可以用变量判断当前是否处于rendering来进行区分，避免额外的更新。
+
+createEffect在依赖收集方面与createMemo类似。在副作用实现上，createEffect确保函数`callEffectFn`在每个useEffect都执行。这个函数会访问`shouldCallEffect`变量，它为true时再执行effect函数，然后将此变量置为false。每当createEffect包裹的signal变化时，`shouldCallEffect`被置为true。
+
+onCleanup获取当前的响应式作用域并将增加其清理函数。
+
+createRef返回了一个普通对象。

package/dist/react-signal.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const d=require("react");let h;const y=()=>h;function E(o,t){const u=h;h=t;const s=o();return h=u,s}let p;const m=()=>p;function S(o,t){const u=p;p=t;const s=o();return p=u,s}function C(o){let t=o;const u=new Set;function s(){const n=y();return n&&!u.has(n)&&(u.add(n),n.listenRangeDestory(()=>u.delete(n))),t}Object.defineProperty(s,"value",{get(){return t}});function e(n){t!==n&&(t=n,u.forEach(l=>l.onSignalChange()))}return[s,e]}function v(o){const t=u=>{const[,s]=d.useReducer(()=>({}),null),e=d.useRef(null);if(e.current)e.current.propsSignal[1](u);else{const r={onSignalChange:()=>{var i;(i=e.current)!=null&&i.isRending||s()},listenRangeDestory:i=>{var c;(c=e.current)==null||c.cleanups.push(i)}},f={addEffectFn:i=>{var c;return(c=e.current)==null?void 0:c.effects.push(i)},addLayoutEffectFn:i=>{var c;return(c=e.current)==null?void 0:c.layoutEffects.push(i)}},g=C(u);e.current={reactivityRange:r,componentRange:f,cleanups:[],effects:[],layoutEffects:[],isRending:!1,propsSignal:g};const a=E(()=>S(()=>o(g[0]),f),r);e.current.render=a}d.useEffect(()=>()=>{if(!e.current)return;const r=e.current.cleanups;e.current=null,r.forEach(f=>f())},[]),d.useLayoutEffect(()=>{if(!e.current)return;const r=e.current.effects;e.current.effects=[],r.forEach(f=>f())}),d.useEffect(()=>{if(!e.current)return;const r=e.current.layoutEffects;e.current.layoutEffects=[],r.forEach(f=>f())});const{render:n,reactivityRange:l}=e.current;e.current.isRending=!0;const R=E(n,l);return e.current.isRending=!1,R};return d.memo(t)}function D(o,t,u){let s=[];function e(){s.forEach(c=>c()),s=[]}const n=y();n==null||n.listenRangeDestory(e);let l;const R={onSignalChange:()=>{f=!0},listenRangeDestory:c=>{s.push(c)}},r=m();let f=!0,g=!0;function a(){const{layoutEffect:c}=u??{};c?r==null||r.addLayoutEffectFn(i):r==null||r.addEffectFn(i)}function i(){a(),f&&(f=!1,e(),E(()=>{t==null||t.forEach(c=>c()),l=o(l,g),g=!1},R))}a()}function F(o,t=Object.is){let u=[];function s(){u.forEach(a=>a()),u=[]}const e=y();e==null||e.listenRangeDestory(s);let n,l=!0;const R={onSignalChange:()=>{l=!0},listenRangeDestory:a=>{u.push(a)}},r=new Set;function f(a=!0){if(!l)return;s();const i=n;E(()=>{n=o(i)},R),l=!1,!(!a||t(i,n))&&r.forEach(c=>c.onSignalChange())}function g(){f();const a=y();return a&&!r.has(a)&&(r.add(a),a.listenRangeDestory(()=>r.delete(a))),n}return Object.defineProperty(g,"value",{get(){return f(!1),n}}),g}function b(o){const t=y();t==null||t.listenRangeDestory(()=>E(o,void 0))}function M(o){return{current:o??null}}exports.createEffect=D;exports.createMemo=F;exports.createRef=M;exports.createSignal=C;exports.defineComponent=v;exports.onCleanup=b;

package/dist/react-signal.d.ts

@@ -0,0 +1,159 @@
+import { FC } from 'react';
+import { MemoExoticComponent } from 'react';
+import { ReactNode } from 'react';
+import { RefObject } from 'react';
+
+/**
+ * 创建基于 signal 的副作用；默认在 React `useEffect` 阶段执行。
+ *
+ * 应在 {@link defineComponent} 的 setup 内调用。清理逻辑使用 {@link onCleanup}。
+ *
+ * @example
+ * ```ts
+ * defineComponent(() => {
+ *   createEffect(
+ *     // 允许 effect 函数返回一个值，并会输入到下一次 effect 函数
+ *     // 可以从参数判断是否第一次调用
+ *     (prev, isFirst) => {
+ *       // 使用的 signal 会被收集，在其变化后触发副作用
+ *       signal1()
+ *       // .value访问值的不会被收集
+ *       signal2.value
+ *       // 下一次effect函数调用前或组件销毁时调用
+ *       onCleanup(()=> console.log('effect'))
+ *       return (prev ?? 0) + 1
+ *     },
+ *     // 允许提供一个 signal getter 数组作为额外的依赖
+ *     [signal3],
+ *     {
+ *       // 在 useLayoutEffect 阶段执行副作用
+ *       layoutEffect: true,
+ *     },
+ *   )
+ *
+ *   return () => null
+ * })
+ * ```
+ */
+export declare function createEffect<T>(effect: Effect<T>, deps?: Deps | undefined | null, option?: EffectOption): void;
+
+/**
+ * 创建派生 signal；可在任意位置调用。
+ *
+ * 内部会记录值是否过期，直到 `getter()` 或 `.value` 访问时才实际重算。
+ *
+ * @example
+ * ```ts
+ * // 参数为上一次的 memo 值
+ * const double = createMemo((prev) =>{
+ *  // .value访问值的不会被收集
+ *  signal2.value
+ *  // count会被收集
+ *  return count() * 2
+ * // 第二个参数是自定义的比较函数
+ * }, Object.is)
+ *
+ * // 访问其值
+ * double()
+ *
+ * // 不具有响应性地获取其值
+ * double.value
+ * ```
+ */
+export declare function createMemo<T>(memo: Memo<T>, isEqual?: EqualFn<T>): SignalGetter<T>;
+
+export declare function createRef<T>(defaultValue?: null | undefined): RefObject<T | null>;
+
+export declare function createRef<T>(defaultValue: T): RefObject<T>;
+
+export declare function createSignal<T>(): Signal<T | undefined>;
+
+export declare function createSignal<T>(defaultValue: T): Signal<T>;
+
+/**
+ * 使用 setup 创建支持响应式 signal 的组件。
+ *
+ * setup 在组件整个生命周期内只执行一次（不包括热重载），应返回一个 render 函数；render 会执行多次。
+ * 入参 `props` 为 {@link SignalGetter}，在 setup 或 render 中用 `props()` 读取并追踪父组件传入的 props。
+ *
+ * @typeParam T - 组件 props 类型。
+ *
+ *
+ * @example
+ * ```tsx
+ * type CompProps = {
+ *   num: number
+ * }
+ * const Comp = defineComponent<CompProps>((props) => {
+ *   // props也是signal
+ *   // 组件销毁后执行
+ *   onCleanup(()=> console.log('comp unmounted'))
+ *   // render中用到的signal被自动收集 变化后更新组件
+ *   // 如果通过.value访问值 则不会被收集
+ *   return () => <span>{props().num}</span>
+ * })
+ * ```
+ */
+export declare function defineComponent<T = object>(sc: SignalComponent<T>): MemoExoticComponent<FC<T>>;
+
+/** 额外依赖：一组 getter，在运行 effect 前会先调用以收集订阅。 */
+export declare type Deps = (() => any)[];
+
+/**
+ * effect 回调：返回值会作为下一次调用的 `prev`；`isFirst` 表示是否首次执行。
+ */
+export declare type Effect<T> = (prev: T | undefined, isFirst: boolean) => T;
+
+export declare type EffectOption = {
+    /** 为 true 时在 `useLayoutEffect` 阶段执行，否则在 `useEffect`。 */
+    layoutEffect?: boolean;
+};
+
+export declare type EqualFn<T> = (prev: T | undefined, current: T) => boolean;
+
+/**
+ * `createMemo` 的计算函数；参数为上一轮的缓存值。
+ */
+export declare type Memo<T> = (prev: T | undefined) => T;
+
+/**
+ * 注册清理函数。
+ *
+ * 可在 {@link defineComponent}、{@link createMemo}、{@link createEffect} 内调用，语义不同：
+ * - 在 **defineComponent** 内：`cleanup` 在组件销毁后调用。
+ * - 在 **createEffect** / **createMemo** 内：`cleanup` 在 effect / memo **下一次执行前**调用。
+ *
+ * 执行清理时不在响应式上下文中，其中读取 signal 不会建立订阅。
+ *
+ * @example
+ * ```ts
+ * defineComponent(() => {
+ *   createMemo(() => {
+ *     onCleanup(() => console.log('memo cleanup'))
+ *     return 0
+ *   })
+ *   createEffect(() => {
+ *     onCleanup(() => console.log('effect cleanup'))
+ *   })
+ *   onCleanup(() => console.log('component cleanup'))
+ *
+ *   return () => null
+ * })
+ * ```
+ */
+export declare function onCleanup(cleanup: () => void): void;
+
+export declare type Render = () => ReactNode;
+
+export declare type Signal<T> = [SignalGetter<T>, (val: T) => void];
+
+declare type SignalComponent<T = object> = (props: SignalGetter<T>) => Render;
+export { SignalComponent as SC }
+export { SignalComponent }
+
+export declare type SignalGetter<T> = {
+    (): T;
+    value: T;
+};
+
+export { }

package/dist/react-signal.js

@@ -0,0 +1,173 @@
+import { memo as C, useReducer as m, useRef as v, useEffect as p, useLayoutEffect as S } from "react";
+let h;
+const d = () => h;
+function y(a, r) {
+  const u = h;
+  h = r;
+  const s = a();
+  return h = u, s;
+}
+let E;
+const D = () => E;
+function F(a, r) {
+  const u = E;
+  E = r;
+  const s = a();
+  return E = u, s;
+}
+function V(a) {
+  let r = a;
+  const u = /* @__PURE__ */ new Set();
+  function s() {
+    const t = d();
+    return t && !u.has(t) && (u.add(t), t.listenRangeDestory(() => u.delete(t))), r;
+  }
+  Object.defineProperty(s, "value", {
+    get() {
+      return r;
+    }
+  });
+  function e(t) {
+    r !== t && (r = t, u.forEach((l) => l.onSignalChange()));
+  }
+  return [s, e];
+}
+function L(a) {
+  return C((u) => {
+    const [, s] = m(() => ({}), null), e = v(null);
+    if (e.current)
+      e.current.propsSignal[1](u);
+    else {
+      const n = {
+        onSignalChange: () => {
+          var i;
+          (i = e.current) != null && i.isRending || s();
+        },
+        listenRangeDestory: (i) => {
+          var c;
+          (c = e.current) == null || c.cleanups.push(i);
+        }
+      }, f = {
+        addEffectFn: (i) => {
+          var c;
+          return (c = e.current) == null ? void 0 : c.effects.push(i);
+        },
+        addLayoutEffectFn: (i) => {
+          var c;
+          return (c = e.current) == null ? void 0 : c.layoutEffects.push(i);
+        }
+      }, g = V(u);
+      e.current = {
+        reactivityRange: n,
+        componentRange: f,
+        cleanups: [],
+        effects: [],
+        layoutEffects: [],
+        isRending: !1,
+        propsSignal: g
+      };
+      const o = y(
+        () => F(() => a(g[0]), f),
+        n
+      );
+      e.current.render = o;
+    }
+    p(() => () => {
+      if (!e.current) return;
+      const n = e.current.cleanups;
+      e.current = null, n.forEach((f) => f());
+    }, []), S(() => {
+      if (!e.current) return;
+      const n = e.current.effects;
+      e.current.effects = [], n.forEach((f) => f());
+    }), p(() => {
+      if (!e.current) return;
+      const n = e.current.layoutEffects;
+      e.current.layoutEffects = [], n.forEach((f) => f());
+    });
+    const { render: t, reactivityRange: l } = e.current;
+    e.current.isRending = !0;
+    const R = y(t, l);
+    return e.current.isRending = !1, R;
+  });
+}
+function b(a, r, u) {
+  let s = [];
+  function e() {
+    s.forEach((c) => c()), s = [];
+  }
+  const t = d();
+  t == null || t.listenRangeDestory(e);
+  let l;
+  const R = {
+    onSignalChange: () => {
+      f = !0;
+    },
+    listenRangeDestory: (c) => {
+      s.push(c);
+    }
+  }, n = D();
+  let f = !0, g = !0;
+  function o() {
+    const { layoutEffect: c } = u ?? {};
+    c ? n == null || n.addLayoutEffectFn(i) : n == null || n.addEffectFn(i);
+  }
+  function i() {
+    o(), f && (f = !1, e(), y(() => {
+      r == null || r.forEach((c) => c()), l = a(l, g), g = !1;
+    }, R));
+  }
+  o();
+}
+function j(a, r = Object.is) {
+  let u = [];
+  function s() {
+    u.forEach((o) => o()), u = [];
+  }
+  const e = d();
+  e == null || e.listenRangeDestory(s);
+  let t, l = !0;
+  const R = {
+    onSignalChange: () => {
+      l = !0;
+    },
+    listenRangeDestory: (o) => {
+      u.push(o);
+    }
+  }, n = /* @__PURE__ */ new Set();
+  function f(o = !0) {
+    if (!l) return;
+    s();
+    const i = t;
+    y(() => {
+      t = a(i);
+    }, R), l = !1, !(!o || r(i, t)) && n.forEach((c) => c.onSignalChange());
+  }
+  function g() {
+    f();
+    const o = d();
+    return o && !n.has(o) && (n.add(o), o.listenRangeDestory(() => n.delete(o))), t;
+  }
+  return Object.defineProperty(g, "value", {
+    get() {
+      return f(!1), t;
+    }
+  }), g;
+}
+function M(a) {
+  const r = d();
+  r == null || r.listenRangeDestory(() => y(a, void 0));
+}
+function O(a) {
+  return {
+    current: a ?? null
+  };
+}
+export {
+  b as createEffect,
+  j as createMemo,
+  O as createRef,
+  V as createSignal,
+  L as defineComponent,
+  M as onCleanup
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@fane_the_divine/react-signal",
+  "version": "0.0.0",
+  "type": "module",
+  "description": "在react中使用signal",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FanetheDivine/react-signal.git"
+  },
+  "keywords": [
+    "react",
+    "signals",
+    "reactivity"
+  ],
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/react-signal.cjs",
+  "module": "./dist/react-signal.js",
+  "types": "./dist/react-signal.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/react-signal.d.ts",
+      "import": "./dist/react-signal.js",
+      "require": "./dist/react-signal.cjs"
+    }
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build-publish": "vite build --config vite.lib.config.ts && npm publish --access public",
+    "lint": "eslint src/ ",
+    "prettier": "prettier --write src/"
+  },
+  "devDependencies": {
+    "react": "^19",
+    "react-dom": "^19",
+    "@eslint/js": "^9.22.0",
+    "@tailwindcss/vite": "^4.1.11",
+    "@trivago/prettier-plugin-sort-imports": "^5.2.2",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@vitejs/plugin-react-swc": "^3.11.0",
+    "eslint": "9",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.19",
+    "globals": "^16.3.0",
+    "prettier": "3.6.2",
+    "prettier-plugin-tailwindcss": "0.6.14",
+    "tailwindcss": "^4",
+    "typescript": "^5",
+    "typescript-eslint": "^8.26.1",
+    "vite": "^6",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@swc/core"
+    ]
+  }
+}