@shadow-js/core 0.1.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (387) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/LICENSE +2 -2
  3. package/README.md +134 -331
  4. package/dist/dev/action.d.ts +34 -0
  5. package/dist/dev/action.js +89 -0
  6. package/dist/dev/action.js.map +1 -0
  7. package/dist/dev/cache.d.ts +33 -0
  8. package/dist/dev/cache.js +61 -0
  9. package/dist/dev/cache.js.map +1 -0
  10. package/dist/dev/context.d.ts +104 -0
  11. package/dist/dev/context.js +110 -0
  12. package/dist/dev/context.js.map +1 -0
  13. package/dist/dev/effect.d.ts +120 -0
  14. package/dist/dev/effect.js +110 -0
  15. package/dist/dev/effect.js.map +1 -0
  16. package/dist/dev/env.d.ts +27 -0
  17. package/dist/dev/env.js +30 -0
  18. package/dist/dev/env.js.map +1 -0
  19. package/dist/dev/events.d.ts +26 -0
  20. package/dist/dev/events.js +32 -0
  21. package/dist/dev/events.js.map +1 -0
  22. package/dist/dev/extend/index.d.ts +329 -0
  23. package/dist/dev/extend/index.js +316 -0
  24. package/dist/dev/extend/index.js.map +1 -0
  25. package/dist/dev/external-store.d.ts +58 -0
  26. package/dist/dev/external-store.js +59 -0
  27. package/dist/dev/external-store.js.map +1 -0
  28. package/dist/dev/index.d.ts +29 -0
  29. package/dist/dev/index.js +26 -0
  30. package/dist/dev/internal/concurrency.d.ts +211 -0
  31. package/dist/dev/internal/concurrency.js +631 -0
  32. package/dist/dev/internal/concurrency.js.map +1 -0
  33. package/dist/dev/internal/devtools.d.ts +69 -0
  34. package/dist/dev/internal/devtools.js +76 -0
  35. package/dist/dev/internal/devtools.js.map +1 -0
  36. package/dist/dev/internal/diagnostics.d.ts +88 -0
  37. package/dist/dev/internal/diagnostics.js +101 -0
  38. package/dist/dev/internal/diagnostics.js.map +1 -0
  39. package/dist/dev/internal/dispose.d.ts +26 -0
  40. package/dist/dev/internal/dispose.js +48 -0
  41. package/dist/dev/internal/dispose.js.map +1 -0
  42. package/dist/dev/internal/flags.js +10 -0
  43. package/dist/dev/internal/flags.js.map +1 -0
  44. package/dist/dev/internal/graph.d.ts +231 -0
  45. package/dist/dev/internal/graph.js +577 -0
  46. package/dist/dev/internal/graph.js.map +1 -0
  47. package/dist/dev/internal/hydration-flag.d.ts +31 -0
  48. package/dist/dev/internal/hydration-flag.js +45 -0
  49. package/dist/dev/internal/hydration-flag.js.map +1 -0
  50. package/dist/dev/internal/messages.d.ts +54 -0
  51. package/dist/dev/internal/messages.js +53 -0
  52. package/dist/dev/internal/messages.js.map +1 -0
  53. package/dist/dev/internal/owner.d.ts +140 -0
  54. package/dist/dev/internal/owner.js +289 -0
  55. package/dist/dev/internal/owner.js.map +1 -0
  56. package/dist/dev/internal/queue.js +45 -0
  57. package/dist/dev/internal/queue.js.map +1 -0
  58. package/dist/dev/internal/scheduler.d.ts +111 -0
  59. package/dist/dev/internal/scheduler.js +286 -0
  60. package/dist/dev/internal/scheduler.js.map +1 -0
  61. package/dist/dev/internal/state.d.ts +139 -0
  62. package/dist/dev/internal/state.js +27 -0
  63. package/dist/dev/internal/state.js.map +1 -0
  64. package/dist/dev/internal/suspension.d.ts +41 -0
  65. package/dist/dev/internal/suspension.js +44 -0
  66. package/dist/dev/internal/suspension.js.map +1 -0
  67. package/dist/dev/internal/types.d.ts +44 -0
  68. package/dist/dev/list.d.ts +91 -0
  69. package/dist/dev/list.js +281 -0
  70. package/dist/dev/list.js.map +1 -0
  71. package/dist/dev/memo.d.ts +58 -0
  72. package/dist/dev/memo.js +40 -0
  73. package/dist/dev/memo.js.map +1 -0
  74. package/dist/dev/optimistic.d.ts +24 -0
  75. package/dist/dev/optimistic.js +44 -0
  76. package/dist/dev/optimistic.js.map +1 -0
  77. package/dist/dev/ownership.d.ts +202 -0
  78. package/dist/dev/ownership.js +260 -0
  79. package/dist/dev/ownership.js.map +1 -0
  80. package/dist/dev/props.d.ts +132 -0
  81. package/dist/dev/props.js +281 -0
  82. package/dist/dev/props.js.map +1 -0
  83. package/dist/dev/reaction.d.ts +27 -0
  84. package/dist/dev/reaction.js +60 -0
  85. package/dist/dev/reaction.js.map +1 -0
  86. package/dist/dev/reducer.d.ts +39 -0
  87. package/dist/dev/reducer.js +38 -0
  88. package/dist/dev/reducer.js.map +1 -0
  89. package/dist/dev/refs.d.ts +50 -0
  90. package/dist/dev/refs.js +57 -0
  91. package/dist/dev/refs.js.map +1 -0
  92. package/dist/dev/resource.d.ts +133 -0
  93. package/dist/dev/resource.js +176 -0
  94. package/dist/dev/resource.js.map +1 -0
  95. package/dist/dev/selector.d.ts +32 -0
  96. package/dist/dev/selector.js +117 -0
  97. package/dist/dev/selector.js.map +1 -0
  98. package/dist/dev/signal.d.ts +40 -0
  99. package/dist/dev/signal.js +38 -0
  100. package/dist/dev/signal.js.map +1 -0
  101. package/dist/dev/store/index.d.ts +5 -0
  102. package/dist/dev/store/index.js +4 -0
  103. package/dist/dev/store/nodes.js +191 -0
  104. package/dist/dev/store/nodes.js.map +1 -0
  105. package/dist/dev/store/proxies.js +159 -0
  106. package/dist/dev/store/proxies.js.map +1 -0
  107. package/dist/dev/store/read.d.ts +37 -0
  108. package/dist/dev/store/read.js +71 -0
  109. package/dist/dev/store/read.js.map +1 -0
  110. package/dist/dev/store/reconcile.d.ts +71 -0
  111. package/dist/dev/store/reconcile.js +185 -0
  112. package/dist/dev/store/reconcile.js.map +1 -0
  113. package/dist/dev/store/types.d.ts +104 -0
  114. package/dist/dev/store/use-store.d.ts +58 -0
  115. package/dist/dev/store/use-store.js +167 -0
  116. package/dist/dev/store/use-store.js.map +1 -0
  117. package/dist/dev/suspense.d.ts +99 -0
  118. package/dist/dev/suspense.js +44 -0
  119. package/dist/dev/suspense.js.map +1 -0
  120. package/dist/dev/transitions.d.ts +75 -0
  121. package/dist/dev/transitions.js +100 -0
  122. package/dist/dev/transitions.js.map +1 -0
  123. package/dist/prod/action.js +2 -0
  124. package/dist/prod/action.js.map +1 -0
  125. package/dist/prod/cache.js +2 -0
  126. package/dist/prod/cache.js.map +1 -0
  127. package/dist/prod/context.js +2 -0
  128. package/dist/prod/context.js.map +1 -0
  129. package/dist/prod/effect.js +2 -0
  130. package/dist/prod/effect.js.map +1 -0
  131. package/dist/prod/env.js +2 -0
  132. package/dist/prod/env.js.map +1 -0
  133. package/dist/prod/events.js +2 -0
  134. package/dist/prod/events.js.map +1 -0
  135. package/dist/prod/extend/index.js +2 -0
  136. package/dist/prod/extend/index.js.map +1 -0
  137. package/dist/prod/external-store.js +2 -0
  138. package/dist/prod/external-store.js.map +1 -0
  139. package/dist/prod/index.js +1 -0
  140. package/dist/prod/internal/concurrency.js +2 -0
  141. package/dist/prod/internal/concurrency.js.map +1 -0
  142. package/dist/prod/internal/devtools.js +2 -0
  143. package/dist/prod/internal/devtools.js.map +1 -0
  144. package/dist/prod/internal/diagnostics.js +2 -0
  145. package/dist/prod/internal/diagnostics.js.map +1 -0
  146. package/dist/prod/internal/dispose.js +2 -0
  147. package/dist/prod/internal/dispose.js.map +1 -0
  148. package/dist/prod/internal/flags.js +2 -0
  149. package/dist/prod/internal/flags.js.map +1 -0
  150. package/dist/prod/internal/graph.js +2 -0
  151. package/dist/prod/internal/graph.js.map +1 -0
  152. package/dist/prod/internal/hydration-flag.js +2 -0
  153. package/dist/prod/internal/hydration-flag.js.map +1 -0
  154. package/dist/prod/internal/messages.js +2 -0
  155. package/dist/prod/internal/messages.js.map +1 -0
  156. package/dist/prod/internal/owner.js +2 -0
  157. package/dist/prod/internal/owner.js.map +1 -0
  158. package/dist/prod/internal/queue.js +2 -0
  159. package/dist/prod/internal/queue.js.map +1 -0
  160. package/dist/prod/internal/scheduler.js +2 -0
  161. package/dist/prod/internal/scheduler.js.map +1 -0
  162. package/dist/prod/internal/state.js +2 -0
  163. package/dist/prod/internal/state.js.map +1 -0
  164. package/dist/prod/internal/suspension.js +2 -0
  165. package/dist/prod/internal/suspension.js.map +1 -0
  166. package/dist/prod/list.js +2 -0
  167. package/dist/prod/list.js.map +1 -0
  168. package/dist/prod/memo.js +2 -0
  169. package/dist/prod/memo.js.map +1 -0
  170. package/dist/prod/optimistic.js +2 -0
  171. package/dist/prod/optimistic.js.map +1 -0
  172. package/dist/prod/ownership.js +2 -0
  173. package/dist/prod/ownership.js.map +1 -0
  174. package/dist/prod/props.js +2 -0
  175. package/dist/prod/props.js.map +1 -0
  176. package/dist/prod/reaction.js +2 -0
  177. package/dist/prod/reaction.js.map +1 -0
  178. package/dist/prod/reducer.js +2 -0
  179. package/dist/prod/reducer.js.map +1 -0
  180. package/dist/prod/refs.js +2 -0
  181. package/dist/prod/refs.js.map +1 -0
  182. package/dist/prod/resource.js +2 -0
  183. package/dist/prod/resource.js.map +1 -0
  184. package/dist/prod/selector.js +2 -0
  185. package/dist/prod/selector.js.map +1 -0
  186. package/dist/prod/signal.js +2 -0
  187. package/dist/prod/signal.js.map +1 -0
  188. package/dist/prod/store/index.js +1 -0
  189. package/dist/prod/store/nodes.js +2 -0
  190. package/dist/prod/store/nodes.js.map +1 -0
  191. package/dist/prod/store/proxies.js +2 -0
  192. package/dist/prod/store/proxies.js.map +1 -0
  193. package/dist/prod/store/read.js +2 -0
  194. package/dist/prod/store/read.js.map +1 -0
  195. package/dist/prod/store/reconcile.js +2 -0
  196. package/dist/prod/store/reconcile.js.map +1 -0
  197. package/dist/prod/store/use-store.js +2 -0
  198. package/dist/prod/store/use-store.js.map +1 -0
  199. package/dist/prod/suspense.js +2 -0
  200. package/dist/prod/suspense.js.map +1 -0
  201. package/dist/prod/transitions.js +2 -0
  202. package/dist/prod/transitions.js.map +1 -0
  203. package/dist/server/action.js +2 -0
  204. package/dist/server/action.js.map +1 -0
  205. package/dist/server/cache.js +2 -0
  206. package/dist/server/cache.js.map +1 -0
  207. package/dist/server/context.js +2 -0
  208. package/dist/server/context.js.map +1 -0
  209. package/dist/server/effect.js +2 -0
  210. package/dist/server/effect.js.map +1 -0
  211. package/dist/server/env.js +2 -0
  212. package/dist/server/env.js.map +1 -0
  213. package/dist/server/events.js +2 -0
  214. package/dist/server/events.js.map +1 -0
  215. package/dist/server/extend/index.js +2 -0
  216. package/dist/server/extend/index.js.map +1 -0
  217. package/dist/server/external-store.js +2 -0
  218. package/dist/server/external-store.js.map +1 -0
  219. package/dist/server/index.js +1 -0
  220. package/dist/server/internal/concurrency.js +2 -0
  221. package/dist/server/internal/concurrency.js.map +1 -0
  222. package/dist/server/internal/devtools.js +2 -0
  223. package/dist/server/internal/devtools.js.map +1 -0
  224. package/dist/server/internal/diagnostics.js +2 -0
  225. package/dist/server/internal/diagnostics.js.map +1 -0
  226. package/dist/server/internal/dispose.js +2 -0
  227. package/dist/server/internal/dispose.js.map +1 -0
  228. package/dist/server/internal/flags.js +2 -0
  229. package/dist/server/internal/flags.js.map +1 -0
  230. package/dist/server/internal/graph.js +2 -0
  231. package/dist/server/internal/graph.js.map +1 -0
  232. package/dist/server/internal/hydration-flag.js +2 -0
  233. package/dist/server/internal/hydration-flag.js.map +1 -0
  234. package/dist/server/internal/messages.js +2 -0
  235. package/dist/server/internal/messages.js.map +1 -0
  236. package/dist/server/internal/owner.js +2 -0
  237. package/dist/server/internal/owner.js.map +1 -0
  238. package/dist/server/internal/queue.js +2 -0
  239. package/dist/server/internal/queue.js.map +1 -0
  240. package/dist/server/internal/scheduler.js +2 -0
  241. package/dist/server/internal/scheduler.js.map +1 -0
  242. package/dist/server/internal/state.js +2 -0
  243. package/dist/server/internal/state.js.map +1 -0
  244. package/dist/server/internal/suspension.js +2 -0
  245. package/dist/server/internal/suspension.js.map +1 -0
  246. package/dist/server/list.js +2 -0
  247. package/dist/server/list.js.map +1 -0
  248. package/dist/server/memo.js +2 -0
  249. package/dist/server/memo.js.map +1 -0
  250. package/dist/server/optimistic.js +2 -0
  251. package/dist/server/optimistic.js.map +1 -0
  252. package/dist/server/ownership.js +2 -0
  253. package/dist/server/ownership.js.map +1 -0
  254. package/dist/server/props.js +2 -0
  255. package/dist/server/props.js.map +1 -0
  256. package/dist/server/reaction.js +2 -0
  257. package/dist/server/reaction.js.map +1 -0
  258. package/dist/server/reducer.js +2 -0
  259. package/dist/server/reducer.js.map +1 -0
  260. package/dist/server/refs.js +2 -0
  261. package/dist/server/refs.js.map +1 -0
  262. package/dist/server/resource.js +2 -0
  263. package/dist/server/resource.js.map +1 -0
  264. package/dist/server/selector.js +2 -0
  265. package/dist/server/selector.js.map +1 -0
  266. package/dist/server/signal.js +2 -0
  267. package/dist/server/signal.js.map +1 -0
  268. package/dist/server/store/index.js +1 -0
  269. package/dist/server/store/nodes.js +2 -0
  270. package/dist/server/store/nodes.js.map +1 -0
  271. package/dist/server/store/proxies.js +2 -0
  272. package/dist/server/store/proxies.js.map +1 -0
  273. package/dist/server/store/read.js +2 -0
  274. package/dist/server/store/read.js.map +1 -0
  275. package/dist/server/store/reconcile.js +2 -0
  276. package/dist/server/store/reconcile.js.map +1 -0
  277. package/dist/server/store/use-store.js +2 -0
  278. package/dist/server/store/use-store.js.map +1 -0
  279. package/dist/server/suspense.js +2 -0
  280. package/dist/server/suspense.js.map +1 -0
  281. package/dist/server/transitions.js +2 -0
  282. package/dist/server/transitions.js.map +1 -0
  283. package/dist/server-dev/action.js +89 -0
  284. package/dist/server-dev/action.js.map +1 -0
  285. package/dist/server-dev/cache.js +61 -0
  286. package/dist/server-dev/cache.js.map +1 -0
  287. package/dist/server-dev/context.js +107 -0
  288. package/dist/server-dev/context.js.map +1 -0
  289. package/dist/server-dev/effect.js +55 -0
  290. package/dist/server-dev/effect.js.map +1 -0
  291. package/dist/server-dev/env.js +30 -0
  292. package/dist/server-dev/env.js.map +1 -0
  293. package/dist/server-dev/events.js +32 -0
  294. package/dist/server-dev/events.js.map +1 -0
  295. package/dist/server-dev/extend/index.js +316 -0
  296. package/dist/server-dev/extend/index.js.map +1 -0
  297. package/dist/server-dev/external-store.js +45 -0
  298. package/dist/server-dev/external-store.js.map +1 -0
  299. package/dist/server-dev/index.js +26 -0
  300. package/dist/server-dev/internal/concurrency.js +632 -0
  301. package/dist/server-dev/internal/concurrency.js.map +1 -0
  302. package/dist/server-dev/internal/devtools.js +76 -0
  303. package/dist/server-dev/internal/devtools.js.map +1 -0
  304. package/dist/server-dev/internal/diagnostics.js +101 -0
  305. package/dist/server-dev/internal/diagnostics.js.map +1 -0
  306. package/dist/server-dev/internal/dispose.js +48 -0
  307. package/dist/server-dev/internal/dispose.js.map +1 -0
  308. package/dist/server-dev/internal/flags.js +10 -0
  309. package/dist/server-dev/internal/flags.js.map +1 -0
  310. package/dist/server-dev/internal/graph.js +577 -0
  311. package/dist/server-dev/internal/graph.js.map +1 -0
  312. package/dist/server-dev/internal/hydration-flag.js +45 -0
  313. package/dist/server-dev/internal/hydration-flag.js.map +1 -0
  314. package/dist/server-dev/internal/messages.js +53 -0
  315. package/dist/server-dev/internal/messages.js.map +1 -0
  316. package/dist/server-dev/internal/owner.js +289 -0
  317. package/dist/server-dev/internal/owner.js.map +1 -0
  318. package/dist/server-dev/internal/queue.js +45 -0
  319. package/dist/server-dev/internal/queue.js.map +1 -0
  320. package/dist/server-dev/internal/scheduler.js +286 -0
  321. package/dist/server-dev/internal/scheduler.js.map +1 -0
  322. package/dist/server-dev/internal/state.js +27 -0
  323. package/dist/server-dev/internal/state.js.map +1 -0
  324. package/dist/server-dev/internal/suspension.js +44 -0
  325. package/dist/server-dev/internal/suspension.js.map +1 -0
  326. package/dist/server-dev/list.js +281 -0
  327. package/dist/server-dev/list.js.map +1 -0
  328. package/dist/server-dev/memo.js +40 -0
  329. package/dist/server-dev/memo.js.map +1 -0
  330. package/dist/server-dev/optimistic.js +44 -0
  331. package/dist/server-dev/optimistic.js.map +1 -0
  332. package/dist/server-dev/ownership.js +260 -0
  333. package/dist/server-dev/ownership.js.map +1 -0
  334. package/dist/server-dev/props.js +281 -0
  335. package/dist/server-dev/props.js.map +1 -0
  336. package/dist/server-dev/reaction.js +60 -0
  337. package/dist/server-dev/reaction.js.map +1 -0
  338. package/dist/server-dev/reducer.js +38 -0
  339. package/dist/server-dev/reducer.js.map +1 -0
  340. package/dist/server-dev/refs.js +57 -0
  341. package/dist/server-dev/refs.js.map +1 -0
  342. package/dist/server-dev/resource.js +175 -0
  343. package/dist/server-dev/resource.js.map +1 -0
  344. package/dist/server-dev/selector.js +81 -0
  345. package/dist/server-dev/selector.js.map +1 -0
  346. package/dist/server-dev/signal.js +38 -0
  347. package/dist/server-dev/signal.js.map +1 -0
  348. package/dist/server-dev/store/index.js +4 -0
  349. package/dist/server-dev/store/nodes.js +191 -0
  350. package/dist/server-dev/store/nodes.js.map +1 -0
  351. package/dist/server-dev/store/proxies.js +159 -0
  352. package/dist/server-dev/store/proxies.js.map +1 -0
  353. package/dist/server-dev/store/read.js +71 -0
  354. package/dist/server-dev/store/read.js.map +1 -0
  355. package/dist/server-dev/store/reconcile.js +185 -0
  356. package/dist/server-dev/store/reconcile.js.map +1 -0
  357. package/dist/server-dev/store/use-store.js +167 -0
  358. package/dist/server-dev/store/use-store.js.map +1 -0
  359. package/dist/server-dev/suspense.js +44 -0
  360. package/dist/server-dev/suspense.js.map +1 -0
  361. package/dist/server-dev/transitions.js +85 -0
  362. package/dist/server-dev/transitions.js.map +1 -0
  363. package/package.json +111 -50
  364. package/dist/chunk-6Y3CCWOY.js +0 -887
  365. package/dist/chunk-6Y3CCWOY.js.map +0 -1
  366. package/dist/chunk-B5FTYDUG.js +0 -3
  367. package/dist/chunk-B5FTYDUG.js.map +0 -1
  368. package/dist/index.cjs +0 -2000
  369. package/dist/index.cjs.map +0 -1
  370. package/dist/index.d.cts +0 -609
  371. package/dist/index.d.ts +0 -609
  372. package/dist/index.js +0 -1094
  373. package/dist/index.js.map +0 -1
  374. package/dist/jsx-Bugil6CJ.d.cts +0 -151
  375. package/dist/jsx-Bugil6CJ.d.ts +0 -151
  376. package/dist/jsx-dev-runtime.cjs +0 -742
  377. package/dist/jsx-dev-runtime.cjs.map +0 -1
  378. package/dist/jsx-dev-runtime.d.cts +0 -2
  379. package/dist/jsx-dev-runtime.d.ts +0 -2
  380. package/dist/jsx-dev-runtime.js +0 -4
  381. package/dist/jsx-dev-runtime.js.map +0 -1
  382. package/dist/jsx-runtime.cjs +0 -742
  383. package/dist/jsx-runtime.cjs.map +0 -1
  384. package/dist/jsx-runtime.d.cts +0 -36
  385. package/dist/jsx-runtime.d.ts +0 -36
  386. package/dist/jsx-runtime.js +0 -4
  387. package/dist/jsx-runtime.js.map +0 -1
package/CHANGELOG.md ADDED
@@ -0,0 +1,17 @@
1
+ # Changelog
2
+
3
+ ## 1.0.1
4
+
5
+ ### Changed
6
+
7
+ - Released at 1.0.1 with the other packages, which share one version. No change to this package.
8
+
9
+ ## 1.0.0
10
+
11
+ ### Added
12
+
13
+ - Fine-grained signals and deep stores, memos, effects, owner lifecycles and context.
14
+ - Batching and deterministic flushing, resources, selectors, optimistic state and concurrency helpers.
15
+ - Error handlers run untracked and restore caller tracking after success or rethrow, preventing accidental subscriptions during synchronous error recovery.
16
+ - Scope options are evaluated once, and a throwing getter restores the original scope.
17
+ - `@shadow-js/core/extend`: the edges of a node are stored as pairs in one array (`observers` of a source, `sources` of a computation: the node on the other side, then the index of this node's entry on that side) instead of two parallel arrays, so every edge costs half the memory and the engine is about 80 bytes smaller (gzip). `SourceNode` is now `{ kind, value, observers, stamp }`: the `observerSlots` and `sourceSlots` fields are gone. Read the edges with the new `observersOf(source)` and `sourcesOf(computation)`, which return the nodes alone. A keyed list row retains 9% fewer bytes (1,407 to 1,281) and a selector key 7% fewer (730 to 682).
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2025 Jehaad AL-Johani
3
+ Copyright (c) 2026 ShadowJS contributors
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
18
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
19
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
20
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,386 +1,189 @@
1
- # ShadowJS Core Framework
1
+ # @shadow-js/core
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/core.svg)](https://www.npmjs.com/package/@shadow-js/core)
4
- [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
5
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
3
+ The reactive engine of ShadowJS: signals, a deep fine-grained store, memos, effects, owners,
4
+ context, resources and list primitives. It has no runtime dependencies, no virtual DOM and no DOM
5
+ access. The renderer lives in [`@shadow-js/web`](../web/README.md).
6
6
 
7
- The core ShadowJS framework providing fine-grained reactivity, JSX runtime, and essential UI components.
7
+ Reads inside an effect or a memo subscribe it to exactly the value or property that was read, and a
8
+ write notifies exactly those readers. Components are plain functions that run once; what changes
9
+ later is the effects and bindings inside them.
8
10
 
9
- ## ✨ Features
11
+ ## Install
10
12
 
11
- - **🎯 Fine-grained Reactivity**: Only re-render what actually changes
12
- - **⚡ Fast Runtime**: Minimal overhead with optimized DOM updates
13
- - **🎨 JSX-First**: Familiar React-like syntax with powerful extensions
14
- - **📦 Tree-Shakable**: Only bundle what you use
15
- - **🔧 TypeScript Ready**: Full type safety and IntelliSense support
16
- - **🎭 Component System**: Built-in components for common UI patterns
17
-
18
- ## 📦 Installation
19
-
20
- ```bash
13
+ ```sh
21
14
  npm install @shadow-js/core
22
15
  ```
23
16
 
24
- For development with hot reload and JSX compilation:
25
-
26
- ```bash
27
- npm install @shadow-js/core @shadow-js/vite
28
- ```
29
-
30
- ## 🚀 Quick Start
31
-
32
- ```tsx
33
- import { useStore, Show, For } from "@shadow-js/core";
34
-
35
- function Counter() {
36
- const [count, setCount] = useStore(0);
37
- const [items, setItems] = useStore(["Shadow", "JS", "Reactivity"]);
38
-
39
- return (
40
- <div>
41
- <h2>Counter: {() => count()}</h2>
42
- <button onClick={() => setCount(count() + 1)}>Increment</button>
43
-
44
- <Show when={() => count() > 5} fallback={<p>Keep clicking!</p>}>
45
- <p>🎉 You reached {() => count()}!</p>
46
- </Show>
47
-
48
- <ul>
49
- <For each={() => items()}>{(item) => <li>{() => item}</li>}</For>
50
- </ul>
51
- </div>
52
- );
53
- }
54
- ```
55
-
56
- ## 🎯 Core Concepts
57
-
58
- ### Reactive Stores
59
-
60
- Create reactive state that automatically updates dependent computations:
61
-
62
- ```tsx
63
- import { useStore } from "@shadow-js/core";
64
-
65
- function App() {
66
- const [count, setCount] = useStore(0);
67
- const doubled = () => count() * 2; // Reactive computation
17
+ ShadowJS 1.0.0 is not on npm yet. Until it is published, install it from a local checkout of this
18
+ repository.
19
+ Requires Node 22.12 or newer for tooling; the package is ESM only.
68
20
 
69
- return (
70
- <div>
71
- <p>Count: {() => count()}</p>
72
- <p>Doubled: {() => doubled()}</p> {/* Updates automatically */}
73
- <button onClick={() => setCount(count() + 1)}>+</button>
74
- </div>
75
- );
76
- }
77
- ```
21
+ ## Example
78
22
 
79
- ### Effects and Lifecycle
23
+ `useStore` is the state hook. A single value gives a `[read, write]` pair; plain objects and
24
+ arrays give a deep store whose reads are tracked per property. `useMemo` caches a derivation and
25
+ `useEffect` runs a side effect after a flush. Effects need an owner, so this module creates one
26
+ with `createRoot`. Writes made outside an event handler flush in a microtask; `flushSync()` flushes
27
+ them at once.
80
28
 
81
- ```tsx
82
- import { useEffect, onMount, onCleanup } from "@shadow-js/core";
29
+ ```ts title="counter.ts" run output="count 0, doubled 0\ncount 1, doubled 2\ncount 5, doubled 10"
30
+ import { createRoot, flushSync, useEffect, useMemo, useStore } from "@shadow-js/core";
83
31
 
84
- function Timer() {
85
- const [time, setTime] = useStore(new Date());
32
+ const [count, setCount] = useStore(0);
86
33
 
87
- onMount(() => {
88
- console.log("Component mounted");
89
- });
34
+ createRoot((dispose) => {
35
+ const doubled = useMemo(() => count() * 2);
90
36
 
91
37
  useEffect(() => {
92
- const interval = setInterval(() => {
93
- setTime(new Date());
94
- }, 1000);
95
-
96
- // Cleanup on unmount or dependency change
97
- return () => clearInterval(interval);
38
+ console.log(`count ${count()}, doubled ${doubled()}`);
98
39
  });
99
40
 
100
- onCleanup(() => {
101
- console.log("Component unmounting");
102
- });
103
-
104
- return <div>Current time: {() => time().toLocaleTimeString()}</div>;
105
- }
106
- ```
107
-
108
- ### Conditional Rendering
109
-
110
- ```tsx
111
- import { Show } from "@shadow-js/core";
112
-
113
- function UserStatus({ user }) {
114
- return (
115
- <Show when={() => user()} fallback={<div>Please log in</div>}>
116
- <div>Welcome back, {() => user().name}!</div>
117
- </Show>
118
- );
119
- }
120
- ```
121
-
122
- ### Lists with For
123
-
124
- ```tsx
125
- import { For } from "@shadow-js/core";
126
-
127
- function TodoList({ todos }) {
128
- return (
129
- <ul>
130
- <For each={() => todos()}>
131
- {(todo, index) => (
132
- <li>
133
- {() => index() + 1}. {() => todo.title}
134
- </li>
135
- )}
136
- </For>
137
- </ul>
138
- );
139
- }
140
- ```
141
-
142
- ### Switch/Case Pattern
143
-
144
- ```tsx
145
- import { Switch, Match } from "@shadow-js/core";
146
-
147
- function StatusDisplay({ status }) {
148
- return (
149
- <Switch fallback={<div>Unknown status</div>}>
150
- <Match when={() => status() === "loading"}>
151
- <div>Loading...</div>
152
- </Match>
153
- <Match when={() => status() === "success"}>
154
- <div>Success!</div>
155
- </Match>
156
- <Match when={() => status() === "error"}>
157
- <div>Error occurred</div>
158
- </Match>
159
- </Switch>
160
- );
161
- }
41
+ flushSync();
42
+ setCount((n) => n + 1);
43
+ flushSync();
44
+ setCount(5);
45
+ flushSync();
46
+ dispose();
47
+ });
162
48
  ```
163
49
 
164
- ### Async Operations with Suspense
165
-
166
- ```tsx
167
- import { Suspense, lazy } from "@shadow-js/core";
50
+ For nested data, a store notifies only the readers of what changed. `setStore` accepts a draft
51
+ function, a merge object, a path (`"todos", 1, "done", true`) or `reconcile(next)`. The effect
52
+ below reads one property of one item, so it does not run for the write to the other item.
168
53
 
169
- // Lazy load components
170
- const LazyComponent = lazy(() => import("./HeavyComponent"));
54
+ ```ts title="todos.ts" run output="first todo done: false\nfirst todo done: true"
55
+ import { createRoot, flushSync, useEffect, useStore } from "@shadow-js/core";
171
56
 
172
- function App() {
173
- return (
174
- <Suspense fallback={<div>Loading component...</div>}>
175
- <LazyComponent />
176
- </Suspense>
177
- );
57
+ interface Todo {
58
+ id: number;
59
+ title: string;
60
+ done: boolean;
178
61
  }
179
- ```
180
62
 
181
- ## 📚 API Reference
182
-
183
- ### Reactivity Hooks
184
-
185
- | Hook | Description |
186
- | --------------------------- | ----------------------------------------- |
187
- | `useStore<T>(initialValue)` | Create a reactive store |
188
- | `useEffect(fn, deps?)` | Run side effects when dependencies change |
189
- | `useMemo<T>(fn, deps?)` | Memoize expensive computations |
190
- | `useId()` | Generate unique IDs |
191
- | `onMount(fn)` | Run code when component mounts |
192
- | `onCleanup(fn)` | Run cleanup code when component unmounts |
193
-
194
- ### Control Flow Components
195
-
196
- | Component | Description |
197
- | ----------------- | ------------------------------------------ |
198
- | `<Show>` | Conditional rendering with fallback |
199
- | `<For>` | Render lists with automatic key management |
200
- | `<Switch>` | Multiple conditional rendering |
201
- | `<Match>` | Case condition for Switch |
202
- | `<Suspense>` | Handle async operations |
203
- | `<ErrorBoundary>` | Catch and handle errors |
204
-
205
- ### Utilities
206
-
207
- | Utility | Description |
208
- | ------------------------------ | ----------------------------------------- |
209
- | `createContext<T>()` | Create a context for dependency injection |
210
- | `useContext<T>(context)` | Consume context values |
211
- | `lazy<T>(importFn)` | Lazy load components |
212
- | `render(component, container)` | Render component to DOM |
213
- | `Fragment` | Group elements without wrapper |
214
-
215
- ## 🔧 Advanced Usage
216
-
217
- ### Custom Hooks
218
-
219
- ```tsx
220
- import { useStore, useEffect } from "@shadow-js/core";
221
-
222
- function useLocalStorage<T>(key: string, initialValue: T) {
223
- const [storedValue, setStoredValue] = useStore<T>(() => {
224
- try {
225
- const item = localStorage.getItem(key);
226
- return item ? JSON.parse(item) : initialValue;
227
- } catch (error) {
228
- return initialValue;
229
- }
230
- });
63
+ const [todos, setTodos] = useStore<{ items: Todo[] }>({
64
+ items: [
65
+ { id: 1, title: "write docs", done: false },
66
+ { id: 2, title: "ship", done: false },
67
+ ],
68
+ });
231
69
 
70
+ createRoot((dispose) => {
232
71
  useEffect(() => {
233
- try {
234
- localStorage.setItem(key, JSON.stringify(storedValue()));
235
- } catch (error) {
236
- console.warn(`Error saving to localStorage:`, error);
237
- }
72
+ console.log(`first todo done: ${todos.items[0]?.done}`);
238
73
  });
74
+ flushSync();
239
75
 
240
- return [storedValue, setStoredValue] as const;
241
- }
242
- ```
243
-
244
- ### Context and Global State
76
+ setTodos("items", 1, "done", true); // the effect does not read item 1
77
+ flushSync();
245
78
 
246
- ```tsx
247
- import { createContext, useContext } from "@shadow-js/core";
248
-
249
- const ThemeContext = createContext();
250
-
251
- function ThemeProvider({ children }) {
252
- const [theme, setTheme] = useStore<"light" | "dark">("light");
253
-
254
- const toggleTheme = () => {
255
- setTheme(theme() === "light" ? "dark" : "light");
256
- };
257
-
258
- return (
259
- <ThemeContext.Provider value={{ theme, toggleTheme }}>
260
- {children}
261
- </ThemeContext.Provider>
262
- );
263
- }
264
-
265
- function useTheme() {
266
- const context = useContext(ThemeContext);
267
- if (!context) {
268
- throw new Error("useTheme must be used within ThemeProvider");
269
- }
270
- return context;
271
- }
272
- ```
273
-
274
- ### Error Boundaries
275
-
276
- ```tsx
277
- import { ErrorBoundary } from "@shadow-js/core";
278
-
279
- function App() {
280
- return (
281
- <ErrorBoundary fallback={(error) => <div>Error: {error.message}</div>}>
282
- <ComponentThatMightError />
283
- </ErrorBoundary>
284
- );
285
- }
286
- ```
287
-
288
- ## 🔌 Integration
289
-
290
- ### Vite Plugin
291
-
292
- For the best development experience, use the ShadowJS Vite plugin:
293
-
294
- **vite.config.ts**
295
-
296
- ```typescript
297
- import { defineConfig } from "vite";
298
- import shadow from "@shadow-js/vite";
299
-
300
- export default defineConfig({
301
- plugins: [shadow()],
79
+ setTodos((draft) => {
80
+ const first = draft.items[0];
81
+ if (first !== undefined) first.done = true;
82
+ });
83
+ flushSync();
84
+ dispose();
302
85
  });
303
86
  ```
304
87
 
305
- ### Manual JSX Setup
88
+ The compiler also keeps `const double = count() * 2;` live inside components
89
+ (forgiving reactivity); that is a compile-time
90
+ feature of [`@shadow-js/compiler`](../compiler/README.md), not of this package.
306
91
 
307
- If you prefer manual setup, configure your bundler to use ShadowJS JSX runtime:
92
+ ## API
308
93
 
309
- ```json
310
- {
311
- "compilerOptions": {
312
- "jsx": "react-jsx",
313
- "jsxImportSource": "@shadow-js/core"
314
- }
315
- }
316
- ```
94
+ Entry `@shadow-js/core`. The exports are listed below by purpose.
317
95
 
318
- ## 🎨 Styling
96
+ ### State
319
97
 
320
- ShadowJS works with any CSS solution:
98
+ | Export | Description |
99
+ | --- | --- |
100
+ | `useStore` | The state hook: a cell for a single value, a deep fine-grained store for plain data. |
101
+ | `useSignal` | The low-level single-value primitive `useStore` is built on; for library authors and `equals` overrides. |
102
+ | `useMemo` | A cached derivation that recomputes only when a dependency changed. |
103
+ | `useSelector` | A selection set over a source: `isSelected(key)` subscribes only to that key's boolean. |
104
+ | `useOptimistic` | State that shows a reducer applied over the real value while actions are pending. |
105
+ | `useReducer` | A state cell whose writes go through a reducer: `dispatch(action)` stores `reducer(state, action)`. |
106
+ | `useAction` | A form-style action: `dispatch` runs it, tracks whether it is pending, and commits only the latest result. |
107
+ | `useExternalStore` | Reads a value that lives outside ShadowJS (a store, a browser API, an observable) as a reactive accessor. |
108
+ | `produce`, `reconcile` | Draft updater marker and a diffing update for `setStore`. |
109
+ | `snapshot`, `unwrap` | A deep plain copy of a store, and the raw data behind it. |
321
110
 
322
- ```tsx
323
- // Inline styles (reactive)
324
- <div style={() => ({ color: theme() === "dark" ? "white" : "black" })}>
325
- Dynamic styling
326
- </div>
111
+ ### Effects, batching and ownership
327
112
 
328
- // CSS Classes
329
- <div className="my-component">
330
- Static styling
331
- </div>
332
-
333
- // CSS Modules
334
- import styles from "./Component.module.css";
335
- <div className={styles.container}>CSS Modules</div>
336
- ```
113
+ | Export | Description |
114
+ | --- | --- |
115
+ | `useEffect` | A side effect after rendering; `useEffect(fn)` or `useEffect(deps, fn, { defer })`. Never runs on the server. |
116
+ | `useRenderEffect` | Render-phase effect used for DOM bindings; runs synchronously when created. |
117
+ | `onMount`, `onCleanup`, `onError` | Lifecycle callbacks of the current owner. |
118
+ | `batch`, `flushSync` | Defer effects until the batch ends; flush every pending effect before returning. |
119
+ | `untrack` | Run a function without subscribing to what it reads. |
120
+ | `useEvent` | A stable callback that always runs its handler untracked. |
121
+ | `useReaction` | A tracker that reports the first change of what it reads, then stops observing until it tracks again. |
122
+ | `startTransition`, `useTransition`, `useDeferredValue` | Run updates in the transition lane, report whether one is pending, and follow a value in that lane. |
123
+ | `createRoot`, `getOwner`, `runWithOwner` | Create and use ownership scopes. |
124
+ | `catchError` | Run a function in a scope whose errors go to a handler. |
125
+ | `useId` | An id identical on server and client for the same position in the owner tree. |
337
126
 
338
- ## 🏗️ Architecture
127
+ ### Context, props and resources
339
128
 
340
- ShadowJS is built with performance and developer experience in mind:
129
+ | Export | Description |
130
+ | --- | --- |
131
+ | `createContext`, `useContext` | Provide a value to a subtree and read the nearest one. |
132
+ | `mergeProps`, `splitProps`, `children` | Getter-preserving props helpers and a memoized `props.children`. |
133
+ | `createRef`, `useImperativeHandle` | A ref object that also works as a ref callback, and publishing an imperative handle to a ref. |
134
+ | `cache` | Memoizes a function per request: within one root the same arguments return the same result. |
135
+ | `useResource` | Load asynchronous data reactively. The handle has `state`, `loading`, `error`, `latest`, `refetch` and `mutate`; reading it while loading holds the nearest `<Suspense>`. |
136
+ | `ResourceCacheContext`, `SuspenseContext` | The bridges that renderers and `<Suspense>` provide. |
341
137
 
342
- ### Fine-grained Reactivity System
138
+ Error handlers registered with `onError` or `catchError` run untracked. Signals read while handling
139
+ an error do not become dependencies of the computation that encountered it. The caller's tracking
140
+ resumes after the handler returns or rethrows.
343
141
 
344
- - **Automatic dependency tracking**: No manual dependency arrays
345
- - **Efficient updates**: Only affected components re-render
346
- - **Memory management**: Automatic cleanup of unused subscriptions
142
+ ### Lists
347
143
 
348
- ### Optimized Runtime
144
+ | Export | Description |
145
+ | --- | --- |
146
+ | `mapArray` | Maps each item of a list to a row that lives as long as the item does. |
147
+ | `indexArray` | Maps each position of a list to a row. |
349
148
 
350
- - **Minimal bundle size**: Core runtime is < 9KB gzipped
351
- - **Fast reconciliation**: Optimized DOM diffing algorithm
352
- - **Memory efficient**: Smart memory management and cleanup
149
+ ### Environment
353
150
 
354
- ### Developer Experience
151
+ | Export | Description |
152
+ | --- | --- |
153
+ | `isDev`, `isServer` | True in development builds; true in the server condition build. |
355
154
 
356
- - **TypeScript first**: Full type safety and IntelliSense
357
- - **Great error messages**: Clear error reporting and debugging
358
- - **Hot reload friendly**: Optimized for development workflows
155
+ The package also exports the types `Accessor`, `Setter`, `Cleanup`, `Equals`, `ErrorHandler`,
156
+ `Owner`, `Context`, `Ref`, `Store`, `SetStore`, `StoreResult`, `Mutable`, `Reconciler`, `Resource`,
157
+ `ResourceInfo`, `ResourceState`, `ResourceCache`, `SuspenseTracker`, `MergeProps`, `MergeSource`,
158
+ `SplitProps`, `ResolvedChildren`, `ListSource` and the option types of each hook.
359
159
 
360
- ## 📚 Examples
160
+ ### Subpath entries
361
161
 
362
- Check out the [examples documentation](../../documentation/examples.md) for comprehensive code examples covering:
162
+ | Entry | Contents |
163
+ | --- | --- |
164
+ | `@shadow-js/core/store` | The store module on its own: `useStore`, `produce`, `reconcile`, `snapshot`, `unwrap` and the store types. |
165
+ | `@shadow-js/core/extend` | The extension API the built-ins are made from: signal nodes (`createSignalNode`, `readSignal`, `writeSignal`), computations (`createComputation`), owners (`createOwner`, `addCleanup`, `disposeOwner`, `runInScope`), scheduling (`flush`, `schedule`, `group`) and diagnostics (`warn`, `ShadowError`, `setWarningListener`). |
363
166
 
364
- - Basic patterns and best practices
365
- - Advanced reactive patterns
366
- - Real-world application examples
367
- - Integration patterns
167
+ The `node`, `worker`, `deno` and `bun` conditions resolve to a server build in which effects never
168
+ run; the `development` condition selects the build with diagnostics.
368
169
 
369
- ## 🤝 Contributing
170
+ ## Links
370
171
 
371
- We welcome contributions! See the [Contributing Guide](../../CONTRIBUTING.md) for details.
172
+ - [`@shadow-js/web`](../web/README.md), [`@shadow-js/testing`](https://testing.shadowjs.net)
372
173
 
373
- ## 📄 License
174
+ ## Dependencies
374
175
 
375
- MIT License - see [LICENSE](../../LICENSE) for details.
176
+ - Runtime: none.
177
+ - Peers: none.
376
178
 
377
- ## 📞 Support
179
+ ## Types
378
180
 
379
- - **Documentation**: [ShadowJS Docs](../../README.md)
380
- - **Examples**: [Code Examples](../../documentation/examples.md)
381
- - **Issues**: [GitHub Issues](https://github.com/shadowjs-dev/shadow/issues)
382
- - **Discussions**: [GitHub Discussions](https://github.com/shadowjs-dev/shadow/discussions)
181
+ - Names from the root: `Accessor`, `Context`, `EffectOptions`, `Cleanup`, `ErrorHandler`, `MergeProps`, `Reconciler`.
182
+ - Type tests in `test-types/` are compile-time checks; `npm run typecheck:types` runs them.
383
183
 
384
- ---
184
+ ## Support
385
185
 
386
- Built by Jehaad AL-Johani for fine-grained reactivity.
186
+ - Node.js `>=22.12.0`. ESM only: use `import`; `require` is not supported.
187
+ - Browsers: current evergreen releases.
188
+ - Versioning: every `@shadow-js/*` package releases together at one version. Upgrade them as one set.
189
+ - Documentation: [ShadowJS documentation](https://shadowjs.net).
@@ -0,0 +1,34 @@
1
+ import { Accessor } from "./internal/types.js";
2
+ /**
3
+ * A state machine for a form-style action: `dispatch(...args)` runs `action(previous, ...args)`,
4
+ * tracks whether it is pending, and commits its result. The ShadowJS form of React's
5
+ * `useActionState` (state, dispatch, pending). `previous` is the last committed state.
6
+ *
7
+ * Only the latest dispatch commits: when two actions overlap, a slower result that settles after a
8
+ * newer dispatch is discarded, so the screen never goes back to an older answer. A failure does not
9
+ * change the state; it clears `pending` and is sent to the owner's error handler (`onError`), so an
10
+ * error boundary can show it. Without an owner the returned promise rejects instead.
11
+ *
12
+ * @param action `(previous, ...args) => next`, synchronous or async. It runs untracked.
13
+ * @param initialState The state before the first dispatch.
14
+ * @returns `[state, dispatch, pending]`. A synchronous result commits at once; `pending` is true
15
+ * only while a returned promise is unsettled. `dispatch` returns a promise that settles when this
16
+ * call has finished, whether it committed or not.
17
+ * @throws Nothing synchronously. Without an owner, the promise returned by `dispatch` rejects with
18
+ * the action's error. With an owner, the error goes to its error handler, or is reported as an
19
+ * uncaught error (`reportError`) when no handler is registered above it.
20
+ * @example
21
+ * import { useAction } from "@shadow-js/core";
22
+ *
23
+ * const [message, send, sending] = useAction(async (_prev: string, text: string) => {
24
+ * await fetch("/api/messages", { method: "POST", body: text });
25
+ * return `sent: ${text}`;
26
+ * }, "");
27
+ * void send("hello");
28
+ * console.log(sending(), message());
29
+ * @see useOptimistic
30
+ * @see useTransition
31
+ * @since 1.0.0
32
+ */
33
+ export declare function useAction<S, A extends unknown[]>(action: (previous: S, ...args: A) => S | PromiseLike<S>, initialState: S): [state: Accessor<S>, dispatch: (...args: A) => Promise<void>, pending: Accessor<boolean>];
34
+ //# sourceMappingURL=action.d.ts.map