Wire on Palmyra

AsyncStore contracts

Mon, 01 Jan 0001 00:00:00 +0000

AsyncStore contracts#

@palmyralabs/palmyra-wire · lib/palmyra/store/AsyncStore.ts

Overview#

The TypeScript contract surface for every store the factory emits. Four read interfaces (LookupStore, QueryStore, GridStore, TreeQueryStore), one write interface (DataStore), plus helpers (ChartStore, AuthDecorator). DataStore is the form contract — there is no separate AsyncFormStore.

Interfaces#

interface BaseQueryStore<T> {
  getClient(): AxiosInstance;
}

interface AbstractQueryStore<T> extends BaseQueryStore<T> {
  query(request: QueryRequest): Promise<QueryResponse<T>>;
}

interface LookupStore<T> extends AbstractQueryStore<T> {}

interface QueryStore<T> extends AbstractQueryStore<T> {
  queryLayout(request: QueryRequest): Promise<any>;
  get(request: GetRequest): Promise<T>;
  getIdentity(o: T): any;
  getIdProperty(): strings;
}

interface GridStore<T> extends QueryStore<T> {
  export(request: ExportRequest): void;
}

interface DataStore<T> extends QueryStore<T> {
  post(data: T, request?: PostRequest):   Promise<T>;
  put(data: T,  request?: PutRequest):    Promise<T>;
  save(data: T, request?: PutRequest):    Promise<T>;
  remove(key: T | any, request?: RemoveRequest): Promise<T>;
}

interface TreeQueryStore<T, R> extends BaseQueryStore<T> {
  getChildren(data: T, options?: AbstractHandler): Promise<QueryResponse<R>>;
  getRoot(options?: AbstractHandler): Promise<R>;
}

interface ChartStore<T> {
  query(request: QueryRequest): Promise<T[]>;
}

interface AuthDecorator {
  decorate(request: any): void;
}

interface DefaultQueryParams {
  filter?: Record<any, any>;
  sort?:   strings;
}

Shared `StoreOptions`#

Every concrete store takes this options object (from lib/palmyra/store/Types.ts):

PalmyraStoreFactory

Mon, 01 Jan 0001 00:00:00 +0000

PalmyraStoreFactory#

@palmyralabs/palmyra-wire · PalmyraStoreFactory

Overview#

Single entry point. Configure a baseUrl, an errorHandlerFactory, and shared StoreOptions once; use the factory everywhere else to get per-endpoint stores. Each getter merges the factory’s storeOptions with the per-call options — per-call wins.

Constructor#

interface PalmyraStoreFactoryArg {
  baseUrl?:             string;                      // default '/palmyra'
  errorHandlerFactory?: APIErrorHandlerFactory;
  storeOptions?:        StoreOptions;
}

new PalmyraStoreFactory(props: PalmyraStoreFactoryArg)

Methods#

Method	Signature
`getGridStore`	`getGridStore(options, endPoint, idProperty?) → GridStore<any>`
`getFormStore`	`getFormStore(options, endPoint, idProperty?) → DataStore<any>`
`getLookupStore`	`getLookupStore(options, endPoint, idProperty) → LookupStore<any>`
`getChartStore`	`getChartStore(options, endPoint, idProperty?) → ChartStore<any>`
`getTreeStore`	`getTreeStore(options, endPoint) → TreeQueryStore<any, any>`

Argument types (shared across all five):

PalmyraAbstractStore

Mon, 01 Jan 0001 00:00:00 +0000

PalmyraAbstractStore#

@palmyralabs/palmyra-wire · PalmyraAbstractStore (exported as AbstractStore)

Overview#

HTTP base class every Palmyra store extends. Holds the shared AxiosInstance, the baseUrl, the IEndPoint (string or per-verb MultiEndPoint), and helpers for URL formatting and query-param conversion. Installs a response interceptor that hands errors to the factory-level error handler.

Not a store on its own — you subclass it or, in practice, let the factory hand you a concrete store that already extends it.

PalmyraGridStore

Mon, 01 Jan 0001 00:00:00 +0000

PalmyraGridStore#

@palmyralabs/palmyra-wire · PalmyraGridStore implements GridStore<any>

Overview#

Read-side store for paginated grids. Paged query, single-record get, a schema endpoint for column metadata, and a browser-driven export that opens a _format-suffixed URL in a new window.

Usually obtained via factory.getGridStore(...) rather than constructed directly.

Constructor#

new PalmyraGridStore(
  baseUrl:    string,
  endPoint:   IEndPoint,
  options:    StoreOptions,
  factory?:   APIErrorHandlerFactory,
  idProperty?: strings,
)

Methods#

Method	Signature
`query`	`query(request: QueryRequest): Promise<QueryResponse<any>>` — GET with `_offset/_limit/_orderBy/_total` params
`queryLayout`	`queryLayout(request: QueryRequest): Promise<any>` — same URL, header `action: 'schema'`; returns column metadata
`get`	`get(request: GetRequest, idProperty?: string): Promise<any>` — GET a single row; unwraps `response.data.result`
`export`	`export(request: ExportRequest): void` — opens `url?...&_format=csv\|excel\|pdf\|doc` in a new window
`getEndPoint`	`getEndPoint(): IEndPoint`
`getIdProperty`	`getIdProperty(): string` — hard-coded `"id"` (constructor arg is ignored)
`getIdentity`	`getIdentity(o): any` — throws `Method not implemented`

Example#

import AppStoreFactory from './wire/StoreFactory';

const users = AppStoreFactory.getGridStore({}, '/user');

// paged query
const page = await users.query({
  filter: { status: 'ACTIVE' },
  sort:   ['-createdAt'],
  offset: 0,
  limit:  25,
});
console.log(page.result.length, page.total);

// single row
const ada = await users.get({ id: 42 });

// schema for a dynamic column picker
const schema = await users.queryLayout({});

// export the current filter as CSV
users.export({ filter: { status: 'ACTIVE' }, format: 'csv' });

Caveat — `getIdProperty`#

The implementation returns the literal string "id" regardless of what you pass into the constructor. If your rows key on something else, plumb the real id-property through your grid configuration instead of relying on store.getIdProperty().

PalmyraDataStore

Mon, 01 Jan 0001 00:00:00 +0000

PalmyraDataStore#

@palmyralabs/palmyra-wire · PalmyraDataStore<T> extends PalmyraGridStore implements DataStore<T>

Overview#

Full CRUD store. Inherits query / queryLayout / get / export from PalmyraGridStore, adds post / put / save / remove. save is the upsert verb — POST with header action: 'save' — handy when the backend decides insert-vs-update from the payload.

Usually obtained via factory.getFormStore(...).

Constructor#

new PalmyraDataStore<T>(
  baseUrl:    string,
  endPoint:   IEndPoint,
  options:    StoreOptions,
  factory?:   APIErrorHandlerFactory,
  idProperty?: strings,
)

Use a MultiEndPoint when the paths diverge per verb:

PalmyraLookupStore

Mon, 01 Jan 0001 00:00:00 +0000

PalmyraLookupStore#

@palmyralabs/palmyra-wire · PalmyraLookupStore implements LookupStore<any>

Overview#

Minimal query-only store — intended for autocomplete, dropdown, and picker lookups where the UI just needs a filtered list and nothing else. Same wire format as the grid store but with a smaller surface.

Obtain via factory.getLookupStore(...).

Constructor#

new PalmyraLookupStore(
  baseUrl:    string,
  endPoint:   IEndPoint,
  options:    StoreOptions,
  factory?:   APIErrorHandlerFactory,
  idProperty?: strings,
)

Methods#

Method	Signature
`query`	`query(request: QueryRequest): Promise<QueryResponse<any>>` — same GET pattern as grid; returns the full `QueryResponse` (`result` + `total`)
`getClient`	inherited — direct axios access when needed

Example#

Debounced autocomplete against a master-data endpoint:

PalmyraChartStore

Mon, 01 Jan 0001 00:00:00 +0000

PalmyraChartStore#

@palmyralabs/palmyra-wire · PalmyraChartStore implements ChartStore<any>

Overview#

One-shot chart-data fetch. Issues a GET against the endpoint with the supplied QueryRequest (filter/sort/pagination), unwraps response.data.result, and returns it as an array ready for your chart library.

No get / save / export — only query. If you need paginated results, use PalmyraGridStore instead.

Obtain via factory.getChartStore(...).

Constructor#

new PalmyraChartStore(
  baseUrl:    string,
  endPoint:   IEndPoint,
  options:    StoreOptions,
  factory?:   APIErrorHandlerFactory,
  idProperty?: strings,
)

Methods#

Method	Signature
`query`	`query(request: QueryRequest): Promise<any>` — returns the unwrapped `result` array
`getClient`	inherited

Example#

import { useEffect, useState } from 'react';
import ReactApexChart from 'react-apexcharts';
import AppStoreFactory from './wire/StoreFactory';

export function MonthlySalesChart() {
  const [series, setSeries] = useState<any[]>([]);

  useEffect(() => {
    const store = AppStoreFactory.getChartStore({}, '/report/monthly-sales');
    store.query({ filter: { year: 2026 } }).then(rows => {
      setSeries([{ name: 'Sales', data: rows.map((r: any) => [r.month, r.total]) }]);
    });
  }, []);

  return (
    <ReactApexChart
      type="line"
      series={series}
      options={{ chart: { id: 'monthly-sales' }, xaxis: { type: 'category' } }}
    />
  );
}

PalmyraTreeStore

Mon, 01 Jan 0001 00:00:00 +0000

PalmyraTreeStore#

@palmyralabs/palmyra-wire · PalmyraTreeStore implements TreeQueryStore<IChildTreeRequest, any>

Overview#

Hierarchical store for tree-shaped data — menu systems, organisation charts, category trees. Every request sends header action: 'nativeQuery'; the backend decides how to serve it (typically a recursive CTE or a parent_id index).

Obtain via factory.getTreeStore(...).

Types#

interface IChildTreeRequest {
  parent?: number;   // id of the parent node; omitted for root
}

Constructor#

new PalmyraTreeStore(
  baseUrl:    string,
  endPoint:   IEndPoint,
  options:    StoreOptions,
  factory?:   APIErrorHandlerFactory,
  idProperty?: strings,
)

Methods#

Method	Signature
`getRoot`	`getRoot(options?: AbstractHandler): Promise<any>` — returns the root level
`getChildren`	`getChildren(data: IChildTreeRequest, options?: AbstractHandler): Promise<QueryResponse<any>>` — filters by `parent` id
`query`	`query(request: QueryRequest): Promise<QueryResponse<any>>` — raw GET with `action: 'nativeQuery'` header
`getClient`	inherited

Example#

Lazy-load a tree one level at a time (Mantine-flavoured):

Connecting to a custom backend

Mon, 01 Jan 0001 00:00:00 +0000

Connecting to a custom backend#

Palmyra’s frontend does not require a Palmyra backend. Every grid, form, lookup, chart, and tree component talks through interfaces, not concrete HTTP classes. If your API speaks a different shape — REST with a different envelope, GraphQL, gRPC-web, Firebase, Supabase, a legacy SOAP service — you can plug it in by implementing the same interfaces.

This page walks through the seam: the contracts you implement, the factory you register, and what changes (and what stays the same) on the React side.

Wire on Palmyra

AsyncStore contracts

AsyncStore contracts#

Overview#

Interfaces#

Shared StoreOptions#

PalmyraStoreFactory

PalmyraStoreFactory#

Overview#

Constructor#

Methods#

PalmyraAbstractStore

PalmyraAbstractStore#

Overview#

PalmyraGridStore

PalmyraGridStore#

Overview#

Constructor#

Methods#

Example#

Caveat — getIdProperty#

PalmyraDataStore

PalmyraDataStore#

Overview#

Constructor#

PalmyraLookupStore

PalmyraLookupStore#

Overview#

Constructor#

Methods#

Example#

PalmyraChartStore

PalmyraChartStore#

Overview#

Constructor#

Methods#

Example#

PalmyraTreeStore

PalmyraTreeStore#

Overview#

Types#

Constructor#

Methods#

Example#

Connecting to a custom backend

Connecting to a custom backend#

Shared `StoreOptions`#

Caveat — `getIdProperty`#