@cascateer/core 2.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to NPM
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Verify version matches tag
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          VERSION="${TAG#v}"
+          FILE_VERSION=$(node -p "require('./package.json').version")
+          if [ "$VERSION" != "$FILE_VERSION" ]; then
+            echo "Version mismatch: tag=$VERSION, package.json=$FILE_VERSION"
+            exit 1
+          fi
+
+      - name: Publish to NPM
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public --provenance

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@cascateer/core",
+  "version": "2.0.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cascateer/core.git"
+  },
+  "scripts": {
+    "patch": "npm version patch && git push origin main --tags"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./jsx-runtime": "./src/jsx-runtime.ts",
+    "./jsx-dev-runtime": "./src/jsx-dev-runtime.ts",
+    "./lib": "./src/lib/index.ts",
+    "./operators": "./src/operators/index.ts"
+  },
+  "devDependencies": {
+    "@types/lodash": "^4.17.20",
+    "@types/object-hash": "^3.0.6",
+    "@types/react": "^19.2.14",
+    "typescript": "~5.8.3",
+    "vite": "^8.0.7"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21",
+    "object-hash": "^3.0.0",
+    "rxjs": "^7.8.2",
+    "uuid": "^13.0.0"
+  }
+}

package/src/api.ts

@@ -0,0 +1,188 @@
+import {
+  constant,
+  Dictionary,
+  intersectionWith,
+  isEqual,
+  isFunction,
+  memoize,
+} from "lodash";
+import objectHash from "object-hash";
+import {
+  BehaviorSubject,
+  combineLatest,
+  filter,
+  lastValueFrom,
+  map,
+  NextObserver,
+  Observable,
+  repeat,
+  shareReplay,
+  Subject,
+  tap,
+  UnaryFunction,
+} from "rxjs";
+import { asObservable, ExtendableDictionary, property } from "./lib";
+import { TapObservable } from "./observable";
+import { tapSubscription } from "./operators";
+import {
+  Action,
+  Effect,
+  MaybeArray,
+  MaybeObservable,
+  TapEffect,
+} from "./types";
+
+interface TagsConstructor<Args, Result> {
+  (args: Args, result: Result): string[];
+}
+
+interface MemoizableConfig<Args, Result> {
+  predicate: UnaryFunction<Args, MaybeObservable<{ data: Result }>>;
+  tags: TagsConstructor<Args, Result> | MaybeArray<string>;
+}
+
+class Memoizable<Args, Result> {
+  predicate: UnaryFunction<Args, Observable<Result>>;
+  tags: TagsConstructor<Args, Result>;
+
+  subscribe: UnaryFunction<Observable<string[]>, TapEffect<Args, Result>>;
+
+  share: UnaryFunction<NextObserver<string[]>, Action<Args, Result>>;
+
+  constructor({ predicate, tags }: MemoizableConfig<Args, Result>) {
+    this.predicate = (args) =>
+      asObservable(predicate(args)).pipe(map(property("data")));
+    this.tags = isFunction(tags) ? tags : constant([tags].flat());
+
+    this.subscribe = (invalidatedTags) => {
+      const loading = new BehaviorSubject(false);
+      const effect: Effect<Args, Result> = memoize(
+        (args) =>
+          this.predicate(args).pipe(
+            tapSubscription(loading),
+            tap({
+              complete: () => loading.next(false),
+            }),
+            repeat({
+              delay: () =>
+                combineLatest([
+                  effect(args).pipe(map((result) => this.tags(args, result))),
+                  invalidatedTags,
+                ]).pipe(
+                  filter(([tags, invalidatedTags]) =>
+                    isEqual(tags, intersectionWith(tags, invalidatedTags)),
+                  ),
+                ),
+            }),
+            shareReplay({ bufferSize: 1, refCount: false }),
+          ),
+        (args) => objectHash(args ?? null),
+      );
+
+      return (args) => new TapObservable(effect(args), loading);
+    };
+
+    this.share = (invalidatedTags) => (args) =>
+      lastValueFrom(this.predicate(args)).then(
+        (result) => (invalidatedTags.next(this.tags(args, result)), result),
+      );
+  }
+}
+
+export interface ApiEffect<Args, Result> extends TapEffect<Args, Result> {}
+
+type ApiAdapterPropertyConstructor<Source, Type extends "effect" | "action"> = {
+  [T in Type]: <Args, Result>(
+    config: UnaryFunction<Source, MemoizableConfig<Args, Result>>,
+  ) => T extends "effect" ? ApiEffect<Args, Result> : Action<Args, Result>;
+}[Type];
+
+export class ApiAdapter<
+  Effects extends Dictionary<ApiEffect<any, any>>,
+  Actions extends Dictionary<Action<any, any>>,
+> {
+  constructor(
+    public effects: Effects,
+    public actions: Actions,
+  ) {}
+}
+
+export class ExtendableApiAdapter<
+  Source,
+  Effects extends Dictionary<ApiEffect<any, any>>,
+  Actions extends Dictionary<Action<any, any>>,
+> {
+  complete(): ApiAdapter<Effects, Actions> {
+    return new ApiAdapter(
+      this.extendableEffects.complete(),
+      this.extendableActions.complete(),
+    );
+  }
+
+  constructor(
+    public context: {
+      source: Source;
+      invalidatedTags: Subject<string[]>;
+    },
+    private extendableEffects: ExtendableDictionary<
+      ApiEffect<any, any>,
+      Effects
+    >,
+    private extendableActions: ExtendableDictionary<Action<any, any>, Actions>,
+  ) {}
+
+  provideEffects<MoreEffects extends Dictionary<ApiEffect<any, any>>>(
+    effects: UnaryFunction<
+      { effect: ApiAdapterPropertyConstructor<Source, "effect"> },
+      MoreEffects
+    >,
+  ) {
+    return new ExtendableApiAdapter(
+      this.context,
+      this.extendableEffects.extend(
+        () => () =>
+          effects({
+            effect: (config) =>
+              new Memoizable(config(this.context.source)).subscribe(
+                this.context.invalidatedTags,
+              ),
+          }),
+      ),
+      this.extendableActions,
+    );
+  }
+
+  provideActions<MoreActions extends Dictionary<Action<any, any>>>(
+    actions: UnaryFunction<
+      { action: ApiAdapterPropertyConstructor<Source, "action"> },
+      MoreActions
+    >,
+  ) {
+    return new ExtendableApiAdapter(
+      this.context,
+      this.extendableEffects,
+      this.extendableActions.extend(
+        () => () =>
+          actions({
+            action: (config) =>
+              new Memoizable(config(this.context.source)).share(
+                this.context.invalidatedTags,
+              ),
+          }),
+      ),
+    );
+  }
+}
+
+export class ApiProvider<Source> extends ExtendableApiAdapter<Source, {}, {}> {
+  constructor(source: Source) {
+    super(
+      {
+        source,
+        invalidatedTags: new Subject(),
+      },
+      new ExtendableDictionary({}),
+      new ExtendableDictionary({}),
+    );
+  }
+}

package/src/app.ts

@@ -0,0 +1,36 @@
+import { Dictionary, mapValues } from "lodash";
+import { UnaryFunction } from "rxjs";
+import { createFragment } from ".";
+import { property } from "./lib";
+import { Slice, SliceAdapter, SliceProvider } from "./slice";
+
+export class App<
+  Slices extends Dictionary<Slice<any, any, any, any, any, any, any, any>>,
+> {
+  slices: Slices;
+  render: () => JSX.Element;
+
+  constructor(
+    slices: UnaryFunction<
+      {
+        SliceProvider: {
+          new (): SliceProvider;
+        };
+      },
+      SliceAdapter<Slices>
+    >,
+    render: UnaryFunction<Record<keyof Slices, JSX.Component>, JSX.Element>,
+  ) {
+    this.slices = slices({ SliceProvider }).slices;
+
+    this.render = () => render(mapValues(this.slices, property("render")));
+  }
+
+  appendTo(node: HTMLElement) {
+    return node.append(
+      createFragment({
+        children: this.render(),
+      }),
+    );
+  }
+}

package/src/component.ts

@@ -0,0 +1,153 @@
+import { Dictionary, kebabCase } from "lodash";
+import { defer, share, UnaryFunction } from "rxjs";
+import { createFragment } from ".";
+import { cssStyleSheets } from "./css";
+import { defineCustomElement } from "./dom";
+import { ExtendableDictionary } from "./lib";
+import { ComputedSignal } from "./observable";
+import { asStoreEffects, StoreAdapter, StoreEffects } from "./store";
+import { TerminalAdapter, TerminalEffect } from "./terminal";
+import { Action, Effect } from "./types";
+
+export class ComponentConstructor<Props extends JSX.Props> {
+  constructor(public predicate: UnaryFunction<string, JSX.Component<Props>>) {}
+}
+
+export function createComponent(customElement?: string) {
+  const withTemplate =
+    <Styles extends Promise<unknown>[]>(...styles: Styles) =>
+    <
+      Deps extends Dictionary<Effect<any, any> | Action<any, any>>,
+      Props extends JSX.Props,
+    >(
+      constructor: (
+        deps: Deps,
+        ...classNamesList: { -readonly [K in keyof Styles]: Awaited<Styles[K]> }
+      ) => JSX.Component<Props>,
+    ) =>
+      class extends ComponentConstructor<Props> {
+        constructor(deps: Deps) {
+          super(
+            (key) => (props) =>
+              createFragment({
+                children: defer(() =>
+                  Promise.all(styles).then((cssModules) =>
+                    cssStyleSheets(cssModules).then(async (cssStyleSheets) => {
+                      const element = constructor(deps, ...cssModules)(props);
+
+                      return customElement != null
+                        ? new (defineCustomElement(
+                            `${key}-${kebabCase(customElement)}`,
+                          ))(element, cssStyleSheets)
+                        : createFragment({
+                            children: element,
+                          }); /* TODO omit cssModules (whole workflow) */
+                    }),
+                  ),
+                ).pipe(share()),
+              }),
+          );
+        }
+      };
+
+  return {
+    withStyles: <Styles extends Promise<unknown>[]>(...styles: Styles) => ({
+      withTemplate: withTemplate(...styles),
+    }),
+    withTemplate: withTemplate(),
+  };
+}
+
+export class ComponentsAdapter<
+  Components extends Dictionary<ComponentConstructor<any>>,
+> {
+  constructor(public components: Components) {}
+}
+
+export class ExtendableComponentsAdapter<
+  StoreSignals extends Dictionary<ComputedSignal<any>>,
+  StoreActions extends Dictionary<Action<any, any>>,
+  TerminalEffects extends Dictionary<TerminalEffect<any, any>>,
+  TerminalActions extends Dictionary<Action<any, any>>,
+  Components extends Dictionary<ComponentConstructor<any>>,
+> {
+  complete(): ComponentsAdapter<Components> {
+    return new ComponentsAdapter(this.extendableComponents.complete());
+  }
+
+  constructor(
+    public context: {
+      store: StoreAdapter<StoreSignals, StoreActions>;
+      terminal: TerminalAdapter<TerminalEffects, TerminalActions>;
+    },
+    private extendableComponents: ExtendableDictionary<
+      ComponentConstructor<any>,
+      Components
+    >,
+  ) {}
+
+  provideComponents<
+    MoreComponents extends Dictionary<ComponentConstructor<any>>,
+  >(
+    components: UnaryFunction<
+      {
+        component: <Props extends JSX.Props>(
+          constructor: UnaryFunction<
+            {
+              store: {
+                effects: StoreEffects<StoreSignals>;
+                actions: StoreActions;
+              };
+              terminal: {
+                effects: TerminalEffects;
+                actions: TerminalActions;
+              };
+            },
+            ComponentConstructor<Props>
+          >,
+        ) => ComponentConstructor<Props>;
+      },
+      MoreComponents
+    >,
+  ) {
+    return new ExtendableComponentsAdapter(
+      this.context,
+      this.extendableComponents.extend(
+        () => () =>
+          components({
+            component: (constructor) =>
+              constructor({
+                store: {
+                  effects: asStoreEffects(this.context.store.signals),
+                  actions: this.context.store.actions,
+                },
+                terminal: {
+                  effects: this.context.terminal.effects,
+                  actions: this.context.terminal.actions,
+                },
+              }),
+          }),
+      ),
+    );
+  }
+}
+
+export class ComponentsProvider<
+  StoreSignals extends Dictionary<ComputedSignal<any>>,
+  StoreActions extends Dictionary<Action<any, any>>,
+  TerminalEffects extends Dictionary<TerminalEffect<any, any>>,
+  TerminalActions extends Dictionary<Action<any, any>>,
+> extends ExtendableComponentsAdapter<
+  StoreSignals,
+  StoreActions,
+  TerminalEffects,
+  TerminalActions,
+  {}
+> {
+  constructor(context: {
+    store: StoreAdapter<StoreSignals, StoreActions>;
+    terminal: TerminalAdapter<TerminalEffects, TerminalActions>;
+  }) {
+    super(context, new ExtendableDictionary({}));
+  }
+}

package/src/css.ts

@@ -0,0 +1,48 @@
+import { isObject, isString, once, tap } from "lodash";
+import { nonNullable } from "./lib";
+
+const cssImports = once(() =>
+  Promise.all(
+    [
+      ...Object.entries(import.meta.glob("/**/*.*css")),
+      ...Object.entries(import.meta.glob("/**/*.*css", { query: "?inline" })),
+    ].map(([url, load]) =>
+      load().then(async (module) => {
+        const DEFAULT_KEY = "default";
+
+        return {
+          url,
+          module,
+          styleSheet:
+            isObject(module) &&
+            DEFAULT_KEY in module &&
+            isString(module[DEFAULT_KEY])
+              ? await new CSSStyleSheet().replace(module[DEFAULT_KEY])
+              : null,
+        };
+      }),
+    ),
+  ).then((imports) =>
+    imports.reduce(
+      (imports, { url, module, styleSheet }) =>
+        tap(imports, ({ urls, styleSheets }) => {
+          urls.set(module, url);
+          styleSheets.set(
+            url,
+            (styleSheets.get(url) ?? []).concat(styleSheet ?? []),
+          );
+        }),
+      {
+        urls: new Map<unknown, string>(),
+        styleSheets: new Map<string, CSSStyleSheet[]>(),
+      },
+    ),
+  ),
+);
+
+export const cssStyleSheets = (modules: unknown[]) =>
+  cssImports().then(({ urls, styleSheets }) =>
+    modules.flatMap(
+      (module) => styleSheets.get(nonNullable(urls.get(module))) ?? [],
+    ),
+  );

package/src/dom.ts

@@ -0,0 +1,35 @@
+import { identity, isObject, memoize } from "lodash";
+import { createFragment } from ".";
+
+export class CustomElement extends HTMLElement {
+  constructor(children?: JSX.Children, styles: CSSStyleSheet[] = []) {
+    super();
+
+    const shadowRoot = this.attachShadow({ mode: "open" });
+
+    shadowRoot.adoptedStyleSheets.push(...styles);
+    shadowRoot.append(createFragment({ children }));
+  }
+}
+
+export const defineCustomElement = memoize((key: string) => {
+  const constructor = class extends CustomElement {};
+
+  customElements.define(key, constructor);
+
+  return constructor;
+}, identity);
+
+export const defineCustomProperties = (
+  definitions: Partial<JSX.CSSCustomPropertyDefinitions>,
+) => {
+  for (const [name, definition] of Object.entries(definitions)) {
+    if (isObject(definition) && "inherits" in definition) {
+      CSS.registerProperty({
+        ...definition,
+        inherits: Boolean(definition.inherits),
+        name,
+      });
+    }
+  }
+};

package/src/fragment.ts

@@ -0,0 +1,134 @@
+import { tap } from "lodash";
+import {
+  combineLatest,
+  distinctUntilChanged,
+  map,
+  Observable,
+  of,
+  scan,
+  share,
+  shareReplay,
+  startWith,
+  Subscription,
+  switchMap,
+} from "rxjs";
+import { asArray, asObservable } from "./lib";
+import { flatMap } from "./operators";
+
+export type Primitive =
+  | string
+  | number
+  | bigint
+  | boolean
+  | symbol
+  | null
+  | undefined;
+
+const isPrimitive = (value: unknown): value is Primitive =>
+  ["string", "number", "bigint", "boolean", "symbol"].includes(typeof value) ||
+  value == null;
+
+const insert = <T extends Node>(...nodes: T[]) => ({
+  before: (child: Node | null): T[] => {
+    for (const node of nodes) {
+      child?.parentNode?.insertBefore(node, child);
+    }
+
+    return nodes;
+  },
+});
+
+const remove = <T extends Node>(...nodes: T[]) => {
+  for (const node of nodes) {
+    node.parentNode?.removeChild(node);
+  }
+};
+
+class AnchorFragment extends DocumentFragment {
+  appendAnchor(current?: Comment) {
+    return {
+      current,
+      next: this.appendChild(new Comment("anchor")),
+    };
+  }
+
+  anchor = new Observable<Node[]>((subscriber) => {
+    const observer = tap(
+      new MutationObserver((records) =>
+        subscriber.next(records.flatMap((record) => [...record.removedNodes])),
+      ),
+      (observer) => observer.observe(this, { childList: true }),
+    );
+
+    return {
+      unsubscribe: () => observer.disconnect(),
+    };
+  }).pipe(
+    share(),
+    scan((anchor, removedNodes) => {
+      if (removedNodes.includes(anchor.next)) {
+        if (anchor.current != null) {
+          remove(anchor.current);
+        }
+
+        return this.appendAnchor(anchor.next);
+      }
+
+      return anchor;
+    }, this.appendAnchor()),
+    flatMap((anchor) => anchor.current ?? []),
+    distinctUntilChanged(),
+    shareReplay(1),
+  );
+
+  constructor() {
+    super();
+
+    this.anchor.subscribe();
+  }
+}
+
+export class ObservableFragment extends AnchorFragment {
+  subscription: Subscription;
+
+  get nodes(): Observable<Node[]> {
+    return asObservable(this.content).pipe(
+      map(asArray),
+      switchMap((elements) =>
+        combineLatest(
+          elements.map((element) =>
+            asObservable(element).pipe(
+              switchMap((element) =>
+                element instanceof ObservableFragment
+                  ? element.nodes
+                  : of(
+                      isPrimitive(element)
+                        ? new Text(element?.toString())
+                        : element,
+                    ),
+              ),
+              startWith(),
+            ),
+          ),
+        ),
+      ),
+      map((nodes) => nodes.flat()),
+    );
+  }
+
+  constructor(private content: JSX.Children = []) {
+    super();
+
+    this.subscription = combineLatest([this.anchor, this.nodes])
+      .pipe(
+        scan(
+          (currentNodes, [anchor, nextNodes]) => (
+            remove(...currentNodes),
+            insert(...nextNodes).before(anchor)
+          ),
+          new Array<Node>(),
+        ),
+      )
+      .subscribe();
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { ApiProvider } from "./api";
+export { App } from "./app";
+export { createComponent } from "./component";
+export { defineCustomProperties } from "./dom";
+export { createElement, createFragment } from "./jsx-runtime";
+export { createSlice } from "./slice";
+export { type StoreEffect } from "./store";
+export { type TerminalEffect } from "./terminal";
+export { type Action, type MaybeObservable } from "./types";

package/src/jsx-dev-runtime.ts

@@ -0,0 +1,4 @@
+import { createElement, createFragment } from "./jsx-runtime";
+
+export const jsxDEV = createElement;
+export const Fragment = createFragment;