The model layer: JavaScript Data Grid API

API reference › The model layer

grid.ai

The grid composes a prompt describing its own columns and operators, you send it to whichever model you like, and it validates the reply before anything is applied. It makes no network call and has no default model.

Ask-your-data (modules/ai)

The opt-in AI module (createAI, UMD LatticeGridAI) turns a question into a validated read-only query spec, runs it in the grid's own engine over the grid.ai skill layer, and - on apply - fans the answer to any router-attached viewers (a chart, a KPI tile) through the Data Router's load(). It uses the same BYO ask() seam as the rest of the module: the grid makes no model call and holds no key. Ask-your-data is read-only; a write/mutation the model asks for is refused and never executed (writes are a separate, human-gated feature).

const { createHeadlessGrid } = await import('../packages/core/src/index.js');
const { createAI } = await import('../packages/modules/ai/index.js');
const grid = createHeadlessGrid({
  rowKey: 'id',
  columns: [{ field: 'id' }, { field: 'region' }, { field: 'amount', type: 'number' }],
  rows: [{ id: 1, region: 'EMEA', amount: 100 }, { id: 2, region: 'AMER', amount: 300 }, { id: 3, region: 'EMEA', amount: 200 }],
});
// Your model returns a schema-constrained SPEC, never rows. WE run it, read-only.
const reads = createAI(grid, { ask: async () => ({ actions: [{ type: 'setFilters', filters: { col: 'region', op: 'eq', value: 'EMEA' } }] }) });
const result = await reads.query('EMEA only');
result.apply();
const rows = grid.rows.data().length;
// A write verb is refused by the read-only gate and never executed.
const writes = createAI(grid, { ask: async () => ({ actions: [{ type: 'setCells', edits: [] }] }) });
const write = await writes.query('change the data');
return `${rows} rows; write ${write.ok ? 'allowed' : 'refused'}`;

AI as a governed actor (modules/ai, writes)

The governed actor lets the model propose edits - a single NL-targeted change (“set the Network Upgrade project to In Progress”) or a bulk cleanup - that a human previews as a before/after diff and approves. The model NEVER writes. On approval the edit applies through the grid's own gate, exactly like a person's edit: a grid cell edit via grid.edit.setCells(writes, 'cell', { origin: 'ai' }) (the beforeEdit veto), a Kanban card move via board.move(…, { origin: 'ai' }) (the beforeMove veto). The AI can never bypass the gate: a host beforeEdit/beforeMove handler that calls preventDefault() (or vetoes async) stops the write, and nothing persists. Writes carry origin: 'ai' on the before-event payload, so a host can allow a person's edit while vetoing the AI's - policing AI writes distinctly. Approved edits are optimistic and revert on a source reject through the shipped write-back (there is no separate beforeCommit event; the edit gate is beforeEdit, and the optimistic/revert half is grid.edit.settle).

NL targeting and any bulk edit bind to the current filtered view (grid.rows.data()), never the whole table implicitly; a target not in the view is surfaced for an explicit opt-in widen, not edited silently. A human label is resolved to the column's stored option value; an unknown label is rejected, not coerced. An ambiguous match (more than one row) surfaces its candidates for the user to pick.

const { createHeadlessGrid } = await import('../packages/core/src/index.js');
const { createAI } = await import('../packages/modules/ai/index.js');
const status = { options: [{ id: 'todo', label: 'To do' }, { id: 'doing', label: 'In Progress' }] };
const seed = () => createHeadlessGrid({
  rowKey: 'id',
  columns: [{ field: 'id' }, { field: 'name' }, { field: 'status', lookup: status, edit: { enabled: true } }],
  rows: [{ id: 'r1', name: 'Network Upgrade', status: 'todo' }, { id: 'r2', name: 'Payroll', status: 'todo' }],
});
// A MOCK ask() returns a structured PROPOSAL - never a write, never rows.
const ask = async () => ({ structured: { edits: [{ match: 'Network Upgrade', column: 'status', value: 'In Progress' }] } });

// Propose: a before/after diff, nothing written yet.
let grid = seed();
let ai = createAI(grid, { ask });
const proposal = await ai.propose('set the Network Upgrade project to In Progress');
const d = proposal.diff[0];
const before = `${d.oldDisplay} then ${d.newDisplay}`;

// A vetoing beforeEdit handler on the AI write => NOTHING persists.
grid.on('beforeEdit', (e) => { if (e.origin === 'ai') e.preventDefault('reviewed elsewhere'); });
await ai.applyProposal(proposal);
const vetoed = grid.rows.byKey('r1').data.status;

// Approve on a grid with no veto => the edit lands through the gate.
grid = seed();
ai = createAI(grid, { ask });
await ai.applyProposal(await ai.propose('set the Network Upgrade project to In Progress'));
const approved = grid.rows.byKey('r1').data.status;

return `diff ${before}; vetoed kept ${vetoed}; approved wrote ${approved}`;

grid.diagnostics

What the grid is doing, as data: render counts and their causes, memory layout, operation and provider timing, event listener counts, effective configuration, and a list of things that look like mistakes.

This is the API; the devtools panel is a consumer of it. Built in that order deliberately: instrumentation shaped by a UI tends to report what is convenient to display rather than what is true, and an API that only exists behind a panel cannot be asserted against in a test.

// the assertion this exists to make possible
const before = grid.diagnostics.renders().dom.cellWrites;
grid.filters.set({ col: 'status', op: 'eq', value: 'active' });
await nextFrame();
const written = grid.diagnostics.renders().dom.cellWrites - before;
expect(written).toBeLessThan(200);

The support bundle

bundle() returns configuration, query state, timing history, warnings, provider statistics, version and environment. It never contains row data, cell values or column values, and says so in its own contains field. The guarantee is the point: a bundle that had to be read for confidential content before sending is a bundle nobody sends.

Warnings

Each carries a stable id a support conversation can name, a plain description, and the specific values involved. Two sources are merged: checks run against the grid, and everything the grid has reported through its own one-per-cause warnings.

The warnings reference

Every developer-facing line the grid prints to the console - each one prefixed [lattice] - is de-duplicated on a key, and that key is the identifier to quote. The package ships the whole list as data: docs/warnings.json, inside @toclocoinc/lattice-grid and in the public repository, with one entry per key giving the message template, the module it comes from, what happened and what the grid did about it, and what to change. A * in an identifier stands for a value filled in at run time - a column id, a chart id, an event name - so icon:* is one entry covering every column the icon renderer refuses.

// look up the line you are reading in the console
const { warnings } = await import('@toclocoinc/lattice-grid/docs/warnings.json', { with: { type: 'json' } });
const entry = warnings.find((w) => w.id === 'rowKey.missing');
console.log(entry.meaning, entry.fix);

The devtools panel

An optional module. It imports nothing (the grid is handed to it) so deployments that never load it pay nothing.

import { createGrid } from '@toclocoinc/lattice-grid';
import { createDevtools } from '@toclocoinc/lattice-grid/modules/devtools';

const grid = createGrid(el, config);
createDevtools({ grid });          // Ctrl+Shift+D collapses it

Nine tabs over the API above, a compact vitals strip to leave open while working, and a render heat overlay that tints cells as they are written: blue for a new value, red for a cell rewritten with the value it already held. The second colour is the one worth chasing: it is work the grid did not need to do, and no counter alone will tell you where it is.

grid.licence

There is one Lattice Grid and every copy is feature-identical. No community edition, no pro tier, no feature held back behind a key. A licence removes the trial watermark; that is the whole of what it does.

Free to develop against, licensed to deploy. A grid on localhost, or any loopback host: needs no key at all. On any other domain an unlicensed grid still renders everything and carries a small trial watermark linking to latticegrid.dev. Nothing ever refuses to render: the failure worth avoiding is a broken production screen, and no licensing state is worth causing one.

// Before creating a grid.
LatticeGrid.setLicence('LG1.…');           // your key; setLicense also works

const grid = LatticeGrid.createGrid(el, config);
grid.licence.state();      // 'licensed' | 'localhost' | 'trial'

Domains

A key names the hosts it covers. *.acme.com matches app.acme.com, a.b.acme.com and acme.com itself, a wildcard that refused the apex would be a puzzle rather than a licence. A bare acme.com matches only itself, and a key naming no domains is valid anywhere. Matching ignores case and a trailing dot.

Getting a key

Keys are issued from latticegrid.dev. A key is issued per domain rather than per developer or per seat: name the domains the grid will run on and one key covers every developer, every build and every user on them.

Keys are perpetual by default. A key carries no expiry unless one was deliberately issued (a trial, a time-boxed pilot) so the ordinary key is valid until the domains it names change, not one that quietly lapses on a date nobody is tracking.

Checking a key needs no network. There is no licence server, no call home, and nothing that can fail at three in the morning, a key carries its own answer and the grid reads it locally, fresh on every load. A key for the wrong domain, or a key that will not read at all, does the same thing a genuinely expired trial key does: log one console warning and show the watermark.

The terms marker

A key's payload may carry a terms marker: 'non-commercial' for the free tier, and 'commercial' - or absent, which is the same thing - for everything else. grid.licence.info() reports it as terms. The marker is carried and reported, never enforced by the software: non-commercial terms are enforced by the licence terms, not by the grid. There is no phone-home, no feature difference, and no network call of any kind - a non-commercial key behaves exactly like any other valid key.

const { createHeadlessGrid } = await import('../packages/core/src/index.js');

// No key installed, and absent means 'commercial': the status API reports it.
const grid = createHeadlessGrid({ columns: [{ id: 'n', field: 'n' }], rows: [{ id: '1', n: 'a' }] });
const terms = grid.licence.info().terms;
grid.destroy();

return terms;

Formulas

A leading = in a numeric cell is a formula. The grid stores what it comes to.

=5 + 5
=quantity * unitPrice
=[Unit Price] * 1.2
=ROUND(quantity * unitPrice, 2)
=IF(quantity > 10, "bulk", "single")
=SUM(readings)              // an array property on the row

References name columns of the same row, not cells, a grid sorts, filters, groups and pages, so A1 would mean a different row from one moment to the next. Matching is on field or title, ignoring case and spacing; bracket a name that contains spaces. A property with no column of its own is reachable too.

Operators + - * / ^ with parentheses, comparison for IF, and postfix %. ^ is right-associative and unary minus binds tighter than it, so -2^2 is 4: Excel's answer rather than mathematics'.

// Your own functions, on top of the built-in library.
createGrid(el, {
  formulaFunctions: {
    MARGIN: ([revenue, cost]) => (revenue - cost) / revenue,
  },
});

Module and utility APIs

Everything else the package declares. Each entry is public: it is declared in the type definitions, which is what makes it a promise.

Locale and messages

Formulas and units

Statistic tiles

Licensing and modules

Ingesting rows, and menus

The charts module

The framework adapters

React, Vue and Svelte build their public surface from the same list, so an event becomes a prop or an emit without either side keeping a second copy.

The web component

The htmx module

The devtools module

Windowed aggregates

The primitives behind grid.statistics.windowed, for a host that drives a live stream itself: a sliding window over timestamped values that re-reduces on demand and stamps every figure with the window it covered. Reduce over the last N ticks, the last N minutes, or the whole session.

const { openWindow, Window, WINDOW_KINDS } = await import('../packages/core/src/index.js');
// openWindow builds one of the three kinds; here, the last 3 ticks.
const live = openWindow({ kind: 'count', span: 3 });
for (const v of [10, 20, 30, 40]) live.push(v); // 10 is evicted; 20, 30, 40 remain
const avg = live.reduce('avg'); // (20 + 30 + 40) / 3 = 30, stamped with the window it covers
// A Window can be built directly too; a session window never evicts.
const session = new Window('session');
session.push(5);
session.push(15);
return `avg ${avg.value} over ${avg.over.size}; kinds ${WINDOW_KINDS.join('/')}; session ${session.reduce('avg').value}`;

Anomaly detection

Flag the rows that do not belong. Interpretable statistics with a written-down cut, never a black box: a robust per-column outlier score, Tukey's fences, and multivariate distance from the joint centre. These are the pure kernels behind grid.statistics.anomalies(...) and the anomalyScore/anomalyFlag shadow columns; a host can score a plain array the same way the grid scores a column.

const { modifiedZScores, iqrFences, mahalanobis, ANOMALY_METHODS } = await import('../packages/core/src/index.js');
// Univariate: the robust modified z-score flags the 500 among steady readings,
// where the mean and standard deviation an ordinary z uses would be dragged up
// by the outlier until it no longer looked like one.
const z = modifiedZScores([20, 21, 19, 20, 21, 19, 20, 500]);
// Tukey's fences say the same, drawn the way a box plot draws them.
const fence = iqrFences([20, 21, 19, 20, 21, 19, 20, 500]);
// Multivariate: height and weight move together; the last person is tall but
// very light, so the pair is impossible even though neither number is extreme.
const hw = [];
for (let i = 0; i < 12; i++) hw.push([160 + i, 60 + i]);
hw.push([182, 45]);
const m = mahalanobis(hw); // the χ² cut flags the off-line row
return `methods ${ANOMALY_METHODS.length}; flagged ${z.flagged}; upper ${fence.upper}; joint ${m.flags[12]}`;

Rolling (windowed) detection and the Data Router bridge: judge each reading against its trailing window for live monitoring, and turn any detector into a router.alert(...) condition without a second alert engine.

const { rollingAnomalies, anomalyCondition, ROLLING_ANOMALY_METHODS } = await import('../packages/core/src/index.js');
// A steady stream that suddenly spikes. The trailing window catches the spike
// against its recent neighbours, where scoring against the whole run could let a
// long earlier drift hide it.
const stream = [10, 11, 9, 10, 11, 9, 10, 11, 9, 10, 40];
const roll = rollingAnomalies(stream, { windowLen: 6, minPeriods: 4 });
// The SAME detector, wired as a Data Router alert condition: (rows) => signal,
// exactly the predicate router.alert(value, condition, handler) already drives - // no second alert engine. `latest` fires only when the newest tick is the one out.
const condition = anomalyCondition({ field: 'temp', method: 'rollingModifiedZScore', orderBy: 't', windowLen: 6, minPeriods: 4, latest: true });
const rows = stream.map((temp, t) => ({ t, temp }));
const signal = condition(rows);
return `methods ${ROLLING_ANOMALY_METHODS.length}; spike ${roll.flags[10]}; alert ${signal ? signal.flagged.length : 0}`;

Forecasting

Project an ordered series forward, and carry a prediction band where a defensible closed form exists. Five methods behind one entry point: movingAverage and ses are flat forecasts (the trailing-window mean, the final smoothed level); holt adds a projected trend, holtWinters a projected trend and an additive seasonal; linear extrapolates an ordinary least-squares fit of the time axis. The exponential-smoothing bands are the innovations state-space forecast variances (Hyndman & Athanasopoulos) at the normal quantile; the linear and moving-average bands are the exact Student-t intervals, and linear also reports the narrower mean-response (confidence) band a trendline draws. These are the pure kernels the chart trendline overlay and the time-series grid forecast from; a host can forecast a plain array the same way.

const { forecast, FORECAST_METHODS } = await import('../packages/core/src/index.js');
// Linear: fit the time axis, project one step, and carry the prediction band.
const lin = forecast([{ at: 1, value: 2 }, { at: 2, value: 4 }, { at: 3, value: 5 }, { at: 4, value: 4 }, { at: 5, value: 5 }], { method: 'linear', horizon: 1 });
const p = lin.points[0];
// Holt-Winters additive: a level, a trend and a two-step season, projected two
// steps ahead - the seasonal swing is carried into the forecast, not smoothed away.
const hw = forecast([10, 20, 30, 40], { method: 'holtWinters', period: 2, alpha: 0.5, beta: 0.5, gamma: 0.5, horizon: 2 });
return `methods ${FORECAST_METHODS.length}; next ${p.mean.toFixed(1)}; r2 ${lin.r2.toFixed(1)}; band ${p.lower.toFixed(2)}..${p.upper.toFixed(2)}; season ${hw.points[1].mean}`;

The same forecast off the standard stats surface: grid.statistics.forecast(colId, opts) reads the column over the filtered rows - ordered by opts.by when the time axis matters, exactly as grid.statistics.series(...) orders - and returns the same ForecastResult, so a host reaches a forecast the way it reaches grid.statistics.anomalies(...) rather than assembling the series itself.

const { createHeadlessGrid } = await import('../packages/core/src/index.js');
const grid = createHeadlessGrid({
  columns: [{ field: 't', type: 'number' }, { field: 'v', type: 'number' }],
  rows: [[1, 2], [2, 4], [3, 5], [4, 4], [5, 5]].map(([t, v], i) => ({ id: String(i), t, v })),
  rowKey: 'id',
});
// Forecast the 'v' column one step ahead, ordered by 't', with the prediction band.
const f = grid.statistics.forecast('v', { by: 't', method: 'linear', horizon: 1 });
const p = f.points[0];
return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.lower > 0}`;