mythik 0.1.2 → 0.1.3

package/docs/wiki/compiled/concept-action-chains.md

@@ -7,15 +7,15 @@ sources: [docs/consumer/ai-context.md#actions, docs/consumer/ai-context-patterns
 
 # Action chains — sequential execution
 
-Wire multiple actions to one event by passing an array. **Each action
-completes before the next starts** — sequential dispatch with state commit
-between steps.
+Wire multiple actions to one event by passing an array. **Each entry
+completes before the next starts** — sequential dispatch with state commit
+between steps. Entries can be normal action bindings or transaction bindings.
 
 ## Shape / Signature
 
-```json
-{ "on": { "press": [<action>, <action>, <action>] } }
-```
+```json
+{ "on": { "press": [<action-or-transaction>, <action-or-transaction>] } }
+```
 
 ## Examples
 
@@ -28,27 +28,65 @@ Save then close + refresh:
 ]
 ```
 
-Set state then navigate (the navigated screen sees the new state):
-```json
-"press": [
-  { "action": "setState", "params": { "statePath": "/draft", "value": { "$state": "/form" } } },
-  { "action": "navigateScreen", "params": { "screen": "review" } }
-]
-```
-
-## Commit semantics
-
-Each action in a sequential chain commits state before the next runs.
-`[setState, navigateScreen]` works — the navigated screen sees the state
-written by `setState`.
+Set state then navigate (the navigated screen sees the new state):
+```json
+"press": [
+  { "action": "setState", "params": { "statePath": "/draft", "value": { "$state": "/form" } } },
+  { "action": "navigateScreen", "params": { "screen": "review" } }
+]
+```
+
+Action before a transaction:
+```json
+"press": [
+  { "action": "setState", "params": { "statePath": "/ui/saving", "value": true } },
+  {
+    "transaction": {
+      "optimistic": [{ "action": "setState", "params": { "statePath": "/items", "value": { "$array": "append", "source": { "$state": "/items" }, "item": { "$state": "/draft" } } } }],
+      "confirm": [{ "action": "fetch", "params": { "url": "/api/items", "method": "POST", "body": { "$state": "/draft" } } }],
+      "onError": [{ "action": "showNotification", "params": { "type": "error", "message": { "$state": "/tx/error/message" } } }]
+    }
+  },
+  { "action": "setState", "params": { "statePath": "/ui/saving", "value": false } }
+]
+```
+
+Conditional action guard:
+```json
+{
+  "action": "fetch",
+  "params": {
+    "skipIf": { "$not": { "$state": "/form/isDirty" } },
+    "url": "/api/save",
+    "method": "POST",
+    "body": { "$state": "/form" }
+  }
+}
+```
+
+## Commit semantics
+
+Each entry in a sequential chain commits state before the next runs.
+`[setState, navigateScreen]` works — the navigated screen sees the state
+written by `setState`.
+
+For a transaction entry, Mythik waits for the transaction to finish before the
+next event-array entry runs. Transaction phases themselves still follow the
+transaction timing rules.
 
 ## Constraints / Anti-patterns
 
-- **Chains do NOT stop on failure.** `validateForm` marks errors but does
-  NOT halt subsequent actions. Use `submitForm` with `formId` instead. See
-  [[@antipattern-action-chain-no-stop]].
-- For background dispatch (next action immediately), use
-  [[@concept-fire-and-forget]].
+- **Chains do NOT stop on failure.** `validateForm` marks errors but does
+  NOT halt subsequent actions. Use `submitForm` with `formId` instead. See
+  [[@antipattern-action-chain-no-stop]].
+- **`skipIf` skips one action, not the whole chain.** It is resolved at
+  dispatch time before other params and removed before the action handler
+  runs. Use it for small dispatch-time guards, not for form validation or
+  transaction rollback.
+- **Do not nest transactions.** An event array may contain a transaction, but
+  transaction phases cannot contain another transaction binding.
+- For background dispatch (next action immediately), use
+  [[@concept-fire-and-forget]].
 - For optimistic CRUD UX, prefer [[@concept-transactions]] over plain chains.
 
 ## Related concepts

package/docs/wiki/compiled/concept-package-layout.md

@@ -12,17 +12,19 @@ sources: [docs/consumer/ai-context.md, docs/consumer/WHERE-TO-LOOK.md]
 | Package | Purpose |
 |---|---|
 | `mythik` | Browser-safe core. State, expressions, validation, renderer engine, design, auth, data, security, and browser-safe spec stores |
-| `mythik/server` | Node-only spec stores: `FileSpecStore`, `SqlServerSpecStore`, and versioned/environment variants |
+| `mythik/server` | Node-only spec stores, SQL drivers, and SQL DDL helpers: `FileSpecStore`, `SqlSpecStore`, `SqlVersionedSpecStore`, `SqlEnvironmentStore`, `createSqlDriver`, `getSqlStoreDdl`, and SQL Server compatibility stores |
 | `mythik-react` | React host, renderer, and web primitives |
 | `mythik-cli` | CLI package; installs the `mythik` command |
 | `mythik-cli/api` | Programmatic CLI API: `runPush`, `runPatch`, `runLint`, `parsePatchInput`, and types |
 | `mythik-server` | Express server runtime for ApiSpecs |
 
-React Native work lives in the repository as a preview track and is not part of the initial npm publish surface.
+React Native work lives in the repository as a preview track and is not part of the supported npm publish surface yet.
 
 ## Browser vs server core entries
 
-The default `mythik` entry is browser-safe by construction. Node-only stores live behind the `mythik/server` subpath so browser bundles do not pull `fs`, `mssql`, or other Node-only dependencies.
+The default `mythik` entry is browser-safe by construction. Node-only stores and SQL drivers live behind the `mythik/server` subpath so browser bundles do not pull `fs`, SQL adapters, or other Node-only dependencies.
+
+SQL adapters (`mssql`, `pg`, `mysql2`, `better-sqlite3`) are optional dependencies of `mythik`. npm/pnpm install optional dependencies by default; if optional dependencies are omitted, install the adapter for the database in use.
 
 ## Programmatic CLI API
 

package/docs/wiki/compiled/concept-public-package-names.md

@@ -12,7 +12,7 @@ Mythik publishes unscoped npm packages. Do not generate scoped package imports f
 | Public package | Use |
 |---|---|
 | `mythik` | Browser-safe core runtime, state, expressions, validation, browser-safe stores |
-| `mythik/server` | Node-only stores exported from the core package subpath |
+| `mythik/server` | Node-only stores, SQL drivers, and SQL DDL helpers exported from the core package subpath |
 | `mythik-react` | React host, renderer, and web primitives |
 | `mythik-cli` | CLI package; installs the `mythik` binary |
 | `mythik-cli/api` | Programmatic CLI API: `runPush`, `runPatch`, `runLint`, and related types |
@@ -28,6 +28,8 @@ npm install mythik mythik-react
 npm install -D mythik-cli
 ```
 
-Add `mythik-server` only when building a Mythik-backed Node server. React Native work is a repository preview track, not part of the initial npm publish surface.
+Add `mythik-server` only when building a Mythik-backed Node server. React Native work is a repository preview track, not part of the supported npm publish surface yet.
+
+SQL adapters (`mssql`, `pg`, `mysql2`, `better-sqlite3`) are optional dependencies of `mythik`. They install by default with npm/pnpm unless optional dependencies are omitted.
 
 Related: [[@cli-docs]], [[@cli-programmatic-api]], [[@concept-spec-stores-catalog]], [[@concept-where-to-look]].

package/docs/wiki/compiled/concept-shape-animations.md

@@ -30,7 +30,7 @@ useShapeAnimations(ref, animations, options)
 ## RN variant
 
 `packages/react-native/src/animation/useShapeAnimations.ts` — repository
-preview implementation. It is not part of the initial npm publish surface.
+preview implementation. It is not part of the supported npm publish surface yet.
 
 ```ts
 useShapeAnimations(animations, options) → { animatedProps }

package/docs/wiki/compiled/concept-spec-stores-catalog.md

@@ -2,7 +2,7 @@
 id: concept-spec-stores-catalog
 title: Spec stores catalog
 kind: concept
-sources: [docs/consumer/ai-context-runtime-semantics.md#54-specstore-layering--save-vs-saveversion-vs-cli-patch]
+sources: [docs/consumer/ai-context-runtime-semantics.md#54-specstore-layering--save-vs-saveversion-vs-cli-patch]
 ---
 
 # Spec stores catalog
@@ -20,18 +20,23 @@ sources: [docs/consumer/ai-context-runtime-semantics.md#54-specstore-layering--s
 
 ## Node-only (`mythik/server`)
 
-| Store | Purpose |
-|---|---|
-| `FileSpecStore` | Local filesystem (`fs`) |
-| `SqlServerSpecStore` | SQL Server (via `mssql`) |
-| `SqlServerVersionedSpecStore` | + version history |
-| `SqlServerEnvironmentStore` | + env promotions |
+| Store | Purpose |
+|---|---|
+| `FileSpecStore` | Local filesystem (`fs`) |
+| `SqlSpecStore` | Generic SQL store over a `SqlDriver` |
+| `SqlVersionedSpecStore` | Generic SQL store + version history |
+| `SqlEnvironmentStore` | Generic SQL store + env promotions |
+| `SqlServerSpecStore` | SQL Server compatibility wrapper |
+| `SqlServerVersionedSpecStore` | SQL Server compatibility wrapper + version history |
+| `SqlServerEnvironmentStore` | SQL Server compatibility wrapper + env promotions |
+
+Supported SQL driver dialects: SQL Server, PostgreSQL, MySQL, and SQLite.
 
 ## Why split
 
-Pre-v0.1.0 shape pulled `mssql` (Node-only) and `fs` into any browser
-bundle that imported `mythik`. v0.1.0 structural split makes
-`mythik` browser-safe **by construction** — no bundler stubs
+The structural split keeps `mythik` browser-safe **by construction**:
+browser bundles import the default entry, while Node hosts import
+`mythik/server` for filesystem stores, SQL stores, and SQL adapters.
 
 ## Imports
 
@@ -39,9 +44,16 @@ bundle that imported `mythik`. v0.1.0 structural split makes
 // Browser-safe
 import { SupabaseSpecStore, MemorySpecStore } from 'mythik';
 
-// Node-only
-import { SqlServerSpecStore, FileSpecStore } from 'mythik/server';
-```
+// Node-only
+import { FileSpecStore, SqlSpecStore, createSqlDriver } from 'mythik/server';
+
+const driver = createSqlDriver({
+  dialect: 'postgres',
+  connection: process.env.DATABASE_URL!,
+});
+
+const store = new SqlSpecStore({ driver });
+```
 
 ## Configurable table names
 
@@ -49,9 +61,9 @@ Default `'screens'`. Override via constructor — see
 [[@concept-storage-custom-names]].
 
 ```ts
-new SqlServerSpecStore({ ..., table: 'api_specs' })
-new SupabaseSpecStore({ ..., table: 'api_specs' })
-```
+new SqlSpecStore({ driver, table: 'api_specs' })
+new SupabaseSpecStore({ ..., table: 'api_specs' })
+```
 
 ## Related concepts
 

package/docs/wiki/compiled/concept-transactions.md

@@ -7,10 +7,14 @@ sources: [docs/consumer/ai-context.md#transactions-optimistic-updates, docs/cons
 
 # Transactions — optimistic CRUD with rollback
 
-Use `transaction` for CRUD operations that need instant UI feedback. The
-framework takes a state snapshot before `optimistic`, applies your changes
-instantly, then confirms with the server. **On failure, it rolls back
-automatically.**
+Use `transaction` for CRUD operations that need instant UI feedback. The
+framework takes a state snapshot before `optimistic`, applies your changes
+instantly, then confirms with the server. **On failure, it rolls back
+automatically.**
+
+A transaction can be used directly as an event binding or as one entry inside
+an event action array. When mixed with normal actions in an event array,
+Mythik awaits the transaction before running the next entry.
 
 ## Shape / Signature
 
@@ -55,17 +59,21 @@ Default 10 seconds. Override:
 
 ## Constraints / Anti-patterns
 
-- **`submitForm` in `confirm` is NOT recommended.** It has its own validation
-  gate that conflicts with the transaction engine. Use `fetch` in `confirm`
-  instead. See [[@antipattern-submit-form-in-tx-confirm]].
-- **UPDATE transactions don't need `onSuccess`** — re-fetch causes flash.
-  See [[@pattern-tx-update]].
+- **`submitForm` in `confirm` is NOT recommended.** It has its own validation
+  gate that conflicts with the transaction engine. Use `fetch` in `confirm`
+  instead. See [[@antipattern-submit-form-in-tx-confirm]].
+- **Do not nest transactions.** An event array may contain transaction
+  bindings, but `before`, `optimistic`, `confirm`, `onSuccess`, and `onError`
+  phases contain normal action bindings only.
+- **UPDATE transactions don't need `onSuccess`** — re-fetch causes flash.
+  See [[@pattern-tx-update]].
 
 ## Related concepts
 
-- [[@concept-transaction-phase-timing]]
-- [[@concept-transaction-rollback]]
-- [[@concept-transaction-snapshot]]
+- [[@concept-transaction-phase-timing]]
+- [[@concept-transaction-rollback]]
+- [[@concept-transaction-snapshot]]
+- [[@concept-action-chains]]
 - [[@pattern-tx-create]] / [[@pattern-tx-update]] / [[@pattern-tx-delete]] / [[@pattern-tx-toggle]]
 - [[@path-tx-result-error]]
 

package/docs/wiki/compiled/expression-let-ref.md

@@ -8,9 +8,12 @@ sources: [docs/consumer/ai-context.md#named-bindings, docs/consumer/reference-do
 # `$let` / `$ref` — named bindings
 
 `$let` defines named bindings; `$in` is the expression that uses them.
-References use `$ref`. Use to define a value once and reference it multiple
-times — particularly useful when `$item` or a complex expression must be
-captured for use in `$template`.
+References use `$ref`. Use to define a value once and reference it multiple
+times — particularly useful when `$item` or a complex expression must be
+captured for use in `$template`.
+
+`$ref` can read nested values from an object binding with dot notation. The
+same dotted binding lookup is available inside `$template` placeholders.
 
 ## Shape / Signature
 
@@ -35,17 +38,28 @@ Array form (preserves order — use when stored in JSONB):
 
 ## Examples
 
-Capture `$item` for `$template` (the most common use):
-```json
-{
-  "$let": { "x": { "$item": "name" } },
-  "$in": { "$template": "Editing: ${x}" }
-}
-```
-
-Multi-step computation:
-```json
-{
+Capture `$item` for `$template` (the most common use):
+```json
+{
+  "$let": { "x": { "$item": "name" } },
+  "$in": { "$template": "Editing: ${x}" }
+}
+```
+
+Read nested object fields:
+```json
+{
+  "$let": { "user": { "$state": "/auth/user" } },
+  "$in": {
+    "label": { "$ref": "user.name" },
+    "message": { "$template": "Welcome, ${user.name}" }
+  }
+}
+```
+
+Multi-step computation:
+```json
+{
   "$let": {
     "total": { "$array": "count", "source": { "$state": "/items" } },
     "label": { "$template": "${total} items" }
@@ -70,10 +84,14 @@ In a composite template:
 
 ## Constraints / Anti-patterns
 
-- **Use array form when storing in JSONB.** Object key order is not
-  preserved by JSONB — if bindings reference each other via `$ref`, use
-  the array form to guarantee evaluation order. See rule 4.
-- Object form is fine when bindings don't reference each other.
+- **Use array form when storing in JSONB.** Object key order is not
+  preserved by JSONB — if bindings reference each other via `$ref`, use
+  the array form to guarantee evaluation order. See rule 4.
+- **Fix missing dotted `$ref` segments.** A path such as
+  `{ "$ref": "user.name" }` expects `user` to exist as a binding and `name`
+  to exist on that object. Missing dotted segments are invalid references,
+  not optional data.
+- Object form is fine when bindings don't reference each other.
 
 ## Related concepts
 

package/docs/wiki/compiled/expression-template.md

@@ -7,8 +7,9 @@ sources: [docs/consumer/ai-context.md#values--formatting, docs/consumer/ai-conte
 
 # `$template` — string interpolation
 
-`$template` interpolates values into a string. Two reference forms:
-`${/state/path}` reads from state, `${name}` reads from a `$let` binding.
+`$template` interpolates values into a string. Two reference forms:
+`${/state/path}` reads from state, `${name}` or `${user.name}` reads from a
+`$let` binding.
 Resolves at the consumption site — at render in element props, at dispatch in
 action params.
 
@@ -30,21 +31,31 @@ URL with state:
 { "$template": "${/config/apiUrl}/rest/v1/items?id=eq.${/form/editId}" }
 ```
 
-Combined with `$let` (when `$item` is needed inside `$template`):
-```json
-{
-  "$let": { "x": { "$item": "name" } },
-  "$in": { "$template": "Editing: ${x}" }
-}
-```
-
-## Constraints / Anti-patterns
-
-- **`$template` does NOT resolve `$item` directly.** `$item` is a JSON
-  expression, not a string token. Capture in `$let` first (see example
-  above) — see also [[@concept-expression-contexts]].
-- **`$template` does NOT resolve in transaction phases.** Capture row data
-  via `setState` before the transaction fires.
+Combined with `$let` (when `$item` is needed inside `$template`):
+```json
+{
+  "$let": { "x": { "$item": "name" } },
+  "$in": { "$template": "Editing: ${x}" }
+}
+```
+
+Nested `$let` binding:
+```json
+{
+  "$let": { "user": { "$state": "/auth/user" } },
+  "$in": { "$template": "Welcome, ${user.name}" }
+}
+```
+
+## Constraints / Anti-patterns
+
+- **`$template` does NOT resolve `$item` directly.** `$item` is a JSON
+  expression, not a string token. Capture in `$let` first (see example
+  above) — see also [[@concept-expression-contexts]].
+- **Dotted `$let` binding placeholders require the binding path to exist.**
+  Use them for known object bindings, not optional deep probing.
+- **`$template` does NOT resolve in transaction phases.** Capture row data
+  via `setState` before the transaction fires.
 - **Plain strings containing `${...}` are LITERAL** in `DataSourceConfig.url`.
   Wrap in `$template` to enable templating — the validator catches plain
   strings with `${...}` and points to the fix. See

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mythik",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Spec-driven core runtime for validated JSON applications, APIs, editor sessions, state, actions, validation, and versioning.",
   "license": "Apache-2.0",
   "type": "module",
@@ -44,7 +44,6 @@
   },
   "dependencies": {
     "isomorphic-dompurify": "^3.9.0",
-    "mssql": "^12.2.1",
     "zustand": "^5.0.0"
   },
   "devDependencies": {
@@ -52,6 +51,12 @@
     "es-module-lexer": "^2.0.0",
     "typescript": "^5.7.0"
   },
+  "optionalDependencies": {
+    "better-sqlite3": "^12.9.0",
+    "mssql": "^12.2.1",
+    "mysql2": "^3.22.3",
+    "pg": "^8.20.0"
+  },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc",
     "typecheck": "node ../../node_modules/typescript/bin/tsc --noEmit"