@absolutejs/sync 2.2.1 → 2.3.0

package/dist/manifest.json

@@ -0,0 +1,390 @@
+{
+	"contract": 1,
+	"identity": {
+		"accent": "#10b981",
+		"category": "sync",
+		"description": "Reactive data over your own database and ORM — no new backend. Three tiers ship in one package: push-on-change over SSE (`createReactiveHub` + the `sync` plugin), ORM-derived topics + `createLiveQuery` (Drizzle/Prisma), and the full sync engine (`/engine`): row-level live collections over WebSocket with optimistic mutations, offline queue, declarative permissions and schemas, CRDT collaborative editing, live full-text/vector search, scheduled functions, CDC for Postgres/MySQL/SQLite, incremental joins/aggregations, point-in-time replay, and cluster fan-out. CRDT backends (`sync/crdt-adapter`) and cluster buses (`sync/cluster-bus`) are pluggable.",
+		"docsUrl": "https://github.com/absolutejs/sync",
+		"name": "@absolutejs/sync",
+		"tagline": "Live data everywhere — changes appear instantly, no refresh."
+	},
+	"implements": [
+		{
+			"contract": "sync/crdt-adapter",
+			"factory": "rgaText",
+			"from": "@absolutejs/sync/crdt",
+			"title": "Built-in collaborative text (zero dependencies)",
+			"wiring": {
+				"code": "rgaText",
+				"imports": [
+					{
+						"from": "@absolutejs/sync/crdt",
+						"names": [
+							"rgaText"
+						]
+					}
+				]
+			}
+		},
+		{
+			"contract": "sync/cluster-bus",
+			"factory": "createInMemoryClusterBus",
+			"from": "@absolutejs/sync/engine",
+			"title": "In process (development only — does not span machines)",
+			"wiring": {
+				"code": "createInMemoryClusterBus()",
+				"imports": [
+					{
+						"from": "@absolutejs/sync/engine",
+						"names": [
+							"createInMemoryClusterBus"
+						]
+					}
+				]
+			}
+		}
+	],
+	"lifecycle": [
+		{
+			"docsUrl": "https://github.com/absolutejs/sync#live-collections--the-sync-engine-tier-3",
+			"id": "cdc-triggers",
+			"idempotent": true,
+			"kind": "migration",
+			"title": "Optional: install Postgres notify triggers so writes that bypass mutations still go live (postgresNotifyTrigger + postgresChangeSource)",
+			"when": "manual"
+		}
+	],
+	"requires": {
+		"peers": [
+			{
+				"name": "elysia",
+				"range": ">= 1.4.26",
+				"reason": "plugin host for the SSE, WebSocket, and devtools plugins"
+			}
+		]
+	},
+	"settings": {
+		"type": "object",
+		"properties": {
+			"devtools": {
+				"title": "Devtools dashboard",
+				"x-group": "devtools",
+				"type": "object",
+				"properties": {
+					"path": {
+						"description": "Route the live devtools dashboard is served from. Default /sync/devtools.",
+						"title": "Devtools route",
+						"type": "string"
+					},
+					"snapshotMs": {
+						"description": "How often the dashboard refreshes its counters, in milliseconds. Default 2000.",
+						"minimum": 100,
+						"title": "Dashboard refresh interval",
+						"type": "number"
+					}
+				}
+			},
+			"engine": {
+				"title": "Sync engine",
+				"x-group": "engine",
+				"type": "object",
+				"properties": {
+					"changeLogRetainMs": {
+						"description": "Also drop change-log entries older than this many milliseconds — bounds memory and reconnect catch-up work on high-throughput engines.",
+						"minimum": 1000,
+						"title": "Change history age limit",
+						"type": "number"
+					},
+					"changeLogSize": {
+						"description": "How many recent changes are kept so a briefly-disconnected visitor catches up with a small diff instead of a full reload. Default 1024.",
+						"minimum": 1,
+						"title": "Change history size",
+						"type": "integer"
+					},
+					"instanceId": {
+						"description": "Stable name for this server instance. Only needed when running several servers behind a cluster bus, so reconnecting visitors can resume across shards.",
+						"title": "Server instance name",
+						"type": "string"
+					},
+					"mutationConcurrency": {
+						"description": "How many writes may run at the same time. Extra writes wait their turn — protects the server from a flood.",
+						"minimum": 1,
+						"title": "Writes running at once",
+						"type": "integer"
+					},
+					"mutationQueueLimit": {
+						"description": "How many writes may wait in line once the limit above is full. Beyond this, writes are rejected cleanly instead of piling up.",
+						"minimum": 0,
+						"title": "Waiting writes limit",
+						"type": "integer"
+					}
+				}
+			},
+			"push": {
+				"title": "Reactive push (SSE)",
+				"x-group": "push",
+				"type": "object",
+				"properties": {
+					"heartbeatMs": {
+						"description": "Keep-alive ping interval so idle proxies don’t drop the update stream, in milliseconds. Default 25000.",
+						"minimum": 1000,
+						"title": "Keep-alive interval",
+						"type": "number"
+					},
+					"path": {
+						"description": "Route browsers connect to for instant updates. Default /sync.",
+						"title": "Update stream route",
+						"type": "string"
+					}
+				}
+			},
+			"socket": {
+				"title": "Live-collection socket",
+				"x-group": "socket",
+				"type": "object",
+				"properties": {
+					"closeOnSlow": {
+						"description": "Disconnect clients that can’t keep up with the update stream (they reconnect and reload fresh). Default off.",
+						"title": "Drop slow connections",
+						"type": "boolean"
+					},
+					"maxBufferedBytes": {
+						"description": "How many bytes may queue for one connection before it counts as slow.",
+						"minimum": 1,
+						"title": "Slow-connection threshold",
+						"type": "number"
+					},
+					"path": {
+						"description": "WebSocket route live collections connect to. Default /sync/ws.",
+						"title": "Live-collection route",
+						"type": "string"
+					}
+				}
+			}
+		}
+	},
+	"slots": {
+		"clusterBus": {
+			"configPath": "$self",
+			"contract": "sync/cluster-bus",
+			"description": "How changes fan out across your server instances when you scale horizontally",
+			"known": [
+				"@absolutejs/sync#memory-bus",
+				"@absolutejs/sync-bus-pg",
+				"@absolutejs/sync-bus-redis"
+			]
+		},
+		"crdt": {
+			"configPath": "$self",
+			"contract": "sync/crdt-adapter",
+			"description": "The engine that merges simultaneous edits in collaborative text",
+			"known": [
+				"@absolutejs/sync#rga-text",
+				"@absolutejs/sync-yjs",
+				"@absolutejs/sync-automerge",
+				"@absolutejs/sync-loro"
+			]
+		}
+	},
+	"wiring": [
+		{
+			"description": "Push-on-change over SSE: a mutation publishes the topics it touched and every subscribed view refetches instantly — no polling loops.",
+			"id": "default",
+			"server": {
+				"code": "const hub = createReactiveHub();\n\n// Mount with .use(syncPush). After a durable write, publish the topics\n// it changed and subscribed browsers refetch instantly:\n//   hub.publish('orders'); hub.publish('orders:' + order.id);\n// Browsers subscribe with createSyncSubscriber (or createLiveQuery)\n// from '@absolutejs/sync/client'.\nconst syncPush = sync({ heartbeatMs: ${settings.push.heartbeatMs}, hub, path: ${settings.push.path} });",
+				"imports": [
+					{
+						"from": "@absolutejs/sync",
+						"names": [
+							"createReactiveHub",
+							"sync"
+						]
+					}
+				],
+				"placement": "module-scope"
+			},
+			"title": "Instant updates over SSE (kill polling)"
+		},
+		{
+			"client": {
+				"client": {
+					"code": "const orders = createLiveQuery({\n\tfetcher: jsonFetcher('/api/orders'),\n\ttopics: ['orders']\n});\n\norders.subscribe((state) => {\n\t// TODO: render state.data — refetched the instant an order changes.\n});",
+					"imports": [
+						{
+							"from": "@absolutejs/sync/client",
+							"names": [
+								"createLiveQuery",
+								"jsonFetcher"
+							]
+						}
+					],
+					"placement": "client-entry"
+				}
+			},
+			"description": "The ORM adapters derive topics from queries so reads and writes line up automatically — a read of a table subscribes to it, a write publishes it.",
+			"id": "live-query",
+			"server": {
+				"code": "const hub = createReactiveHub();\n\n// Mount with .use(syncPush). Reads map to topics automatically\n// (a list read of `orders` -> topic 'orders'; a primary-key lookup\n// -> 'orders:<id>'). After a write, publish from the same filter:\n//   publishWhere(hub, orders, eq(orders.id, id), { op: 'update' });\n// (same function names on '@absolutejs/sync/prisma' for Prisma.)\nconst syncPush = sync({ heartbeatMs: ${settings.push.heartbeatMs}, hub, path: ${settings.push.path} });",
+				"imports": [
+					{
+						"from": "@absolutejs/sync",
+						"names": [
+							"createReactiveHub",
+							"sync"
+						]
+					},
+					{
+						"from": "@absolutejs/sync/drizzle",
+						"names": [
+							"deriveReadTopics",
+							"publishWhere"
+						]
+					}
+				],
+				"placement": "module-scope"
+			},
+			"title": "Auto-reactive queries from your ORM (Drizzle / Prisma)"
+		},
+		{
+			"client": {
+				"react": {
+					"code": "const { data, mutate, status } = useSyncCollection({\n\tcollection: 'orders',\n\t// TODO: your server's WebSocket URL (syncSocket path).\n\turl: 'ws://localhost:3000/sync/ws'\n});",
+					"imports": [
+						{
+							"from": "@absolutejs/sync/react",
+							"names": [
+								"useSyncCollection"
+							]
+						}
+					],
+					"placement": "client-entry"
+				}
+			},
+			"description": "Row-level live collections: the client hydrates once, then the server pushes {added, removed, changed} diffs over WebSocket, with optimistic mutations and an offline queue. Declares the module-scope `engine` binding other sync packages wire against.",
+			"id": "engine",
+			"server": {
+				"code": "// The sync engine. The module-scope `engine` binding is the documented\n// anchor @absolutejs/sync-pack-* wiring snippets reference by name.\nconst engine = createSyncEngine({\n\tchangeLogRetainMs: ${settings.engine.changeLogRetainMs},\n\tchangeLogSize: ${settings.engine.changeLogSize},\n\tinstanceId: ${settings.engine.instanceId},\n\tmutationConcurrency: ${settings.engine.mutationConcurrency},\n\tmutationQueueLimit: ${settings.engine.mutationQueueLimit}\n});\n\n// TODO: register your first live table — a collection (what clients\n// subscribe to), a writer (how rows persist), and a mutation.\n// See https://github.com/absolutejs/sync#live-collections--the-sync-engine-tier-3\n\n// Mount with .use(liveSync) (and .use(liveDevtools) in development).\nconst liveSync = syncSocket({ closeOnSlow: ${settings.socket.closeOnSlow}, engine, maxBufferedBytes: ${settings.socket.maxBufferedBytes}, path: ${settings.socket.path} });\nconst liveDevtools = syncDevtools({ engine, path: ${settings.devtools.path}, snapshotMs: ${settings.devtools.snapshotMs} });",
+				"imports": [
+					{
+						"from": "@absolutejs/sync",
+						"names": [
+							"syncDevtools",
+							"syncSocket"
+						]
+					},
+					{
+						"from": "@absolutejs/sync/engine",
+						"names": [
+							"createSyncEngine"
+						]
+					}
+				],
+				"placement": "module-scope"
+			},
+			"title": "Live collections (the sync engine)"
+		},
+		{
+			"description": "Conflict-free collaborative editing: the engine merges the declared CRDT fields on write instead of overwriting, and auto-registers the merge mutation the useCollaborativeText hooks call. Rides the engine recipe.",
+			"id": "collaborative-text",
+			"server": {
+				"code": "// Rides the 'engine' recipe: `engine` is its module-scope binding.\nconst textCrdt = ${slot.crdt};\n\n// TODO: replace 'docs'/'body' with your table and CRDT field.\nengine.registerCrdt('docs', { body: textCrdt });",
+				"imports": [],
+				"placement": "module-scope"
+			},
+			"title": "Collaborative text (CRDT merge on write)"
+		},
+		{
+			"description": "Horizontal scale: committed changes fan out across server instances over a cluster bus, so a mutation on one shard reaches subscribers on every shard. Rides the engine recipe.",
+			"id": "cluster",
+			"server": {
+				"code": "// Rides the 'engine' recipe: `engine` is its module-scope binding.\nawait engine.connectCluster(${slot.clusterBus});",
+				"imports": [],
+				"placement": "module-scope"
+			},
+			"title": "Fan out across server instances (cluster bus)"
+		}
+	],
+	"tools": {
+		"engine_metrics": {
+			"annotations": {
+				"readOnlyHint": true
+			},
+			"description": "Operator-shaped engine health: uptime, subscription/mutation/change counters, memory estimates, and throughput since start.",
+			"input": {
+				"type": "object",
+				"properties": {}
+			},
+			"kind": "runtime"
+		},
+		"engine_overview": {
+			"annotations": {
+				"readOnlyHint": true
+			},
+			"description": "What this sync engine serves: registered collections with live subscription counts, mutations, schedules, readers/writers, installed packs, and the most recent changes.",
+			"input": {
+				"type": "object",
+				"properties": {}
+			},
+			"kind": "runtime"
+		},
+		"publish_topic": {
+			"description": "Publish a reactive topic on the hub so every subscribed view refetches now. Useful after out-of-band data changes. Reports how many subscribers were listening.",
+			"input": {
+				"type": "object",
+				"required": [
+					"topic"
+				],
+				"properties": {
+					"topic": {
+						"minLength": 1,
+						"type": "string"
+					}
+				}
+			},
+			"kind": "runtime"
+		},
+		"replay_at": {
+			"annotations": {
+				"readOnlyHint": true
+			},
+			"description": "Point-in-time replay: reconstruct table state as of a past timestamp from the change log. Returns per-table row counts plus asOfVersion/asOfAt; truncated=true means the log doesn’t reach back that far (widen changeLogRetainMs for forensics).",
+			"input": {
+				"type": "object",
+				"required": [
+					"atMs"
+				],
+				"properties": {
+					"atMs": {
+						"description": "Target timestamp, Unix epoch milliseconds.",
+						"minimum": 0,
+						"type": "integer"
+					},
+					"tables": {
+						"type": "array",
+						"items": {
+							"minLength": 1,
+							"type": "string"
+						}
+					}
+				}
+			},
+			"kind": "runtime"
+		},
+		"run_schedule": {
+			"description": "Fire one registered scheduled function now instead of waiting for its cron pattern. Whatever it writes goes live through the change feed.",
+			"input": {
+				"type": "object",
+				"required": [
+					"name"
+				],
+				"properties": {
+					"name": {
+						"minLength": 1,
+						"type": "string"
+					}
+				}
+			},
+			"kind": "runtime"
+		}
+	}
+}

package/package.json

@@ -1,11 +1,15 @@
 {
 	"name": "@absolutejs/sync",
-	"version": "2.2.1",
+	"version": "2.3.0",
 	"description": "Lightweight reactive-push and write-behind-cache primitives for Elysia and the AbsoluteJS ecosystem — kill polling and keep a remote store off your hot path, without adopting a whole sync-engine backend.",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/absolutejs/sync.git"
 	},
+	"homepage": "https://github.com/absolutejs/sync",
+	"bugs": {
+		"url": "https://github.com/absolutejs/sync/issues"
+	},
 	"type": "module",
 	"main": "./dist/index.js",
 	"module": "./dist/index.js",
@@ -107,7 +111,16 @@
 			"types": "./dist/angular/index.d.ts",
 			"import": "./dist/angular/index.js",
 			"default": "./dist/angular/index.js"
-		}
+		},
+		"./manifest": {
+			"types": "./dist/manifest.d.ts",
+			"import": "./dist/manifest.js",
+			"default": "./dist/manifest.js"
+		},
+		"./manifest.json": "./dist/manifest.json"
+	},
+	"absolutejs": {
+		"manifestContract": 1
 	},
 	"files": [
 		"dist",
@@ -189,7 +202,9 @@
 		}
 	},
 	"dependencies": {
-		"@absolutejs/telemetry": "^0.0.2"
+		"@absolutejs/manifest": "^0.1.0",
+		"@absolutejs/telemetry": "^0.0.2",
+		"@sinclair/typebox": "^0.34.0"
 	},
 	"devDependencies": {
 		"@absolutejs/absolute": "^0.19.0-beta.1051",