Haystack Client

A client haystack implementation written in TypeScript. Currently this API is specifically targeted to work with the FIN Framework's web server.

This library uses haystack-core.

Installation

Use the following npm command to install haystack client...

npm install @j2inn/haystack-core @j2inn/haystack-client

Note how haystack-core must be installed as a peer dependency.

Client

A set of useful high level of APIs for working with Haystack data in the FIN framework's server.

// Query all the available sites server side...
const grid = await client.read('site')

Unless you're building your own APIs, it's recommended to use the Client APIs. These APIs build on top of the fetchGrid API.

Watch

Watches are used to watch for live events on records...

// Resolve a grid with ids.
const grid = await hs.client.read('point and navName == "SAT"')

// Create a watch and give it a display name.
const watch = hs.client.watch('All SAT points', grid)

// Add event handlers. We're only interested in 'curVal' changes.
watch.changed({
  interests: ['curVal'],
  callback: (event) => console.log(event)
})

...

// Always close a watch after using it.
await watch.close()

Haystack filters can also be used to watch for specific conditions...

// Add event handlers. We're only interested in changes to curVal when it's above a certain value.
watch.changed({
	interests: ['curVal'],
	condition: 'curVal > 50°F',
	callback: (event) => console.log(event),
})

fetchVal

The fetchVal API builds on top of hsFetch. It adds all the necessary encoding and decoding of a haystack value in one API call.

const dict = await fetchVal<HDict>('/api/demo/somethingnew')

For backwards compatibility, there is also a fetchGrid that calls fetchVal.

Hayson

Decoding values from Hayson will happen transparently when the server responds with the correct MIME type.

To send Hayson, consider the following code...

const dict = await fetchVal<HDict>('/api/demo/somethingnew', {
	method: 'POST',
	headers: { 'Content-Type': HAYSON_MIME_TYPE },
	body: JSON.stringify(hval.toJSON()),
})

hsFetch

The fetch API is used by web developers to make network calls.

The hsFetch API wraps fetch and adds some additional useful behaviors...

• Automatic background management of CSRF tokens (a.k.a. Attest Keys).
• Additional methods to make it easier for working with Haystack data. For example, a response has a toGrid method.

This API is designed as low level. The fetchVal API builds on top of this API.

Use this API if you want to work with the web server but aren't going to work with grids.

// Call a JSON REST API...
const resp = await hsFetch('/someApi')
const someJson = await resp.json()

CSRF protection

By default, haystack-client is designed to work with FIN's web server. When used the library attempts to automatically resolve a CSRF token (attest key).

To change this behavior, implement a requestHaystackAttestKey function on globalThis to change how the attest key is acquired...

window.requestHaystackAttestKey = async (resource: string, options: RequestInit): Promise<string> {
	// TODO: request the attest key. Return a promise with an empty string when no attest key is to be used.
}