kopular 0.3.0 → 0.4.0

package/LLM.md

@@ -1,13 +1,14 @@
 # Kopular — LLM reference
 
 Complete reference for generating correct Kopular code. This is a spec, not a tutorial —
-see `README.md` for narrative/rationale. Kopular is 4 files total; this covers all of
+see `README.md` for narrative/rationale. Kopular is 6 files total; this covers all of
 them. For the host language, see KopScript's own `LLM.md` in the `Kop` repo (or its
 published `LLM.md` on the `kopscript` npm package) — that reference is a prerequisite,
 not repeated here.
 
 Published as npm `kopular`. Entry points: `kopular` / `kopular/component` (Component),
-`kopular/router` (Router), `kopular/dom` (ambient DOM bindings), `kopular/directives` (If).
+`kopular/router` (Router), `kopular/dom` (ambient DOM bindings), `kopular/directives`
+(If), `kopular/http` (Http).
 
 ## Consuming Kopular from your own KopScript project
 
@@ -30,6 +31,19 @@ extern class Router {
 } from "kopular/router";
 
 extern Element If(bool condition, () => Element whenTrue, () => Element whenFalse) from "kopular/directives";
+
+extern class Response {
+  bool ok { get; }
+  number status { get; }
+  task<string> text();          // no `async` on an extern signature — see KopScript's own LLM.md
+};
+extern class Http {
+  static task<Response> Get(string url);
+  static task<Response> Post(string url, string jsonBody);
+  static task<Response> Put(string url, string jsonBody);
+  static task<Response> Patch(string url, string jsonBody);
+  static task<Response> Delete(string url);
+} from "kopular/http";
 ```
 
 You also need your own ambient DOM `extern` block (`document`, `Element`, `Event`, ...) —
@@ -145,6 +159,38 @@ that needs comparing old/new data by a caller key, generic over item type, and K
 has no generics. Not planned as a workaround; would need real language-level generics
 first.
 
+## `Http` (`http.ks`) — thin wrapper over `fetch`
+
+```ks
+Response r = await Http.Get(url);            // task<Response>
+Response r = await Http.Post(url, jsonBody); // string body, Content-Type: application/json
+Response r = await Http.Put(url, jsonBody);
+Response r = await Http.Patch(url, jsonBody);
+Response r = await Http.Delete(url);         // no body param — DELETE has none
+
+r.ok       // bool
+r.status   // number
+await r.text();   // task<string> — the raw body, nothing more
+```
+
+**No typed JSON deserialization** — no generics means no safe `Get<T>(url): task<T>`.
+Get a typed response by describing its shape as its own `extern class` and parsing with
+a per-shape `extern ... as "JSON.parse"` (unchecked, same trust model as every other
+`extern`):
+
+```ks
+extern class DogDto { string name { get; } };
+extern DogDto ParseDog(string json) as "JSON.parse";
+
+DogDto dog = ParseDog(await (await Http.Get(url)).text());
+```
+
+`Get`/`Delete` need no request body, so they bind straight to the real global `fetch` —
+no object literal involved (KopScript has none). `Post`/`Put`/`Patch` (and a
+hypothetical `Delete`-with-a-body) need one for `{ method, headers, body }`, which
+KopScript categorically cannot construct — Kopular ships one small hand-written JS
+function (`http_runtime.js`, not compiled from `.ks`) that does, for exactly that reason.
+
 ## Dependency injection — no container, no decorators
 
 There is no injector, no `@Injectable`, no provider tokens. "Injecting" a service is
@@ -194,5 +240,5 @@ class CounterService {
 DI container/injector · decorators (`@Injectable`, `@Component`, ...) · a template
 language/DSL — everything is imperative `Render()` code against plain DOM bindings ·
 vdom diffing / reconciliation beyond a single component's own re-render · pipes ·
-animations · forms/validation module · HTTP client · a CLI/scaffolding tool (`ng
-generate`-equivalent) · SSR.
+animations · forms/validation module · typed/generic HTTP responses (`Http` returns raw
+text — see above) · a CLI/scaffolding tool (`ng generate`-equivalent) · SSR.

package/README.md

@@ -33,6 +33,9 @@ Generating Kopular code with an AI coding assistant? Point it at **[`LLM.md`](./
   a subtree conditionally, repeat one per item, pick one of several cases — done as plain
   function calls (`If(...)`) and existing KopScript expressions (`array.ForEach(...)`,
   `match`), not special template syntax. See "Structural directives" below.
+- **`Http`**: a thin, static wrapper over the real Fetch API (`Http.Get(url)`,
+  `Http.Post(url, jsonBody)`, ...) — no HttpClient injection tokens, no RxJS
+  observables/operators. See "HTTP" below.
 
 ## What's here
 
@@ -42,8 +45,11 @@ Generating Kopular code with an AI coding assistant? Point it at **[`LLM.md`](./
 - `src/router.ks` — the `Router`.
 - `src/directives.ks` — `If()`, the structural-directive equivalents' one genuinely new
   piece (see below).
+- `src/http.ks` — `Http`, a thin wrapper over `fetch` (see below). `src/http_runtime.js`
+  is its one companion file — the single hand-written (not compiled from `.ks`) file in
+  Kopular, and why is explained in its own header comment.
 
-That's the whole framework — four files. Everything else (a real app built on top of it)
+That's the whole framework — six files. Everything else (a real app built on top of it)
 lives in a separate consumer repo, [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo).
 
 ## Dependency injection: the composition root pattern
@@ -179,6 +185,56 @@ caller-supplied key, generic over the item type — and KopScript has no generic
 per list, but that's real vdom-diffing work — already called out as out of scope in
 "Status" below, and not something these three lines take on.
 
+## HTTP
+
+```ks
+using "./http";
+
+Response r = await Http.Get("/api/dogs");
+if (r.ok) {
+  string body = await r.text();
+  print(body);
+}
+
+await Http.Post("/api/dogs", "{\"name\":\"Rex\"}");
+await Http.Put("/api/dogs/1", "{\"name\":\"Rexy\"}");
+await Http.Patch("/api/dogs/1", "{\"name\":\"Max\"}");
+await Http.Delete("/api/dogs/1");
+```
+
+`Http` is a thin, static wrapper over the real Fetch API — `Get`/`Post`/`Put`/`Patch`/
+`Delete`, each returning `task<Response>` (`.ok`, `.status`, `async text()`). No
+`HttpClient` to inject, no RxJS `Observable`/operators, no interceptors — call it from
+anywhere, including straight out of a service's own methods.
+
+**No typed JSON deserialization** — `Response.text()` gets you the raw body, nothing
+more. This isn't a corner cut for v1; it's a direct consequence of two things KopScript
+doesn't have: generics (so there's no safe way to write a general `Get<T>(url):
+task<T>`) and object-literal syntax (`{ ... }` as a value — see below). If you want a
+typed response, describe its shape as its own `extern class` and parse it yourself with
+a per-shape `extern ... as "JSON.parse"` declaration — the same trust-based approach
+`extern` already uses for everything else, not a new mechanism:
+
+```ks
+extern class DogDto {
+  string name { get; }
+};
+extern DogDto ParseDog(string json) as "JSON.parse";
+
+string body = await (await Http.Get("/api/dogs/1")).text();
+DogDto dog = ParseDog(body);   // unchecked, like a TypeScript `as DogDto` cast
+```
+
+**Why `Post`/`Put`/`Patch`/`Delete` aren't just `extern` bindings straight to `fetch`,
+the way `Get` is**: setting a request method/body/headers means passing `fetch` a second
+argument that's a plain JS object literal (`{ method, headers, body }`) — and KopScript
+has no object-literal syntax at all, so it can't construct one. `src/http_runtime.js` is
+one small hand-written function that does, and `Get`/`Delete`-with-no-body skip it
+entirely (`fetch(url)` alone needs no options object, so `Get` binds straight to the
+real global). It's the one file in this package not compiled from `.ks` — everywhere
+else avoids the problem by only wrapping JS APIs that take plain positional arguments
+(see `dom.ks`'s `addEventListener(string, handler)`, never an options-object-taking API).
+
 ## Using Kopular from another KopScript project
 
 KopScript's own `using "./path";` only resolves relative paths within a project — it has

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kopular",
-  "version": "0.3.0",
-  "description": "Kopular: a small component framework for KopScript — components, reactive state, constructor-injected services, and routing, with no template DSL and no DI container",
+  "version": "0.4.0",
+  "description": "Kopular: a small component framework for KopScript — components, reactive state, constructor-injected services, routing, structural directives, and HTTP, with no template DSL and no DI container",
   "type": "module",
   "license": "MIT",
   "author": "Joe Koppin <koppinjo@gmail.com>",
@@ -21,7 +21,8 @@
     "./component": "./src/component.js",
     "./router": "./src/router.js",
     "./dom": "./src/dom.js",
-    "./directives": "./src/directives.js"
+    "./directives": "./src/directives.js",
+    "./http": "./src/http.js"
   },
   "files": [
     "src",
@@ -29,13 +30,13 @@
     "LLM.md"
   ],
   "scripts": {
-    "build": "ks build src/router.ks && ks build src/directives.ks",
+    "build": "ks build src/router.ks && ks build src/directives.ks && ks build src/http.ks",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "kopscript": "^0.2.0",
+    "kopscript": "^0.3.0",
     "@types/jsdom": "^30.0.0",
     "@types/node": "^20.14.0",
     "jsdom": "^25.0.1",

package/src/http.js

@@ -0,0 +1,25 @@
+export const Response = globalThis.Response;
+export const FetchUrl = globalThis.fetch;
+import { requestWithBody as RequestWithBody } from "./http_runtime.js";
+export { RequestWithBody };
+export class Http {
+  static async Get(url) {
+    return await FetchUrl(url);
+  }
+
+  static async Delete(url) {
+    return await RequestWithBody(url, "DELETE", null, "application/json");
+  }
+
+  static async Post(url, jsonBody) {
+    return await RequestWithBody(url, "POST", jsonBody, "application/json");
+  }
+
+  static async Put(url, jsonBody) {
+    return await RequestWithBody(url, "PUT", jsonBody, "application/json");
+  }
+
+  static async Patch(url, jsonBody) {
+    return await RequestWithBody(url, "PATCH", jsonBody, "application/json");
+  }
+}

package/src/http.ks

@@ -0,0 +1,52 @@
+// A thin wrapper over the real Fetch API — no object literals (KopScript
+// has no syntax for one), no generics, no automatic JSON deserialization.
+// `Response.Text()` gets you the raw body; for a typed JSON response,
+// describe the shape as its own `extern class` and parse it with a
+// per-shape `extern ... as "JSON.parse"` declaration (see Kopular's README)
+// — the same trust-based approach `extern` already uses for everything
+// else, not a new mechanism.
+
+extern class Response {
+  bool ok { get; }
+  number status { get; }
+  task<string> text();
+};
+
+// GET/HEAD/DELETE-without-a-body need no options object at all, so they
+// bind straight to the real global `fetch` — no runtime helper involved.
+extern task<Response> FetchUrl(string url) as "fetch";
+
+// POST/PUT/PATCH (and DELETE-with-a-body) need to set a method/body/
+// headers, which does need an options object — the one thing in this file
+// that isn't a direct, unassisted binding to a real JS global. See
+// http_runtime.js for why, and for the only hand-written JS in this
+// package. A relative path, not a package-name one: this is Kopular
+// referencing its own sibling file (which isn't part of Kopular's public
+// API — only Http's static methods below are), not a consumer reaching
+// into Kopular from outside.
+extern task<Response> RequestWithBody(string url, string method, string? body, string contentType) from "./http_runtime.js" as "requestWithBody";
+
+// Static methods, not free functions, purely so call sites read as
+// `Http.Get(url)` / `Http.Post(url, body)` — there's no instance state here
+// to justify a real object.
+class Http {
+  public static async task<Response> Get(string url) {
+    return await FetchUrl(url);
+  }
+
+  public static async task<Response> Delete(string url) {
+    return await RequestWithBody(url, "DELETE", null, "application/json");
+  }
+
+  public static async task<Response> Post(string url, string jsonBody) {
+    return await RequestWithBody(url, "POST", jsonBody, "application/json");
+  }
+
+  public static async task<Response> Put(string url, string jsonBody) {
+    return await RequestWithBody(url, "PUT", jsonBody, "application/json");
+  }
+
+  public static async task<Response> Patch(string url, string jsonBody) {
+    return await RequestWithBody(url, "PATCH", jsonBody, "application/json");
+  }
+}

package/src/http_runtime.js

@@ -0,0 +1,15 @@
+// The one hand-written file in Kopular — every other .js file here is
+// compiled from a same-named .ks source. KopScript has no object-literal
+// syntax, so it can't construct `fetch`'s second (options) argument itself;
+// every other Kopular binding avoids this by only wrapping JS APIs that take
+// plain positional arguments (see dom.ks). `fetch(url)` alone needs no
+// options object at all (that's a plain `extern` in http.ks), but a request
+// with a body/headers does — this function exists so http.ks has something
+// with a real, callable, options-object-free signature to bind to.
+export function requestWithBody(url, method, body, contentType) {
+  return fetch(url, {
+    method,
+    headers: body === null ? undefined : { "Content-Type": contentType },
+    body: body === null ? undefined : body,
+  });
+}