Repository navigation
syncables 0.18.0: browser-safe read path as syncables/browser - #83
Merged
Merged
Conversation
Browser and iframe plugins (pets, Notion) need syncables' read path, but the package entry imports node:http, node:fs and node:crypto, so it can't be bundled for a browser. The new syncables/browser entry exports the read path alone, with an injected Transport. - src/read/: crudResources collection discovery, query selections, a page walker with request and record budgets and 429 Retry-After handling, ontology derivation with Atomic Data datatypes, readPlatform and paginate. Re-derived from the browser port in closed PR #76 (integrations/localthought/reflector-read.ts). The page walker reuses syncables' own pagination modules. - Request-body pagination: buildBody puts cursor, page-size, offset and page fields from request.bodyFields into a POST's JSON body, and nextCursor now reads body-field offset and page roles. Collections opt in to POST listing with x-list-method: POST and add fixed body fields with x-list-body. This covers Notion's /v1/search and /v1/databases/{id}/query. - applyOverlay moves to openapi/apply-overlay.ts, which has no file-system access. openapi/overlay.ts re-exports it and keeps loadOverlay, so the Node API is unchanged. The main entry also exports the read path, with paginate renamed paginateOperation. - Tests: an esbuild platform: 'browser' bundle of src/browser.ts that fails on any Node built-in import, with a control test showing that the Node entry is caught. Also read-path unit tests with a stub transport: the PR #76 pets, calendar and workspace scenarios, and a Notion-shaped POST-body scenario built from overlays. The session log is docs/ai-logs/sessions/2026-09-23-browser-entry.md. The session URL was not available to the agent, so this commit has no Claude-Session trailer. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Merging this publishes
syncables@0.18.0to npm. This PR bumpssyncables/package.jsonfrom 0.17.1 to 0.18.0. When that change reachesmain,.github/workflows/syncables-publish.ymlrunsnpm publishthrough npm Trusted Publishing. The publish only succeeds once the npm Trusted Publisher forsyncablespoints atontola/atomic-pluginsandsyncables-publish.yml.Why
Browser and iframe plugins, starting with pets and Notion, need syncables' read path. The only entry today is
syncables, and it importsnode:http,node:fsandnode:crypto, so it can't be bundled for a browser. The closed PR #76 got around this with a 1,100-line port,integrations/localthought/reflector-read.ts. This PR moves that read path into syncables itself.What
syncables/browser(src/browser.ts,"exports": { "./browser": … }). It contains the read path only and never callsfetch. Every request goes through an injectedTransport, a function from{ url, method, headers, body? }to{ status, headers, body }.fetchTransport(fetch)adapts anything fetch-shaped. The entry exports:prepareDocument(document, overlays): applies overlays, then resolves$refs.describePlatform(document): returns{ parameters, collections, upstream }, read fromcomponents.crudResources.readPlatform(document, { platform, constants, transport, selection?, limits?, probe? }): returns{ platform, ontology, records, errors }. This is the same shape asFetchedPlatforminintegrations/localthought.paginate(document, { transport, path, method, … }): walks one operation's pages and doesn't needcrudResources.deriveOntology,ontologyShortname,mergeQuerySelections,DATATYPES,DEFAULT_READ_LIMITS, and the existing pagination and overlay helpers.buildBodybuilds a POST's JSON body fromrequest.bodyFields: cursor, page size, offset and page.nextCursornow reads body-fieldoffsetandpageroles. On acrudResourcescollection,x-list-method: POSTlists with a POST instead of a GET, andx-list-bodyadds fixed body fields. This covers Notion's/v1/searchand/v1/databases/{id}/query, which sendstart_cursorin the request and returnnext_cursor. Auto-detection already matched body fields, so an operation that declaresstart_cursorandpage_sizein its request body picks up this scheme withoutx-pagination.applyOverlaymoves toopenapi/apply-overlay.ts, which has no file-system access.openapi/overlay.tsre-exports it and keepsloadOverlay. The mock server and loaders are unchanged.syncablesalso exports the read path, withpaginaterenamedpaginateOperationso it doesn't clash with thePaginateOptionstype thatApiClient.paginateuses.Limits and what isn't covered
Retry-After. When any of these limits is reached, the read stops, keeps what it has read so far, and reports the stop inerrors.nextLinkto another origin, or with credentials or a fragment, stops that collection with an error. So does a page that repeats, which is what happens when a proxy drops the cursor.js-yaml, so pass documents and overlays as parsed JSON.x-crudreads and cross-collection links. Header-based auto-detection (matchHeaders) is still not implemented. Neither of these was in the Node API before.Read incomplete: …replacesImport incomplete; no changes proposed: ….Tests
__tests__/unit/browser/bundle.test.tsbundlessrc/browser.tswith esbuildplatform: 'browser'. It fails if anything imports a Node built-in, pulls in anode_modulesfile, or usesprocess.,Buffer.orrequire(. A control test bundles the Node entry and checks that it is flagged, so the check isn't vacuous.__tests__/unit/read/read.test.ts(18 tests, all with a stub transport) covers:paginateover GET and POST;fetchTransport.request-builder.test.tsaddsbuildBodycases.Verification
All run locally on Node 22.23.2:
syncables-ci.yml:npm ci,npm run lint,npm run prettier:check,npm test(127 tests pass) andnpm run build.npm pack --dry-runshowssyncables@0.18.0with 53 files, includingbuild/src/browser.{js,d.ts}andbuild/src/read/*.syncables/browser:tscresolved its types withmoduleResolution: bundler.platform: 'browser'bundled it, and the bundle contains nonode:imports.platform: 'browser'and--minifygives 19.2 kB.package-lock.jsonandpnpm-lock.yamleach gain only anesbuild ~0.21.5devDependency. That is the version vitest already installs.🤖 Generated with Claude Code