Quario

https://getquario.com
Admin
Quario is a declarative reporting engine for JavaScript that compiles JSON report definitions into...
Tokens:97,603
Snippets:807
Trust Score:2.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install quario with npm

Source: https://getquario.com/docs

Install the quario package via npm. The command is shown on the landing page as the quick start for evaluating the library.

```bash
$npm install quario
```

--------------------------------

### Install @quario/csv

Source: https://getquario.com/docs/diving-deeper/csv-target

Install the @quario/csv package. The csv() factory takes no options and refuses one rather than discarding it.

```bash
npm install @quario/csv
```

--------------------------------

### Install @quario/xlsx

Source: https://getquario.com/docs/diving-deeper/xlsx-target

Install the @quario/xlsx package to render reports to XLSX files.

```bash
npm install @quario/xlsx
```

--------------------------------

### Install quario engine and render targets

Source: https://getquario.com/docs/getting-started

Install the quario engine and the HTML and PDF render targets. The targets declare the engine as a peer dependency, so you can add another target later without touching existing definitions.

```bash
npm install quario @quario/html @quario/pdf
```

--------------------------------

### Report document with $schema pointing to quario/schema.json

Source: https://getquario.com/docs/diving-deeper/validating

Example report document that references the installed JSON Schema file. The engine only checks the top-level $schema string; anywhere else it is an unknown key.

```json
{
  "$schema": "./node_modules/quario/lib/schema.json",
  "data": "$.invoice.lines[*]",
  "detail": { "columns": [{ "header": "Item", "value": "{{ @.item }}" }] }
}

```

--------------------------------

### Activate quario with a license key

Source: https://getquario.com/docs/diving-deeper/licensing

Used to activate quario by providing a license key. The `q.license` promise settles with `{ licensed, licensee?, id? }` and never rejects; without a key it settles with `{ licensed: false }`. Verification starts once, and every report compiled by the instance shares the result.

```ts
import { quario } from 'quario'

const q = quario({ license: 'quario_...' })

const { licensed, licensee, id } = await q.license
```

--------------------------------

### Agent tool-call loop with validate_report and render_report

Source: https://getquario.com/docs

Example of the agent tool-call loop: validate_report returns problems, then a revised definition passes validation, and render_report produces a PDF. The output shows the exact error messages and the final file path.

```text
→ validate_report  { definition }
← 2 problems
    sort[0].dir: unknown sort direction "descending"
    detail.columns[1].value [{{ round(@.qty * @.unitPrice }}]: Unexpected end of expression
→ validate_report  { definition }  revised
← {"problems":[],"warnings":[]}
→ render_report  { definition, target: "pdf", dataPath: "invoices/1042.json", filename: "invoice-1042" }
← Wrote invoice-1042.pdf (1.8 kB): /srv/reports/invoice-1042.pdf
```

--------------------------------

### Create a quario instance with locale and currency

Source: https://getquario.com/docs/getting-started

Create a quario instance that holds host configuration such as locale, currency, and timezone. The instance verifies the license key once, offline, and should be built at startup and kept for the service's lifetime.

```ts
import { quario } from 'quario'

const q = quario({ locale: 'en-IE', currency: 'EUR', timeZone: 'UTC' })
```

--------------------------------

### JSON-LD BreadcrumbList schema

Source: https://getquario.com/docs/getting-started

A JSON-LD structured data snippet for a breadcrumb list, used for SEO. It defines a BreadcrumbList with three items: Home, Docs, and Getting started.

```json
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://getquario.com/"},{"@type":"ListItem","position":2,"name":"Docs","item":"https://getquario.com/docs"},{"@type":"ListItem","position":3,"name":"Getting started","item":"https://getquario.com/docs/getting-started"}]}
```

--------------------------------

### quario(options?)

Source: https://getquario.com/docs/reference/quario

Creates a configured quario instance with host-level options.

```APIDOC
## quario(options?)

### Description
Creates a configured instance of the quario engine. Host-level configuration only.

### Method
function

### Endpoint
quario(options?)

### Parameters
#### Options
- **license** (string) - Optional - License key, verified offline once at creation. The engine marks output when the key ends before this version's release date.
- **locale** (string) - Optional - Locale for `format`. Defaults to `"en-US"`.
- **currency** (string) - Optional - Default ISO 4217 code for `format: "currency"`.
- **timeZone** (string) - Optional - Timezone for `format: "date"`. Defaults to `"UTC"`.
- **query** (QueryOptions) - Optional - Budgets for the JSONPath selection.
- **schemes** (readonly string[]) - Optional - The URL schemes an `href` may use, lower-case and colon-terminated. Defaults to `https:` and `mailto:`. A value the engine can't read throws at construction.

### Returns
- **Quario** - A configured instance.

### Example
```ts
const engine = quario({
  license: 'your-license-key',
  locale: 'en-US',
  currency: 'USD',
  timeZone: 'UTC',
  schemes: ['https:', 'mailto:']
});
```
```

--------------------------------

### q.plan(schema, funcs?)

Source: https://getquario.com/docs/diving-deeper/validating

Compiles a report definition and returns a detailed plan object with report, problems, anchors, warnings, and params. Use this to check a definition before rendering and to inspect anchors and warnings.

```APIDOC
## q.plan(schema, funcs?)

### Description
Compiles a report definition and returns a detailed plan object. Use this to check a definition before rendering and to inspect anchors and warnings.

### Method
Function

### Endpoint
q.plan(schema, funcs?)

### Parameters
#### Parameters
- **schema** (object) - Required - The report definition to compile.
- **funcs** (object) - Optional - Additional functions or configuration.

### Returns
- **report** (object|null) - The compiled report, or null if the document has problems.
- **problems** (array) - List of problems found during compilation.
- **anchors** (object) - Maps each compiled source's schema path to the anchors and handles it reads.
- **warnings** (array) - List of warnings, each with `path` and `message`.
- **params** (array) - List of parameters the document declares.

### Example
```ts
const { report, problems, anchors, warnings, params } = q.plan(definition)
```
```

--------------------------------

### Inline reducer example

Source: https://getquario.com/docs/reference/functions-and-reducers

Shows an inline reducer that folds an array on the row itself, using the sum reducer with a lambda expression.

```json
{ "value": "{{ sum(@.lines, l => l.total) }}" }
```

--------------------------------

### Typed and untyped columns side by side

Source: https://getquario.com/docs/diving-deeper/xlsx-target

Example configuration showing a typed column with a currency format and an untyped column that renders as text.

```json
{
  "columns": [
    { "header": { "value": "Amount" }, "value": "{{ @.amount }}",
      "style": { "format": "currency" } },
    { "header": { "value": "Label" }, "value": "Total: {{ @.amount }}" }
  ]
}
```

--------------------------------

### pdf(options?)

Source: https://getquario.com/docs/reference/pdf

Creates a PDF render target. Validates options at the factory call and returns a target that resolves to a Uint8Array containing the PDF bytes.

```APIDOC
## pdf(options?)

### Description
Returns the PDF render target. It validates options at the factory call, and takes three: `page`, `meta` and `fonts`. Any other key, or one of the wrong type, throws a `TypeError` naming the path. The factory copies `meta` as it reads it, so mutating that object afterwards changes nothing the target writes.

### Signature
```ts
function pdf(options?: PdfOptions): Target<'pdf', Promise<Uint8Array>>
```

### Parameters
- **options** (PdfOptions) - Optional - Configuration object with `page`, `meta`, and `fonts` fields.

### Returns
- **Target<'pdf', Promise<Uint8Array>>** - The PDF render target that resolves to the document bytes.

### Errors
- **TypeError** - Thrown if options contain an invalid key or a field of the wrong type.
```

--------------------------------

### QuarioDiagnostic interface

Source: https://getquario.com/docs/reference/quario

An error interface representing a diagnostic raised by a delegated engine, with optional code, start, end, limit, actual, and blocks.

```APIDOC
## QuarioDiagnostic interface

### Description
An error interface representing a diagnostic raised by a delegated engine, with optional code, start, end, limit, actual, and blocks.

### Signature
```ts
interface QuarioDiagnostic extends Error {
  readonly code?: QuarioErrorCode
  readonly start?: number
  readonly end?: number
  readonly limit?: number
  readonly actual?: number
  readonly blocks?: readonly SjabloonBlock[]
}
```

### Properties
- **code** (QuarioErrorCode) - Optional - The error code, absent on option and target-definition faults.
- **start** (number) - Optional - The start position.
- **end** (number) - Optional - The end position.
- **limit** (number) - Optional - The limit on a budget failure.
- **actual** (number) - Optional - The actual value on a budget failure.
- **blocks** (readonly SjabloonBlock[]) - Optional - The blocks involved.
```

--------------------------------

### Render a PDF with page size and margin

Source: https://getquario.com/docs/diving-deeper/pdf-target

Sets up a PDF page with A4 size and a 54-point margin, then renders the report to bytes. The page geometry is validated at the factory call, so a bad option throws before the engine walks any data.

```ts
import { pdf } from '@quario/pdf'

const bytes = await report.render(pdf({ page: { size: 'A4', margin: 54 } }), data)
```

--------------------------------

### quario.license

Source: https://getquario.com/docs/diving-deeper/licensing

Activates the license and returns the license status. Settles with { licensed, licensee?, id? } and never rejects. Without a key it settles { licensed: false }.

```APIDOC
## quario.license

### Description
Activates the license and returns the license status. Settles with { licensed, licensee?, id? } and never rejects. Without a key it settles { licensed: false }.

### Method
Property access (async)

### Endpoint
q.license

### Parameters
None

### Request Example
```ts
import { quario } from 'quario'

const q = quario({ license: 'quario_...' })

const { licensed, licensee, id } = await q.license
```

### Response
#### Success Response (200)
- **licensed** (boolean) - Whether the license is valid.
- **licensee** (string, optional) - The licensee name, if licensed.
- **id** (string, optional) - The license ID, if licensed.

#### Response Example
```json
{
  "licensed": true,
  "licensee": "Acme Corp",
  "id": "quario_..."
}
```
```

--------------------------------

### xlsx(options)

Source: https://getquario.com/docs/diving-deeper/xlsx-target

Renders a compiled report to an XLSX workbook, returning a Uint8Array. Accepts options for metadata, print setup, and autofilter. Throws TypeError for unknown or incorrectly typed options.

```APIDOC
## xlsx(options)

### Description
Renders a compiled report to an XLSX workbook, returning a Uint8Array. Accepts options for metadata, print setup, and autofilter. Throws TypeError for unknown or incorrectly typed options.

### Method
Function

### Endpoint
xlsx(options)

### Parameters
#### Options
- **meta** (object) - Required - Metadata for the workbook. Contains `title`, `author`, `subject` (all strings, never a date).
- **page** (object) - Optional - Print setup options.
- **filter** (object) - Optional - Autofilter configuration.

### Request Example
```javascript
import { xlsx } from '@quario/xlsx';
const result = xlsx({
  meta: { title: 'Report', author: 'Author', subject: 'Subject' },
  page: { /* print setup */ },
  filter: { /* autofilter */ }
});
```

### Response
#### Success Response
- **Uint8Array** - The XLSX workbook bytes.

#### Response Example
```javascript
// result is a Uint8Array
```

### Error Handling
- Throws `TypeError` if an option is unknown or of the wrong type, naming the path it came from.
```

--------------------------------

### Pinned header configuration

Source: https://getquario.com/docs/diving-deeper/bands

Defines a report header band with a fixed height and a text item that uses a template expression. Requires page.margin on the document because the pin starts at the physical page edge.

```json
{
  "header": {
    "height": 120,
    "items": [
      { "type": "text", "value": "{{ $.input.company }}", "style": { "size": 14, "bold": true } }
    ]
  }
}
```

--------------------------------

### q.report(schema, funcs?)

Source: https://getquario.com/docs/diving-deeper/validating

Compiles a report definition and throws on the first problem encountered. Use this when you want to fail fast on invalid definitions.

```APIDOC
## q.report(schema, funcs?)

### Description
Compiles a report definition and throws on the first problem encountered. Use this when you want to fail fast on invalid definitions.

### Method
Function

### Endpoint
q.report(schema, funcs?)

### Parameters
#### Parameters
- **schema** (object) - Required - The report definition to compile.
- **funcs** (object) - Optional - Additional functions or configuration.

### Throws
Throws an error on the first problem found during compilation.

### Example
```ts
q.report(definition)
```
```

--------------------------------

### Compile and render a report with q.report

Source: https://getquario.com/docs/getting-started

Compile the report definition once and render it per dataset. The report object is held by the service and reused for each render, avoiding repeated parsing costs.

```ts
import { html } from '@quario/html'

const report = q.report(definition)

const invoice = await getInvoice()
const fragment = await report.render(html(), { invoice })
```

--------------------------------

### Await q.license before streaming a report

Source: https://getquario.com/docs/diving-deeper/licensing

Shows how to explicitly await the license promise before draining `report.stream(data)` directly. This prevents a race where the stream could outrun the license check; `render` already awaits settlement, but direct stream consumers must await `q.license` first.

```ts
await q.license

for (const event of report.stream(data)) {
  if (event.type === 'report-start' && event.marking) console.log(event.marking)
}
```

--------------------------------

### Fetch row data with an async registered function

Source: https://getquario.com/docs/diving-deeper/host-functions

Fetches data the report's own data doesn't carry by registering an `async` function and calling it as the whole value of a detail cell. The engine calls the function once per rendered row, starts all calls together, and waits for all before the first event reaches a target. The call must be the whole cell value and its arguments must come from the row; `render()` settles the calls, while `stream()` cannot.

```json
{ “type”: “text”, “value”: ”{{ customerName(@.customerId) }}” }
```

```ts
const funcs = {
  customerName: async (id: string) => (await getCustomer(id)).name,
}

const report = q.report(definition, funcs)
const output = await report.render(target, data)
```

--------------------------------

### q.report(definition, funcs)

Source: https://getquario.com/docs/diving-deeper/formatting

Creates a report with a definition and registered functions.

```APIDOC
## `q.report(definition, funcs)`

### Description
Creates a report using a definition and a set of registered functions. Registered functions are configuration you trust, the same standing as the definition itself. A function of the same name as a built-in shadows it.

### Parameters
- **definition** (object) - Required - The report definition.
- **funcs** (object) - Required - An object mapping function names to implementations.

### Example
```ts
const funcs = {
  period: (ym: string) => {
    const [year, month] = ym.split('-').map(Number)
    return new Intl.DateTimeFormat('en-GB', { month: 'long', year: 'numeric' })
      .format(new Date(year, month - 1, 1))
  },
}
const report = q.report(definition, funcs)
```
```

--------------------------------

### Import the HTML target stylesheet

Source: https://getquario.com/docs/diving-deeper/html-target

Imports the reference stylesheet for the HTML target. Two rules in this sheet affect fragment behavior: .q-item has min-height: 1lh and white-space: pre-line, and table cells carry pre-line but no min-height. The classes are yours to restyle, overriding on source order like any vendor sheet.

```css
@import '@quario/html/style.css';
```

--------------------------------

### paint(ctx, page, options?)

Source: https://getquario.com/docs/reference/layout

Draws one page to a canvas, filling white over the whole canvas first. The canvas must be sized to the paper before calling, as page ops are in page coordinates.

```APIDOC
## paint(ctx, page, options?)

### Description
Draws one page to a canvas, filling white over the whole canvas first. The canvas must be sized to the paper before calling, as page ops are in page coordinates.

### Method
paint

### Signature
```ts
function paint(
  ctx: CanvasRenderingContext2D,
  page: Page,
  options?: { scale?: number; fonts?: LayoutFonts },
): Promise<void>
```

### Parameters
- **ctx** (CanvasRenderingContext2D) - Required - The canvas rendering context to draw on.
- **page** (Page) - Required - The page to draw.
- **options** (object) - Optional - Options for painting.
  - **scale** (number) - Optional - Scale factor for drawing.
  - **fonts** (LayoutFonts) - Optional - Fonts to use for text rendering.

### Example
```ts
import { layout, paint } from '@quario/layout'

const list = await report.render(layout({ page: { size: 'A4' } }), data)

canvas.width = list.width * 2        // the paper's, never a page's
canvas.height = list.height * 2
await paint(ctx, list.pages[0], { scale: 2 })
```

### Returns
Promise<void> - Resolves when painting is complete.
```

--------------------------------

### Admit URL schemes with quario({ schemes })

Source: https://getquario.com/docs/diving-deeper/security

Configures the URL scheme allowlist for a render. Defaults to https: and mailto:; each entry is lower-case and ends in a colon. Refused URLs drop out (text renders, link doesn't), and an unreadable schemes value throws at construction rather than falling back to the default.

```ts
import { quario } from 'quario'

const q = quario({ locale: 'en-IE', schemes: ['https:'] })
```

--------------------------------

### Configure quario MCP server in Claude Desktop

Source: https://getquario.com/docs/diving-deeper/mcp

Add this configuration to your claude_desktop_config.json file to enable the quario MCP server in Claude Desktop.

```json
{
  "mcpServers": {
    "quario": {
      "command": "npx",
      "args": ["-y", "@quario/mcp"],
      "env": { "QUARIO_LICENSE": "quario_..." }
    }
  }
}
```

--------------------------------

### html(options?)

Source: https://getquario.com/docs/reference/html

The html() factory function that creates the HTML render target.

```APIDOC
## `html(options?)`

### Description
Returns the HTML render target. `report.render(html(), data)` resolves the fragment.

### Method
Function call

### Endpoint
`html(options?)`

### Parameters
#### Options
- **fonts** (Record<string, string>) - Optional - A declared `family` name mapped to a CSS `font-family` value. Names match case-insensitively, and a mapping may cover the generics `sans` / `serif` / `mono` like any other.
- **paths** (boolean) - Optional - Emit `data-q-path` on each element whose event carries a schema `path`. Off by default.

### Return Value
`Target<'html', Promise<string>>`

### Errors
- Throws a `TypeError` if any option key is not `fonts` or `paths`, or if a value is of the wrong type.
- Throws from `html()` if a `fonts` value contains `;` or `}`.
- Throws if `fonts` is an array instead of a record.
- Throws if `paths` is not `true` or `false`.
```

--------------------------------

### Mark your own target with report-start.marking

Source: https://getquario.com/docs/diving-deeper/licensing

For custom targets that need to mark output when unlicensed. Reads `report-start.marking` and draws it; do not restate the wording or derive it from the document.

```ts
import { walk } from 'quario'

await walk(report.stream(data), {
  'report-start': (e) => {
    if (e.marking) console.log(e.marking)
  },
})
```

--------------------------------

### xlsx(options?)

Source: https://getquario.com/docs/reference/xlsx

The xlsx() factory function that creates the spreadsheet render target.

```APIDOC
## `xlsx(options?)`

### Description
Returns the spreadsheet render target. It takes three options, `meta`, `page` and `filter`. Any other key, or one of the wrong type, throws a `TypeError` naming the path. The factory reads `meta` once and copies it, so mutating that object between renders no longer changes the workbook.

### Signature
```ts
function xlsx(options?: XlsxOptions): Target<'xlsx', Promise<Uint8Array>>
```

### Parameters
#### Options
- **`meta`** (`XlsxMeta`) - Optional document information.
- **`page`** (`XlsxPage`) - Print setup, written to every worksheet.
- **`filter`** (`boolean`) - Put an autofilter over a worksheet’s one table. Off unless asked.

### Returns
- **`Target<'xlsx', Promise<Uint8Array>>`** - The target that resolves workbook bytes with typed cells.

### Errors
- Throws a `TypeError` if any option key is not one of `meta`, `page`, `filter`, or if the value is of the wrong type.
```

--------------------------------

### Painting a page to canvas

Source: https://getquario.com/docs/reference/layout

Shows how to render a page to a canvas, sizing the canvas to the paper dimensions and scaling by 2. The canvas must be sized to the paper, not the page, or content will be clipped.

```typescript
import { layout, paint } from '@quario/layout'

const list = await report.render(layout({ page: { size: 'A4' } }), data)

canvas.width = list.width * 2        // the paper's, never a page's
canvas.height = list.height * 2
await paint(ctx, list.pages[0], { scale: 2 })
```
Tokens:
Raw