flowstate-rxdb-node-client Package Skill

Package: @epicdm/flowstate-rxdb-node-client Repository: epic-flowstate-community Path: packages/flowstate-rxdb-node-client Version: 1.0.8

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

Node Client Contracts And Troubleshooting

Use this skill when replication appears connected but a service is missing data, missing events, failing auth, or hanging during shutdown.

Auth And Header Contract

Current public NodeClientConfig includes token, but NodeClient.startCollectionReplication does not pass that token to replicateCloudflareD1.

Current internal config supports customHeaders, and those headers are forwarded, but createNodeClient does not expose customHeaders publicly.

If D1 auth is failing:

1. Inspect whether the consumer uses manual new NodeClient(db, { customHeaders }).
2. Check D1 Worker auth expectations.
3. Do not assume token is effective until source changes forward it.

Collection Coverage

createLocalDatabase skips unknown collection names and only throws when no valid collections remain. If a service is missing events for one collection:

1. Check the collection name against @epicdm/flowstate-collections.
2. Confirm the local database actually has the collection in database.collections.
3. Confirm the D1 Worker supports that collection route.

Status And Partial Starts

start sets status to connecting, loops through local collections, starts replication, marks running = true, then emits connected.

If a later collection throws during startup, earlier replication states may already exist. A repair should cancel any started states on failure before rethrowing.

Event Handling

RxDB change subscriptions call void this.dispatchEvent(event). This means:

• async event handlers are not backpressured by RxDB subscriptions.
• stop does not wait for in-flight handlers.
• handler failures are logged and swallowed.

For critical workflows, make handlers idempotent and store durable progress outside the event callback.

Generated Content Drift

The feature matrix may list replicateCloudflareD1 and RxCloudflareD1ReplicationState near this package. Those belong to @epicdm/flowstate-rxdb-d1/client; this package only consumes that API.

Package Skill Inventory

Package Skill Inventory: @epicdm/flowstate-rxdb-node-client

Package path: packages/flowstate-rxdb-node-client.

Skill Map

Anti-Sprawl Decision

Do not create one skill per exported type or ambient declaration. This package has one real job: provide Node services with in-memory RxDB plus live D1 replication and document-change events. The useful skills are workflows around manual replication, managed replication, local database provisioning, contracts, and maintenance.

Deferred Skills

• Dedicated replicateCloudflareD1 skill: belongs to @epicdm/flowstate-rxdb-d1, not this package.
• Dedicated event-operation skills for INSERT, UPDATE, and DELETE: fold into event replication because handlers usually need all three together.

Review Gate

Package Skill Review: @epicdm/flowstate-rxdb-node-client

Package path: packages/flowstate-rxdb-node-client.

Review Result

Status: drafted, source-backed, verified, pending publication.

The skillset is workflow-shaped rather than symbol-shaped. It covers the package purpose, manual and managed replication paths, local database provisioning, high-risk contracts, and verification.

Checks

• Source review: completed from package source, tests, package exports, and feature-matrix drift.
• Skill inventory: completed.
• Skill files: completed.
• ASCII/frontmatter scan: passed.
• Package tests: passed, 3 suites and 25 tests.
• Package typecheck: passed.
• Package lint: passed with 32 existing warnings.
• Package build: passed through Nx.
• Generated Dojo replacement: pending.
• Cloud Dojo publication: pending.

Verification Commands

Run before publication:

yarn workspace @epicdm/flowstate-rxdb-node-client test --runInBand
yarn workspace @epicdm/flowstate-rxdb-node-client typecheck
yarn workspace @epicdm/flowstate-rxdb-node-client lint
yarn nx build @epicdm/flowstate-rxdb-node-client

Optional downstream checks:

yarn workspace @epicdm/flowstate-rag-sync test --runInBand
yarn workspace @epicdm/flowstate-workers test --runInBand

Publication Gate

Do not publish the existing generated .flowstate/dojo package as-is. Publish only after Dojo content is regenerated or rewritten from these reviewed skills.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/flowstate-rxdb-node-client/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.