@j2inn/haystack-client

Haystack Client

A client haystack implementation written in TypeScript. This API targets standard Haystack web servers plus other non-standard implementations.

This library uses haystack-core.

Optionally use haystack-units for the unit database.

If you're building an application using React try using haystack-react in addition to the core and client libraries.

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.

Servers

This library is used to talk to array of different Haystack servers...

• FIN 5.X: only use the methods under Client ops and ext.
  • Everything under ops uses all the standard Haystack Ops.
  • Everything under ext uses methods specific to SkySpark (i.e. evaluating Axon).
• FINx: in addition to ops, try using the newer Haystack enabled REST API services under Client (i.e. record, schedule, user or proj). Prefer REST API services over ops. Never use ext.

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 using the Haystack read op...
const grid = await client.ops.read('site')

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

Construction

Please note, since a Client instance contains state (i.e. maintains a list of watches), always cache and reuse a Client instance. Do not create a new Client instance everytime you use it!

If you're using haystack-react, the Client is created from a React Context. Use a hook called useClient() to get access to the Client.

If you need to create your own Client object...

FIN5

// Create a client object using the web browser's current URI.
// The project name will be parsed from the URI.
const client = new Client({
	base: new URL(window.location.href)
})

// Explicitly define what project to use...
const clientWithProject = new Client({
	base: new URL(window.location.href),
	project: 'demo'
})

FINx

// For FINx...
const client = new Client({
	base: new URL(window.location.href),
	opsBase: 'haystack',
	// Again the project can be specified if it can't be picked from the browser's current URI.
	// project: 'demo',
	// Optionally prefer Hayson over Zinc...
	options: { headers: { accept: HAYSON_MIME_TYPE } }
})

Watch

Please note, haystack-react contains some hooks that makes this even easier!

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

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

// Create a watch and give it a display name.
const watch = client.ops.watch.make('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()),
})

finCsrfFetch

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

The finCsrfFetch API wraps fetch and automatic background management of CSRF tokens (a.k.a. Attest Keys) for the FIN framework.

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 finCsrfFetch('/someApi')
const someJson = await resp.json()