@octoii-works/octoii-std 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -4,4 +4,8 @@ The notable changes of `@octoii-works/octoii-std`, newest first.
 
 ## [Unreleased]
 
+## [0.0.2] - 2026-10-31
+
+## [0.0.1] - 2026-10-31
+
 - First release: The general-purpose base library of Octoii: JSON, deltas, encodings, ids, schemas, async helpers, bounded text, SQLite, SSE and JSON-RPC.

package/README.md

@@ -0,0 +1,86 @@
+# @octoii-works/octoii-std
+
+The base every Octoii package stands on: JSON values and their changes, text encodings, hashes, ids, TypeBox
+validation, time and cancellation, a portable SQLite connection, Server-Sent Events, JSON-RPC 2.0, addresses and text
+diffs. It knows no agent, model or tool, and the same code runs on Bun, Node, browsers, workerd and the Hermes of
+React Native.
+
+Contents: [Where it sits](#where-it-sits) · [The subpaths](#the-subpaths) · [Everything from the caller](#everything-from-the-caller) ·
+[SQLite](#sqlite) · [Constants](#constants) · [Testing](#testing).
+
+## Where it sits
+
+```sh
+bun add @octoii-works/octoii-std
+```
+
+- **At the bottom.** std depends on TypeBox alone, and every other Octoii package depends on it.
+- **No root entry.** Every import names its subpath, so a program loads only what it uses:
+
+  ```ts
+  import { parseJson, type JsonValue } from "@octoii-works/octoii-std/json";
+  import { matches } from "@octoii-works/octoii-std/schema";
+  ```
+
+## The subpaths
+
+| Subpath | What it gives |
+| --- | --- |
+| `/json` | The JSON value model every package shares, `JsonValue` and `JsonObject`, with checks, `jsonEqual`, `copyJson` and a `parseJson` whose keys are own data only |
+| `/delta` | How a JSON value changed, as operations: `diffJson` and `applyOps` |
+| `/encoding` | UTF-8, base64, base64url and hex, strict when asked, so a value read back is the value written |
+| `/hash` | SHA-256 in plain JavaScript, synchronous on every platform, and HMAC, PKCE and the check of an RSA signature on it |
+| `/id` | UUIDs of versions 4 and 7, from the randomness and the time the caller passes |
+| `/schema` | TypeBox validators compiled once per schema, `matches`, `parsed` and `validationProblems`, with the same results where code cannot be generated |
+| `/async` | Clocks, `sleep`, timeouts (`withinLimit`), cancellation (`abortable`, `linkedSignal`) and backoff |
+| `/errors` | `errorMessage` for an unknown error, and `unreachable` |
+| `/sqlite` | A synchronous SQLite connection, `SqlDriver`, and consecutive schema migrations; its adapters are `/sqlite/bun`, `/sqlite/node` and `/sqlite/worker` |
+| `/sse` | An incremental Server-Sent Events decoder that does no I/O |
+| `/json-rpc` | JSON-RPC 2.0 messages, their checks, and the error codes as `JSON_RPC_ERRORS` |
+| `/url` | Absolute addresses parsed and normalized without a platform URL parser, and their queries |
+| `/text` | Text as editing tools read it: sizes and line counts, line endings, line diffs and the unified diff, and an edit's tiers |
+| `/testing` | `portabilityProblems`, the scan of platform-neutral sources against what Hermes lacks |
+
+## Everything from the caller
+
+std reads no clock, timer, randomness or environment of its own: a function that needs one takes it.
+
+```ts
+import { systemClock, withinLimit } from "@octoii-works/octoii-std/async";
+import { uuidv7 } from "@octoii-works/octoii-std/id";
+
+const random = (length: number) => crypto.getRandomValues(new Uint8Array(length));
+const id = uuidv7(systemClock.now(), random);
+const answer = await withinLimit(fetch("https://example.com"), 5_000, systemClock);
+if ("timedOut" in answer) console.log("gave up after 5 s");
+```
+
+So a test passes a fake clock and fixed bytes, and gets the same results every run.
+
+## SQLite
+
+```ts
+import { bunSqlite } from "@octoii-works/octoii-std/sqlite/bun";
+import { migrate } from "@octoii-works/octoii-std/sqlite";
+
+const db = bunSqlite("app.db", { durability: "full" });
+migrate(db, [
+	"CREATE TABLE notes (id TEXT PRIMARY KEY, text TEXT NOT NULL)",
+	"ALTER TABLE notes ADD COLUMN at INTEGER",
+]);
+```
+
+- **One interface, three platforms.** `bunSqlite` on Bun, `nodeSqlite` on Node, `durableObjectSql` in a Durable Object;
+  code written against `SqlDriver` runs on all three.
+- **Synchronous.** Every statement returns its rows, so a transaction never waits in the middle.
+- **Migrations count on.** `migrate` runs the statements past the schema's version, each once, in order.
+
+## Constants
+
+std's codes and limits are in one module, and each subpath gives those of its own, such as `JSON_RPC_ERRORS` from
+`/json-rpc`, `DIFF_CONTEXT_LINES` from `/text` and `PKCE_VERIFIER_BYTES` from `/hash`.
+
+## Testing
+
+Each module's tests run on Bun and on Node. `portabilityProblems` from `/testing` is what every Octoii package's tests
+use to keep platform-neutral code within what Hermes runs.

package/package.json

@@ -1,15 +1,15 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@octoii-works/octoii-std",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "The general-purpose base library of Octoii: JSON, deltas, encodings, ids, schemas, async helpers, bounded text, SQLite, SSE and JSON-RPC",
   "type": "module",
   "license": "MIT",
   "author": "Elian Yang (https://elianyang.com)",
-  "homepage": "https://github.com/octoii-works/octoii/tree/main/packages/std#readme",
+  "homepage": "https://github.com/octoii-works/octoii-siphon/tree/main/packages/std#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/octoii-works/octoii.git",
+    "url": "git+https://github.com/octoii-works/octoii-siphon.git",
     "directory": "packages/std"
   },
   "publishConfig": {