kopular 0.19.0 → 0.20.0

package/LLM.md

@@ -584,6 +584,30 @@ Dependencies are explicit constructor arguments, not automatically tracked. Fixe
 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

@@ -674,6 +674,41 @@ has no array-of-function-values type, and no way to express "N sources of N diff
 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.19.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",
@@ -34,6 +34,7 @@
     "./http": "./src/http.js",
     "./forms": "./src/forms.js",
     "./computed": "./src/computed.js",
+    "./resource": "./src/resource.js",
     "./testing": "./src/testing.js"
   },
   "files": [
@@ -43,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 && ks build src/computed.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/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;
+    }
+  }
+}