@magicdoor/magic-use-case-solid 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# @magicdoor/magic-use-case-solid
+
+## 0.1.0
+
+### Minor Changes
+
+- First release of `magic-use-case` — clean-architecture use cases and
+  presentations for front-end TypeScript, consolidating the previous
+  `solid-use-case`, `solid-use-case-core` and `solid-use-case-react` packages
+  into one project.
+
+  **Use cases and presentations.** `UseCase` holds application logic; a
+  `Presentation` — a pure function from state to a view model — is what a screen
+  renders. Both are framework-agnostic, bound to your framework by a thin
+  adapter: `useUseCase`, `usePresenter`, `ErrorHandler` and `Navigator`.
+
+  **A presentation is a value, not a subclass.** `usePresenter(presentTenants)`
+  takes the function itself, so two screens that need the same rule share it by
+  calling the same function, and one presentation can back several presenters.
+  `Presenter` is exported as infrastructure — it holds a presentation and reruns
+  it on every state change — not as a base class to extend. Presenters given the
+  same presentation share one run of it: the model is built once per state
+  change and handed to all of them. Sharing is by the identity of the function
+  object, so it survives minification, which mangles names and can leave two
+  unrelated functions sharing one. The model handed to a component is readonly —
+  `usePresenter` returns `DeepReadonly<TModel>`, enforced by the compiler and at
+  runtime — since one model is shared by every screen using that presentation. A
+  presentation is only ever called with state: `resetAppState()` empties every
+  model directly, rather than asking each presentation to map an absence. One that throws anyway
+  is reported to the console and leaves its model empty, rather than failing the
+  render or the emit that other screens are waiting on.
+
+  **A use case can run other use cases.** A run announces its work unless
+  somebody is waiting on it: a nested run stays silent and its caller announces
+  everything written beneath it, once. Two flows a screen started independently
+  announce independently, so a long initialization never holds back the fetch a
+  page made for itself. Navigation is not held back either, so a nested use case
+  still moves the screen the moment it decides to.
+
+  **Failures propagate.** `execute()` rejects, so a nested failure aborts its
+  caller and a sequence of steps is a sequence. The failure reaches `onError`
+  exactly once, from the outermost run. A caller that catches decides what the
+  failure means and only what it throws is reported; a caller that handles it
+  reports nothing, and `report()` is there for the case that recovers but still
+  wants the screen to know. A use case that writes state and then throws still
+  announces what it wrote.
+
+  **State is only mutable inside a use case.** `getState()` returns a deep proxy
+  that accepts writes only while a use case runs. Writing elsewhere throws rather
+  than silently desyncing the UI, since such a write emits no state-change event.
+  A presentation receives a fully readonly view and can never write.
+
+  **In-place or immutable, your choice.** Mutating state in place and replacing
+  branches with new frozen values are both supported, including in the same use
+  case. State built with `Object.freeze` reads back correctly.
+
+  **State is adopted, not borrowed.** The object returned from `initializeState()`
+  is deep-cloned, so the caller's reference is no longer live state. The clone
+  preserves prototypes, keeping class-based state class-based. `#private` fields
+  cannot be cloned — use TypeScript `private` or a `_` prefix.
+
+  **Bootstrapping happens exactly once**, decided by the library rather than by
+  each use case, so no use case can replace live state by accident.
+  `resetAppState()` — protected, callable only from within a running use case — is
+  the one way to clear state and bootstrap again.
+
+  **The state type is pinned to the application's.** An application names its
+  state type once by augmenting `MagicUseCaseTypes`, and `usePresenter` then
+  accepts only presentations written against it. Without that, a presentation's
+  state type is whatever the presentation claims, and one written against the
+  wrong shape compiles cleanly and fails on the screen.
+
+  **Server-side rendering** resolves a scope per request, so two requests never
+  share state, the event bus, or a presentation's model. Everything that makes
+  up a running application lives in one scope, and on a server that scope
+  belongs to the request being served. Solid needs nothing from you: its server
+  build reads the request from `getRequestEvent()` and keeps that request's
+  scope beside it. React has no request context of its own, so
+  `@magicdoor/magic-use-case-react/server` exports `runInRequestScope()`, which
+  the host opens once per request; the subpath is what keeps `node:async_hooks`
+  out of browser bundles. Rendering outside a request throws rather than falling
+  back to a shared scope, because a silent fallback is the leak this prevents.
+
+  **State can travel to the browser**, so a page rendered with data is not
+  fetched again while it hydrates. It is opt-in and it is one line: Solid
+  renders `<StateTransfer />` once in its tree, React puts
+  `serializedStateScript()` in its document, and the browser adopts what it
+  finds as the package loads. Application state has to be data — objects,
+  arrays, sets, maps, dates, primitives — since a class instance cannot cross
+  without its prototype. Two things to weigh: everything in state reaches the
+  page in plain text, and the payload is an inline script, so a strict
+  `script-src` needs a nonce.
+
+  `createScope()` hands back an opaque handle: the only thing an application can
+  do with a scope is give it to `setScopeResolver()`, since the bus and the
+  state inside it are the library's own.
+
+  `@magicdoor/magic-use-case-core` is internal and never published — it is bundled into each
+  adapter, so the adapters' exports are the entire supported API surface.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                             Apache License
+                       Version 2.0, January 2004
+                    http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+  "License" shall mean the terms and conditions for use, reproduction,
+  and distribution as defined by Sections 1 through 9 of this document.
+
+  "Licensor" shall mean the copyright owner or entity authorized by
+  the copyright owner that is granting the License.
+
+  "Legal Entity" shall mean the union of the acting entity and all
+  other entities that control, are controlled by, or are under common
+  control with that entity. For the purposes of this definition,
+  "control" means (i) the power, direct or indirect, to cause the
+  direction or management of such entity, whether by contract or
+  otherwise, or (ii) ownership of fifty percent (50%) or more of the
+  outstanding shares, or (iii) beneficial ownership of such entity.
+
+  "You" (or "Your") shall mean an individual or Legal Entity
+  exercising permissions granted by this License.
+
+  "Source" form shall mean the preferred form for making modifications,
+  including but not limited to software source code, documentation
+  source, and configuration files.
+
+  "Object" form shall mean any form resulting from mechanical
+  transformation or translation of a Source form, including but
+  not limited to compiled object code, generated documentation,
+  and conversions to other media types.
+
+  "Work" shall mean the work of authorship, whether in Source or
+  Object form, made available under the License, as indicated by a
+  copyright notice that is included in or attached to the work
+  (an example is provided in the Appendix below).
+
+  "Derivative Works" shall mean any work, whether in Source or Object
+  form, that is based on (or derived from) the Work and for which the
+  editorial revisions, annotations, elaborations, or other modifications
+  represent, as a whole, an original work of authorship. For the purposes
+  of this License, Derivative Works shall not include works that remain
+  separable from, or merely link (or bind by name) to the interfaces of,
+  the Work and Derivative Works thereof.
+
+  "Contribution" shall mean any work of authorship, including
+  the original version of the Work and any modifications or additions
+  to that Work or Derivative Works thereof, that is intentionally
+  submitted to Licensor for inclusion in the Work by the copyright owner
+  or by an individual or Legal Entity authorized to submit on behalf of
+  the copyright owner. For the purposes of this definition, "submitted"
+  means any form of electronic, verbal, or written communication sent
+  to the Licensor or its representatives, including but not limited to
+  communication on electronic mailing lists, source code control systems,
+  and issue tracking systems that are managed by, or on behalf of, the
+  Licensor for the purpose of discussing and improving the Work, but
+  excluding communication that is conspicuously marked or otherwise
+  designated in writing by the copyright owner as "Not a Contribution."
+
+  "Contributor" shall mean Licensor and any individual or Legal Entity
+  on behalf of whom a Contribution has been received by Licensor and
+  subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+  this License, each Contributor hereby grants to You a perpetual,
+  worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+  copyright license to reproduce, prepare Derivative Works of,
+  publicly display, publicly perform, sublicense, and distribute the
+  Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+  this License, each Contributor hereby grants to You a perpetual,
+  worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+  (except as stated in this section) patent license to make, have made,
+  use, offer to sell, sell, import, and otherwise transfer the Work,
+  where such license applies only to those patent claims licensable
+  by such Contributor that are necessarily infringed by their
+  Contribution(s) alone or by combination of their Contribution(s)
+  with the Work to which such Contribution(s) was submitted. If You
+  institute patent litigation against any entity (including a
+  cross-claim or counterclaim in a lawsuit) alleging that the Work
+  or a Contribution incorporated within the Work constitutes direct
+  or contributory patent infringement, then any patent licenses
+  granted to You under this License for that Work shall terminate
+  as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+  Work or Derivative Works thereof in any medium, with or without
+  modifications, and in Source or Object form, provided that You
+  meet the following conditions:
+
+  (a) You must give any other recipients of the Work or
+      Derivative Works a copy of this License; and
+
+  (b) You must cause any modified files to carry prominent notices
+      stating that You changed the files; and
+
+  (c) You must retain, in the Source form of any Derivative Works
+      that You distribute, all copyright, patent, trademark, and
+      attribution notices from the Source form of the Work,
+      excluding those notices that do not pertain to any part of
+      the Derivative Works; and
+
+  (d) If the Work includes a "NOTICE" text file as part of its
+      distribution, then any Derivative Works that You distribute must
+      include a readable copy of the attribution notices contained
+      within such NOTICE file, excluding those notices that do not
+      pertain to any part of the Derivative Works, in at least one
+      of the following places: within a NOTICE text file distributed
+      as part of the Derivative Works; within the Source form or
+      documentation, if provided along with the Derivative Works; or,
+      within a display generated by the Derivative Works, if and
+      wherever such third-party notices normally appear. The contents
+      of the NOTICE file are for informational purposes only and
+      do not modify the License. You may add Your own attribution
+      notices within Derivative Works that You distribute, alongside
+      or as an addendum to the NOTICE text from the Work, provided
+      that such additional attribution notices cannot be construed
+      as modifying the License.
+
+  You may add Your own copyright statement to Your modifications and
+  may provide additional or different license terms and conditions
+  for use, reproduction, or distribution of Your modifications, or
+  for any such Derivative Works as a whole, provided Your use,
+  reproduction, and distribution of the Work otherwise complies with
+  the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+  any Contribution intentionally submitted for inclusion in the Work
+  by You to the Licensor shall be under the terms and conditions of
+  this License, without any additional terms or conditions.
+  Notwithstanding the above, nothing herein shall supersede or modify
+  the terms of any separate license agreement you may have executed
+  with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+  names, trademarks, service marks, or product names of the Licensor,
+  except as required for reasonable and customary use in describing the
+  origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+  agreed to in writing, Licensor provides the Work (and each
+  Contributor provides its Contributions) on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+  implied, including, without limitation, any warranties or conditions
+  of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+  PARTICULAR PURPOSE. You are solely responsible for determining the
+  appropriateness of using or redistributing the Work and assume any
+  risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+  whether in tort (including negligence), contract, or otherwise,
+  unless required by applicable law (such as deliberate and grossly
+  negligent acts) or agreed to in writing, shall any Contributor be
+  liable to You for damages, including any direct, indirect, special,
+  incidental, or consequential damages of any character arising as a
+  result of this License or out of the use or inability to use the
+  Work (including but not limited to damages for loss of goodwill,
+  work stoppage, computer failure or malfunction, or any and all
+  other commercial damages or losses), even if such Contributor
+  has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+  the Work or Derivative Works thereof, You may choose to offer,
+  and charge a fee for, acceptance of support, warranty, indemnity,
+  or other liability obligations and/or rights consistent with this
+  License. However, in accepting such obligations, You may act only
+  on Your own behalf and on Your sole responsibility, not on behalf
+  of any other Contributor, and only if You agree to indemnify,
+  defend, and hold each Contributor harmless for any liability
+  incurred by, or claims asserted against, such Contributor by reason
+  of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 MagicDoor, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,33 @@
+# @magicdoor/magic-use-case-solid
+
+SolidJS >1.9.3 bindings for [magic-use-case](https://github.com/MagicDoorInc/magic-use-case) —
+clean-architecture use cases and presentations for front-end TypeScript.
+
+```bash
+npm install @magicdoor/magic-use-case-solid
+```
+
+## Exports
+
+- `UseCase` — base class for your application logic
+- `Presentation` — the type of a function mapping state to a view model
+- `DeepReadonly` — the type of a model as a screen sees it
+- `useUseCase` — execute a use case, with loading, progress and success state
+- `usePresenter` — subscribe a component to a presentation's model
+- `Presenter` — the presentation holder behind `usePresenter`, for wiring of your own
+- `ErrorHandler` — error boundary wired to the use-case error channel
+- `Navigator` — bridges use-case navigation events to your router
+- `onError` / `onNavigation` — subscribe to those two channels directly
+- `createScope` / `setScopeResolver` — one scope per request, for server rendering
+
+New to it? The [main README](https://github.com/MagicDoorInc/magic-use-case#readme)
+introduces the five players, walks a complete feature in five steps, and sets out
+the rules the library is built around.
+
+## Credits
+
+Created by Norbert Nemes.
+
+## License
+
+Apache-2.0 © MagicDoor, Inc.

package/dist/index.d.ts

@@ -0,0 +1,173 @@
+import * as solid_js from 'solid-js';
+import { JSXElement } from 'solid-js';
+
+/**
+ * The whole of what a screen needs written by hand: a pure function from
+ * application state to the model the view renders. It is called again on every
+ * state change, so it must derive its result from `state` alone.
+ *
+ * Presentations are plain functions, so two screens that need the same rule
+ * share it by calling the same function — no class hierarchy, and no presenter
+ * constructed inside another presenter. Sharing is by identity: pass the same
+ * function and the work is done once for all of them.
+ */
+type Presentation<TState, TModel extends object> = (state: TState) => TModel | undefined;
+
+declare const scopeBrand: unique symbol;
+/**
+ * A scope, as everything outside the library sees it: a value to hand back to
+ * `setScopeResolver`, and nothing more. The bus, the state and the bookkeeping
+ * are the library's own.
+ */
+interface ScopeHandle {
+    readonly [scopeBrand]?: never;
+}
+declare function createScope(initialState?: unknown): ScopeHandle;
+/**
+ * Installed by the server build to resolve a scope per request. Left alone,
+ * every caller shares the one browser scope.
+ */
+declare function setScopeResolver(resolver: () => ScopeHandle): void;
+declare function onError(handler: (error: Error) => void): () => void;
+declare function onNavigation(handler: (url: string) => void): () => void;
+
+type UseCaseClass<T> = new (...args: any[]) => UseCase<T>;
+declare abstract class UseCase<T> {
+    protected onProgress?: (progress: number) => void;
+    constructor(onProgress?: (progress: number) => void);
+    /** Resolved per emit, so an execution always announces on the scope it is running in. */
+    private get eventEmitter();
+    execute(params?: unknown): Promise<void>;
+    /**
+     * Starts a use case that this one does not wait for. It runs on its own: the
+     * caller returns and announces its own changes immediately, and the detached
+     * run announces its own when it lands. Nobody is waiting on it, so its failure
+     * is reported rather than thrown.
+     */
+    protected detach(UseCaseClass: UseCaseClass<T>, params?: unknown): void;
+    private run;
+    protected getState(): T;
+    /**
+     * Clears application state so the next execution bootstraps it again.
+     *
+     * All four pieces of module state go together: the state itself, the
+     * emitter's retained copy, the in-flight dedup map, and any bootstrap in
+     * flight. Leaving any one behind resurrects the old state.
+     */
+    protected resetAppState(): void;
+    protected navigate(url: string): void;
+    /**
+     * Announces a failure the screen should hear about, for a use case that
+     * handles the failure rather than rethrowing it. Anything rethrown is
+     * reported on its way out and must not be reported here as well.
+     */
+    protected report(error: Error): void;
+    protected abstract runLogic(params: unknown): Promise<void>;
+    protected abstract initializeState(): Promise<T>;
+    /**
+     * A run announces its work unless somebody is waiting on it. A nested run
+     * stays silent and its caller announces everything written beneath it, once.
+     *
+     * Whether a run has a caller is known when it starts, which is what keeps an
+     * unrelated run finishing at the same moment from being swallowed: two flows
+     * a screen started independently each reach it on their own.
+     */
+    private runWithUpdate;
+    private announceUnlessCallerWill;
+    /**
+     * Counting who is running cannot tell a caller from an unrelated run that
+     * happens to overlap, and guessing wrong loses the failure entirely. Whether
+     * this run has a caller is known when it starts, so that is what decides.
+     */
+    private reportUnlessCallerWill;
+}
+
+/**
+ * Infrastructure, not a place for logic: it subscribes to the model built by a
+ * presentation and pushes it at whoever is listening. Adapters construct it —
+ * `usePresenter(presentation)` — so application code writes presentations and
+ * never touches this class.
+ *
+ * Presenters that were given the same presentation share one run of it: the
+ * model is built once per state change and handed to all of them.
+ */
+declare class Presenter<TState, TModel extends object> {
+    private model;
+    private subscribers;
+    private presentation;
+    private source;
+    private onModel;
+    private scope;
+    constructor(presentation: Presentation<TState, TModel>);
+    subscribe(listener: (model?: TModel) => void): void;
+    unsubscribe(listener: (model?: TModel) => void): void;
+    private notifySubscribers;
+    destroy(): void;
+}
+
+type AnyFunction = (...args: never[]) => unknown;
+/** What a presentation's model looks like to the screen rendering it. */
+type DeepReadonly<T> = T extends AnyFunction ? T : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<K, DeepReadonly<V>> : T extends ReadonlySet<infer V> ? ReadonlySet<DeepReadonly<V>> : T extends ReadonlyArray<infer V> ? ReadonlyArray<DeepReadonly<V>> : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+
+declare function useUseCase<T>(UseCaseClass: UseCaseClass<T>): {
+    execute: (params?: unknown) => Promise<void>;
+    isLoading: solid_js.Accessor<boolean>;
+    didSucceed: solid_js.Accessor<boolean>;
+    progress: solid_js.Accessor<number>;
+};
+
+interface ErrorDialogProps {
+    error: Error;
+    onClose: () => void;
+}
+interface ErrorHandlerProps {
+    children: JSXElement;
+    onWillReportError: (error: Error) => boolean;
+    onDidReportError?: (error: Error) => void;
+    renderErrorDialog: (props: ErrorDialogProps) => JSXElement;
+}
+declare const ErrorHandler: (props: ErrorHandlerProps) => solid_js.JSX.Element;
+
+interface NavigatorProps {
+    onNavigate?: (url: string) => void;
+}
+declare const Navigator: (props: NavigatorProps) => null;
+
+/**
+ * What a browser build renders for `<StateTransfer />`: nothing.
+ *
+ * Handing state over is something a server render does; there is no request to
+ * hand over here, and the browser has already adopted whatever the server left.
+ * Keeping this separate from the server version is what leaves the serializer —
+ * and the several kilobytes of it — out of the browser bundle entirely.
+ */
+declare const StateTransfer: () => null;
+
+/**
+ * Augmented by the application to name the type its use cases keep state in:
+ *
+ *     declare module '@magicdoor/magic-use-case-solid' {
+ *       interface MagicUseCaseTypes {
+ *         state: MyAppState;
+ *       }
+ *     }
+ *
+ * Until an application does, presentations go unchecked, which is how one can
+ * declare a state type the application never emits and fail only at runtime.
+ */
+interface MagicUseCaseTypes {
+}
+type ApplicationState = MagicUseCaseTypes extends {
+    state: infer TState;
+} ? TState : any;
+/**
+ * Declared here rather than re-exported, so an application's augmentation of
+ * this module merges with the interface above.
+ */
+declare function usePresenter<TModel extends object>(presentation: Presentation<ApplicationState, TModel>): {
+    model: solid_js.Accessor<DeepReadonly<TModel> | undefined>;
+};
+
+export { type DeepReadonly, ErrorHandler, type MagicUseCaseTypes, Navigator, type Presentation, Presenter, StateTransfer, UseCase, createScope, onError, onNavigation, setScopeResolver, usePresenter, useUseCase };