tally-protocol
v0.1.1
Published
Tally Query Protocol: wire schemas, request validation, JSON Schema and the adapter conformance suite.
Readme
tally-protocol
The wire contract between a Tally grid and a data source: Zod schemas for every request and response, validation of a request against a Schema, generated JSON Schema files, and the conformance suite an adapter runs to prove it answers queries exactly like the in-memory engine.
Not published yet.
Install
npm install tally-protocol tally-coreWire types
| Schema | Type | Direction |
| ----------------------- | ----------------------------------------- | ---------------------- |
| queryRequestSchema | QueryRequest from core | POST /query body |
| queryResponseSchema | QueryResponse from core | POST /query response |
| mutationRequestSchema | { version: 1, mutations } | PATCH /rows body |
| mutationResultSchema | MutationResult from core | PATCH /rows response |
| rowPatchSchema | RowPatch from core | live events |
| schemaResponseSchema | { version, columns, capabilities, key } | GET /schema response |
Every schema is a z.ZodType of the matching tally-core type, so the client and the server share one definition.
Validating a request
import { createSchema } from 'tally-core'
import { validateQueryRequest } from 'tally-protocol'
const schema = createSchema({ columns, key: 'id' })
const request = validateQueryRequest(await req.json(), schema)validateQueryRequest parses the shape, then checks it against the schema: columns exist and allow the operation, operators are supported by the column type, values match the operator arity and the value kind, aggregates and facets are available for the column. It throws a TallyError with code invalid_query and one detail per problem. queryIssues returns the same list without throwing. validateMutationRequest and mutationIssues do the same for mutations.
JSON Schema
schemas/*.json are generated from the Zod schemas and shipped with the package for adapters written in other languages:
import queryRequest from 'tally-protocol/schemas/query-request.json' with { type: 'json' }toJsonSchema(name) returns the same document at runtime.
Conformance
An adapter is conformant when it returns the same rows, totals, groups, aggregates and facets as tally-core's executor for the fixture dataset.
import { runConformance } from 'tally-protocol'
const report = await runConformance((request) => adapter.query(request), {
capabilities: adapter.capabilities,
})
expect(report.failures).toEqual([])conformanceRows and conformanceSchema cover every built-in column type with empty values in each column. Relative date filters resolve against CONFORMANCE_TODAY, so the adapter under test must be created with that date as its today. Cases that need a capability the adapter does not declare are skipped. Offset adapters also run the page cases, cursor adapters are walked page by page until the cursor runs out. Every failure lists what differed, by path.
