mirror of https://github.com/logseq/logseq.git synced 2026-05-14 07:52:20 +00:00

Files

megayu 79c25837cb Migrate from yarn to pnpm (#12529 )

* migrate yarn to pnpm

* chore: update pnpm version to 10.33.0 across all package.json files

* chore: update .npmrc and package.json for improved dependency management

* chore: unify Clojure, Node, and Java version in workflow files

* fix: enable shamefully-hoist for now and add electron, keytar to onlyBuiltDependencies

* feat: add cider/piggieback dependency and update nREPL middleware configuration to silence warnings

* ensure pnpm setup prior to node setup

* fix: update logseq/bb-tasks git SHA

* feat: add pnpm configuration for onlyBuiltDependencies in package.json

* feat: add onlyBuiltDependencies configuration for better-sqlite3 in pnpm settings

* chore: update pnpm lockfile

* fix: resolve merge conflicts

* fix: remove invisible characters from markdown headers

* fix: update .npmrc comments for clarity on lockfile usage

* Revert "feat: add cider/piggieback dependency and update nREPL middleware configuration to silence warnings"

This reverts commit 70a111936f.

* fix: remove invisible characters from various README files and add .editorconfig

* fix: clarify lockfile resolution process in SKILL.md

---------

Co-authored-by: Tienson Qin <tiensonqin@gmail.com>

2026-04-24 23:40:25 +08:00

3.4 KiB

Raw Permalink Blame History

DB-Sync Feature Agent Guide

Purpose

This guide helps AI agents implement and review db-sync features consistently across the client and the Cloudflare Worker. Keep changes scoped, follow the existing flow, and document any protocol or storage changes. Keep this document accurate (file names, paths, commands, and parameters).

Key Code Locations

Client config: src/main/frontend/config.cljs
Client runtime: src/main/frontend/worker/db_sync.cljs
Worker thread API: src/main/frontend/worker/db_worker.cljs
Handler entry points: src/main/frontend/handler/db_based/db_sync.cljs
Server worker code: deps/db-sync/src/logseq/db_sync/

Implementation Workflow

Define behavior: state the new capability, expected inputs/outputs, and compatibility requirements.
Update protocol first (if needed): change protocol.cljs and adjust server/client serialization in tandem.
Server changes: update worker.cljs, worker_core.cljs, storage.cljs, or cycle.cljs.
Client changes: update db_sync.cljs and thread APIs in db_worker.cljs.
Handler glue: add or adjust the entry points in handler/db_based/db_sync.cljs.
Function ordering: keep related ClojureScript fns together and ordered to minimize declare usage.

Data, Keywords, and Schema

Use existing :db-sync/* keywords; add new keywords via logseq.common.defkeywords/defkeyword.
When adding persisted fields, ensure any migration or index logic is updated on both client and worker.

Fail-Fast Error Policy

db-sync core code must fail fast on bugs: log an error (log/error) and throw immediately.
Treat these as bugs (internal invariants or bad server responses on the client):
- db connection missing when required (client or worker).
- WS/HTTP response fields missing (e.g., :t, :txs, :reason, :data).
- Response parse/coercion failures (e.g., transit decode, malli coercion).
- Unexpected WS/HTTP message type or reason value on the client.
- Asset operations missing required fields when processing client-side metadata.
- Invariant violations in tx apply (e.g., tx-data empty after normalization).
Server-side validation of client input should not throw. Respond with tx/reject or 400 errors for:
- tx payload type mismatch (e.g., :txs not a sequence of strings).
- Invalid graph identity (missing/empty graph id or uuid in sync path).
- Invalid or negative t/t-before values.
Do not silently recover or drop messages for bug cases; surface them via exceptions.

HTTP API (Bootstrap + Assets)

HTTP endpoints backfill initial graph data, snapshots, and assets.
See docs/agent-guide/db-sync/protocol.md for request/response shapes.

Client-Server Message Protocol (WebSocket)

See docs/agent-guide/db-sync/protocol.md for request/response shapes.

Testing & Verification

Local dev(client+server): bb dev:db-sync-start runs the db-sync watcher, wrangler dev, and pnpm watch with ENABLE_DB_SYNC_LOCAL=true
DB-sync server side unit-tests: bb dev:db-sync-test
Node adapter tests: cd deps/db-sync && pnpm test:node-adapter
Node adapter build/run: cd deps/db-sync && pnpm build:node-adapter && pnpm start:node-adapter

Review Checklist

Protocol versioning and error handling are consistent across client/server.
No breaking changes without fallback or migration.
New data fields are indexed or stored intentionally.
Logs and errors use :db-sync/* context keys.

3.4 KiB Raw Permalink Blame History