kopular 0.18.0 → 0.20.0

package/LLM.md

@@ -564,6 +564,50 @@ via `.Touch()` on `OnBlur`. A **template** has real `[(value)]="Field"` sugar fo
 value-binding half (see "Templates" above); `Touch()` on blur still needs its own explicit
 `(blur)="Field.Touch()"` either way — `[(value)]` only ever wires `value`/`input`.
 
+## `Computed1<A, R>` / `Computed2<A, B, R>` (`computed.ks`)
+
+```ks
+state<number> price = state(10);
+state<number> qty = state(2);
+Computed2<number, number, number> total = new Computed2<number, number, number>(
+  price, qty, (number p, number q) => p * q);
+
+total.Value.Value              // 20 — recomputed whenever price OR qty changes
+total.Value.Subscribe((number v) => { ... });  // returns an unsubscribe handle, same as any state<T>
+```
+
+`useMemo`/Angular signals' `computed()` equivalent — built entirely on `state<T>`'s own
+`.Value`/`.Subscribe`, no new reactive primitive. `Value` is `state<R>`, not a bare `R` —
+KopScript's property grammar has no custom-getter syntax, so a computed value can't expose
+a self-recomputing property; `state<R>` already gives the right two members instead.
+Dependencies are explicit constructor arguments, not automatically tracked. Fixed arity (1
+source, 2 sources) — same array-of-function-values reason `CombineValidators2/3` are fixed;
+add a `Computed3<A, B, C, R>` the same way if ever needed.
+
+## `Resource<T>` (`resource.ks`)
+
+```ks
+enum AsyncStatus { Loading, Success, Failure }
+
+Resource<Response> r = new Resource<Response>(Http.Get(url));  // task already in flight
+r.Status.Subscribe((AsyncStatus s) => this.Update());
+
+match r.Status.Value {
+  AsyncStatus.Loading => ...,
+  AsyncStatus.Success => ... r.Data.Value ...,   // T?
+  AsyncStatus.Failure => ... r.Error.Value ...   // string?
+};
+```
+
+The loading/success/failure shape around a `task<T>`, as `state<T>` a `Component` renders
+and `Subscribe`s to — most commonly wrapping an `Http` call. `Status` starts at
+`AsyncStatus.Loading` immediately; the constructor's own handling of the task is
+fire-and-forget (there's no way to construct a `task` value outside an `async` function
+body to `await` it from the constructor itself — see "Async" above), so the caller must
+pass an ALREADY-STARTED task (call the `async` function first — `Http.Get(url)`, not
+something the constructor starts). `Status`/`Data`/`Error` transition together, exactly
+once, inside a `try`/`catch` around the `await` — whichever branch the task actually takes.
+
 ## `kopular/testing` (`testing.js`, hand-written JS, not compiled from `.ks`)
 
 ```ts

package/README.md

@@ -638,6 +638,77 @@ gets real sugar for exactly this — `[(value)]="Field"` desugars to `[value]="F
 `(input)="Field = e.target.value"` (see KopScript's own "Templates" docs) — since a
 markup file has no equivalent direct access to fall back on.
 
+## Computed values
+
+React's `useMemo`/Angular signals' `computed()` equivalent — a read-only value derived
+from one or more `state<T>` sources, recomputed and re-notified whenever a source changes:
+
+```ks
+using "./computed";
+
+state<number> price = state(10);
+state<number> qty = state(2);
+Computed2<number, number, number> total = new Computed2<number, number, number>(
+  price, qty, (number p, number q) => p * q);
+
+print(total.Value.Value);              // 20
+total.Value.Subscribe((number v) => print("total: " + v));
+price.Value = 15;                      // prints "total: 30"
+```
+
+`Value` is `state<R>`, not a bare `R` — KopScript's property grammar has no custom-getter
+syntax (only auto-implemented `{ get; }`/`{ get; set; }`), so a computed value can't expose
+a property that recomputes itself on read. `state<R>` already **is** the right shape for
+"read the current value, or subscribe to it changing" — `total.Value.Value`/
+`total.Value.Subscribe(...)` are the exact same two members any other `state<T>` has, not a
+parallel API to learn.
+
+Dependencies are explicit, not automatically tracked the way Angular signals infer their
+own by watching which signals get read during evaluation — that needs a live "currently
+evaluating" context threaded through every read, a different kind of feature from anything
+else here. Naming each source directly is one honest step short of automatic, consistent
+with explicit constructor arguments everywhere else in Kopular (dependency injection,
+routing). `Computed1<A, R>` covers one source; `Computed2<A, B, R>` covers two — fixed
+arity for the same reason `CombineValidators2`/`CombineValidators3` (above) are: KopScript
+has no array-of-function-values type, and no way to express "N sources of N different
+types" without one type parameter per source. Add a `Computed3<A, B, C, R>` the same way if
+a real derivation ever needs three.
+
+## Async data — `Resource<T>`
+
+The loading/success/failure shape almost every real app needs around a `task<T>` — most
+commonly wrapping an `Http` call — as reactive `state<T>` a `Component` can render and
+`Subscribe` to, instead of hand-rolling the same three fields and try/catch every time:
+
+```ks
+using "./resource";
+
+Resource<Response> dogs = new Resource<Response>(Http.Get("https://dog.ceo/api/breeds/list/all"));
+dogs.Status.Subscribe((AsyncStatus s) => this.Update());
+```
+
+```ks
+public override VElement Render() {
+  return match dogs.Status.Value {
+    AsyncStatus.Loading => this.BuildSpinner(),
+    AsyncStatus.Success => this.BuildList(dogs.Data.Value),
+    AsyncStatus.Failure => this.BuildError(dogs.Error.Value)
+  };
+}
+```
+
+`Status` starts at `AsyncStatus.Loading` the moment `Resource` is constructed — the
+operation is already in flight (`Http.Get(...)` above is called before `Resource` ever
+sees it; a `task<T>` value can only be produced by calling an `async` function, and
+`Resource`'s own constructor isn't one, so it always receives an already-started
+operation, never starts one itself). Its internal handling of that task is genuinely
+fire-and-forget from the constructor's point of view (there's no way to construct a
+`task` value outside an async function body to await it there instead — see KopScript's
+own "Async" docs) — `Status`/`Data`/`Error` transition together, exactly once, whichever
+branch the `task` actually takes. `match` over `AsyncStatus` gets the same real
+exhaustiveness checking any other enum `match` does — leaving out a case is a compile
+error, not a runtime blank screen.
+
 ## Starting a new project: `kp new`
 
 Everything in the next section — the `extern` bindings, plus a `vendor/kopular/` copy of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Kopular: a small component framework for KopScript — components, reactive state, constructor-injected services, routing, real compiled templates, and HTTP, with no DI container",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,8 @@
     "./directives": "./src/directives.js",
     "./http": "./src/http.js",
     "./forms": "./src/forms.js",
+    "./computed": "./src/computed.js",
+    "./resource": "./src/resource.js",
     "./testing": "./src/testing.js"
   },
   "files": [
@@ -42,7 +44,7 @@
     "LLM.md"
   ],
   "scripts": {
-    "build": "ks build src/router.ks && ks build src/directives.ks && ks build src/http.ks && ks build src/forms.ks",
+    "build": "ks build src/router.ks && ks build src/directives.ks && ks build src/http.ks && ks build src/forms.ks && ks build src/computed.ks && ks build src/resource.ks",
     "prepublishOnly": "npm run build",
     "pretest": "npm run build",
     "test": "vitest run",

package/src/computed.js

@@ -0,0 +1,37 @@
+class __KopState {
+  constructor(value) {
+    this._value = value;
+    this._listeners = [];
+  }
+  get Value() { return this._value; }
+  set Value(v) {
+    this._value = v;
+    for (const listener of this._listeners) listener(v);
+  }
+  Subscribe(listener) {
+    this._listeners.push(listener);
+    return () => { this._listeners = this._listeners.filter((l) => l !== listener); };
+  }
+}
+
+export class Computed1 {
+  constructor(source, compute) {
+    this.Value = new __KopState(compute(source.Value));
+    source.Subscribe((v) => {
+  this.Value.Value = compute(v);
+});
+  }
+}
+export class Computed2 {
+  constructor(a, b, compute) {
+    this.Value = new __KopState(compute(a.Value, b.Value));
+    a.Subscribe((v) => {
+  this.Value.Value = compute(v, b.Value);
+});
+    b.Subscribe((v) => {
+  this.Value.Value = compute(a.Value, v);
+});
+  }
+}
+
+//# sourceMappingURL=computed.js.map

package/src/computed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"computed.js","sources":["computed.ks"],"sourcesContent":["// Computed1<A, R>/Computed2<A, B, R>: a read-only reactive value derived\n// from one or more state<T> sources, recomputed and re-notified whenever\n// any source changes — React's useMemo/Angular signals' computed()\n// equivalent. No new reactive primitive: built entirely on state<T>'s\n// existing .Value/.Subscribe (including the unsubscribe handle Subscribe\n// now returns — see kopscript's own LLM.md), the same way FormField<T>\n// (forms.ks) is built on state<T> rather than introducing a second\n// reactive system.\n//\n// Deliberately EXPLICIT dependencies, not automatic tracking (the way\n// Angular signals' computed() infers its own deps by watching which\n// signals get read during evaluation) — that needs a live \"currently\n// evaluating\" context the compiler/runtime would have to thread through\n// every read, a different kind of feature than anything else here.\n// Naming each source explicitly is one honest step short of automatic,\n// consistent with this project's own \"explicit constructor args, no\n// hidden magic\" position elsewhere (dependency injection, routing).\n//\n// `Value` is `state<R>`, not a bare `R` — KopScript's declared-property\n// grammar has no way to write a custom getter body (only auto-implemented\n// `{ get; }`/`{ get; set; }`, backed by ordinary assignment), so a\n// Computed can't expose a property that recomputes itself on read. state<R>\n// already IS the \"read the current value, or subscribe to it changing\"\n// shape this needs — Value.Value / Value.Subscribe(...), the exact same\n// two members any other state<T> exposes, not a parallel API to learn.\n//\n// Fixed arity (1 and 2 sources) for the same reason CombineValidators2/3\n// (forms.ks) are fixed-arity, not a general array-taking form: KopScript\n// has no array-of-function-values type, and no way to express \"N sources\n// of N different types\" without one type parameter per source. Add\n// Computed3<A, B, C, R> the same way if a real derivation ever needs three.\nclass Computed1<A, R> {\n  public state<R> Value { get; }\n\n  constructor(state<A> source, (A) => R compute) {\n    this.Value = state(compute(source.Value));\n    source.Subscribe((A v) => { this.Value.Value = compute(v); });\n  }\n}\n\nclass Computed2<A, B, R> {\n  public state<R> Value { get; }\n\n  constructor(state<A> a, state<B> b, (A, B) => R compute) {\n    this.Value = state(compute(a.Value, b.Value));\n    a.Subscribe((A v) => { this.Value.Value = compute(v, b.Value); });\n    b.Subscribe((B v) => { this.Value.Value = compute(a.Value, v); });\n  }\n}\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;AA+BA;EAGE;IACa;IACK;EAA6B;;;;AAIjD;EAGE;IACa;IACA;EAA6B;;IAC7B;EAA6B"}

package/src/computed.ks

@@ -0,0 +1,49 @@
+// Computed1<A, R>/Computed2<A, B, R>: a read-only reactive value derived
+// from one or more state<T> sources, recomputed and re-notified whenever
+// any source changes — React's useMemo/Angular signals' computed()
+// equivalent. No new reactive primitive: built entirely on state<T>'s
+// existing .Value/.Subscribe (including the unsubscribe handle Subscribe
+// now returns — see kopscript's own LLM.md), the same way FormField<T>
+// (forms.ks) is built on state<T> rather than introducing a second
+// reactive system.
+//
+// Deliberately EXPLICIT dependencies, not automatic tracking (the way
+// Angular signals' computed() infers its own deps by watching which
+// signals get read during evaluation) — that needs a live "currently
+// evaluating" context the compiler/runtime would have to thread through
+// every read, a different kind of feature than anything else here.
+// Naming each source explicitly is one honest step short of automatic,
+// consistent with this project's own "explicit constructor args, no
+// hidden magic" position elsewhere (dependency injection, routing).
+//
+// `Value` is `state<R>`, not a bare `R` — KopScript's declared-property
+// grammar has no way to write a custom getter body (only auto-implemented
+// `{ get; }`/`{ get; set; }`, backed by ordinary assignment), so a
+// Computed can't expose a property that recomputes itself on read. state<R>
+// already IS the "read the current value, or subscribe to it changing"
+// shape this needs — Value.Value / Value.Subscribe(...), the exact same
+// two members any other state<T> exposes, not a parallel API to learn.
+//
+// Fixed arity (1 and 2 sources) for the same reason CombineValidators2/3
+// (forms.ks) are fixed-arity, not a general array-taking form: KopScript
+// has no array-of-function-values type, and no way to express "N sources
+// of N different types" without one type parameter per source. Add
+// Computed3<A, B, C, R> the same way if a real derivation ever needs three.
+class Computed1<A, R> {
+  public state<R> Value { get; }
+
+  constructor(state<A> source, (A) => R compute) {
+    this.Value = state(compute(source.Value));
+    source.Subscribe((A v) => { this.Value.Value = compute(v); });
+  }
+}
+
+class Computed2<A, B, R> {
+  public state<R> Value { get; }
+
+  constructor(state<A> a, state<B> b, (A, B) => R compute) {
+    this.Value = state(compute(a.Value, b.Value));
+    a.Subscribe((A v) => { this.Value.Value = compute(v, b.Value); });
+    b.Subscribe((B v) => { this.Value.Value = compute(a.Value, v); });
+  }
+}

package/src/resource.js

@@ -0,0 +1,38 @@
+class __KopState {
+  constructor(value) {
+    this._value = value;
+    this._listeners = [];
+  }
+  get Value() { return this._value; }
+  set Value(v) {
+    this._value = v;
+    for (const listener of this._listeners) listener(v);
+  }
+  Subscribe(listener) {
+    this._listeners.push(listener);
+    return () => { this._listeners = this._listeners.filter((l) => l !== listener); };
+  }
+}
+
+export const AsyncStatus = Object.freeze({ Loading: 0, Success: 1, Failure: 2 });
+export class Resource {
+  constructor(operation) {
+    this.Status = new __KopState(AsyncStatus.Loading);
+    this.Data = new __KopState(null);
+    this.Error = new __KopState(null);
+    this.Run(operation);
+  }
+
+  async Run(operation) {
+    try {
+      let result = await operation;
+      this.Data.Value = result;
+      this.Status.Value = AsyncStatus.Success;
+    } catch (message) {
+      this.Error.Value = message;
+      this.Status.Value = AsyncStatus.Failure;
+    }
+  }
+}
+
+//# sourceMappingURL=resource.js.map

package/src/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sources":["resource.ks"],"sourcesContent":["// Resource<T>: the \"loading / success / failure\" shape around a task<T>,\n// as reactive state<T> a Component can render and Subscribe to — React's\n// (commonly hand-rolled, or via a data-fetching library) loading-state\n// pattern / Angular's resource() equivalent.\nenum AsyncStatus { Loading, Success, Failure }\n\nclass Resource<T> {\n  public state<AsyncStatus> Status;\n  public state<T?> Data;\n  public state<string?> Error;\n\n  constructor(task<T> operation) {\n    this.Status = state(AsyncStatus.Loading);\n    this.Data = state(null);\n    this.Error = state(null);\n    this.Run(operation);\n  }\n\n  private async task Run(task<T> operation) {\n    try {\n      T result = await operation;\n      this.Data.Value = result;\n      this.Status.Value = AsyncStatus.Success;\n    } catch (string message) {\n      this.Error.Value = message;\n      this.Status.Value = AsyncStatus.Failure;\n    }\n  }\n}\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAIA;AAEA;EAKE;IACc;IACF;IACC;IACH;;;EAGI;IACZ;MACE;MACgB;MACE;;MAED;MACC"}

package/src/resource.ks

@@ -0,0 +1,29 @@
+// Resource<T>: the "loading / success / failure" shape around a task<T>,
+// as reactive state<T> a Component can render and Subscribe to — React's
+// (commonly hand-rolled, or via a data-fetching library) loading-state
+// pattern / Angular's resource() equivalent.
+enum AsyncStatus { Loading, Success, Failure }
+
+class Resource<T> {
+  public state<AsyncStatus> Status;
+  public state<T?> Data;
+  public state<string?> Error;
+
+  constructor(task<T> operation) {
+    this.Status = state(AsyncStatus.Loading);
+    this.Data = state(null);
+    this.Error = state(null);
+    this.Run(operation);
+  }
+
+  private async task Run(task<T> operation) {
+    try {
+      T result = await operation;
+      this.Data.Value = result;
+      this.Status.Value = AsyncStatus.Success;
+    } catch (string message) {
+      this.Error.Value = message;
+      this.Status.Value = AsyncStatus.Failure;
+    }
+  }
+}