See throttle for more details about the parameters and the
returned throttled function's .finish() method.

---

@reykjavik/webtools/errorhandling

A small set of lightweight tools for handling errors and promises in a safer,
more structured, FP-ish way.

Errors are always the first return value to promote early, explicit error
handling.

$3

Syntax: asError(maybeError: unknown): ErrorFromPayload

Guarantees that a caught (catch (e)) value of unknown type, is indeed an
Error instance.

If the input is an Error instance, it is returned as-is. If the input is
something else it is wrapped in a new ErrorFromPayload instance, and the
original value is stored in as a payload property, and it's .toString() is
used for the message property.

`ts
import { asError, type ErrorFromPayload } from '@reykjavik/webtools/errorhandling';

const theError = new Error('Something went wrong');
try {
throw theError;
} catch (err) {
// theError is an instance of Error so it's returned as-is
const error = asError(theError);
console.error(error === theError); // true
console.error('payload' in error); // false
}

const someObject = ['Oops', 'Something went wrong'];
try {
throw someObject;
} catch (err) {
// the thrown someObject is not an Error so an ErrorFromPayload is returned
const error = asError(someObject);
console.error(error === someObject); // false
console.error(error instanceOf ErrorFromPayload); // true

console.error(error.payload === someObject); // true
console.error(error.message === someObject.join(',')); // true
}
`

$3

Singleton object with the following small methods for creating, mapping or
handling ResultTupleObj instances:

- Result.Success
- Result.Fail
- Result.catch
- Result.map
- Result.throw

$3

Syntax: ResultTuple

(Also aliased as Result.Tuple)

Simple bare-bones discriminated tuple type for a [error, result] pair.

`ts
import { type ResultTuple } from '@reykjavik/webtools/errorhandling';

declare const myResult: ResultTuple;

const [error, result] = myResult;
// (One of these two is always undefined)

if (error) {
// Here error is an Error instance
console.error(error.message);
} else {
// Here result is guaranteed to be a string
console.log(result);
}
`

$3

Syntax: ResultTupleObj

(Also aliased as Result.TupleObj)

Discriminated tuple type for a [error, result] pair (same as ResultTuple)
but with named properties error and result attached for dev convenience.

It also has a .mapTo method (see below).

`ts
import { type ResultTupleObj } from '@reykjavik/webtools/errorhandling';

declare const myResult: ResultTupleObj;

const [error, result] = myResult;
// (One of these two is always undefined)

if (error) {
// Here error is an Error instance
console.error(error.message);
} else {
// Here result is guaranteed to be a string
console.log(result);
}

// But myResults also has named properties, for convenience
if (myResult.error) {
// Here myResult.error is an Error instance
console.error(myResult.error.message);
} else {
// Here myResult.result is a string
console.log(myResult.result);
}
`

#### Type ResultTupleObj.mapTo

Syntax:
ResultTupleObj.mapTo(mapResult: (resultValue: T) => T2): ResultTuple

This convenience method allows quick mapping of the ResultTubleOBj's result
value to a new type. The returned value is also a ResultTubleOBj.

(Internally this method calls Result.map.)

`ts
import { type ResultTuple } from '@reykjavik/webtools/errorhandling';

declare const myResult: ResultTuple;

const mappedResult: ResultTupleObj = myResult.mapTo(
(result: string) => result.length
);

if (mappedRes.error) {
console.error(myResult.error.message);
} else {
// Here myResult.result is a number
console.log(myResult.result);
}
`

If the original ResultTupleObj is in a failed state, the mapping function is
not called.

If the mapping function throws an error it gets caught and turned into a
failed ResultTupleObj.

$3

Aliased as Result.ify for readability.

Syntax:
Result.catch(callback: () => T): ResultTupleObj
Syntax:
Result.catch(promise: Promise): Promise>

Error handling utility that wraps a promise or a callback function.

Catches errors and returns a ResultTupleObj — a nice discriminated
[error, results] tuple with the result and error also attached as named
properties.

Works on both promises and sync callback functions.

`ts
import { Result } from '@reykjavik/webtools/errorhandling';

// Callback:
const [error, fooObject] = Result.catch(() => getFooSyncMayThrow());
// Promise:
const [error, fooObject] = await Result.catch(getFooPromiseMayThrow());

// Example of object property access:
const fooQuery = await Result.catch(getFooPromiseMayThrow());
if (fooQuery.error) {
console.log(fooQuery.error === fooQuery[0]); // true
throw fooQuery.error;
}
console.log(fooQuery.result === fooQuery[1]); // true
fooQuery.result; // Guaranteed to be defined
`

This function acts as the inverse of Result.throw().

$3

Syntatic sugar alias of Result.catch.

$3

Syntax:
Result.map(result: ResultTuple, mapResult: (resultValue: T) => T2): ResultTuple

Convenience helper to map a ResultTuple-like object to a new
ResultTupleObj object, applying a transformation function to the result, but
retaining the error as-is. Errors thrown from the mapping function are caught
and turned into a failed ResultTupleObj.

`ts
import { Result } from '@reykjavik/webtools/errorhandling';

const getStrLength = (str: string) => str.length;

const resultTuple =
Math.random() < 0.5 ? [new Error('Fail')] : [undefined, 'Hello!'];

const [error, mappedResult] = Result.map(resultTuple, getStrLength);

if (result) {
console.log(result); // 6
}
`

$3

Syntax: Result.Success(result: T): ResultTuple

Factory for creating a successful ResultTupleObj.

`ts
import { Result } from '@reykjavik/webtools/errorhandling';

const happyResult: Result.SuccessObj =
Result.Success('My result value');

console.log(happyResult.error); // undefined
console.log(happyResult[0]); // undefined
console.log(happyResult.result); // 'My result value'
console.log(happyResult[1]); // 'My result value'
`

$3

Syntax: Result.Fail(err: T): ResultTuple

Factory for creating a failed ResultTupleObj.

`ts
import { Result } from '@reykjavik/webtools/errorhandling';

const happyResult: Result.FailObj = Result.Fail(new Error('Oh no!'));

console.log(happyResult.error.message); // 'Oh no!'
console.log(happyResult[0].message); // 'Oh no!'
console.log(happyResult.result); // undefined
console.log(happyResult[1]); // undefined
`

$3

Syntax: Result.throw(result: ResultTuple): T

Unwraps a discriminated ResultTuple-like [error, result] tuple and throws
if there's an error, but returns the result otherwise.

`ts
import { Result } from '@reykjavik/webtools/errorhandling';

try {
const fooResults = Result.throw(await getFooResultsTuple());
} catch (fooError) {
// Do something with the error from getFooResultsTuple()
}
`

This function acts as the inverse of Result.catch().

$3

Syntax:
Result.PayloadOf | Promise> | ((...args: Array) => ResultTuple | Promise>)>

This utility type extracts the successful payload type T from a
Result.Tuple-like type, a Promise of such type, or a function returning
either of those.

`ts
import { Result } from '@reykjavik/webtools/errorhandling';

type ResTpl = Result.Tuple;
type ResTplPromise = Promise>;
type ResTplFn = (arg: unknown) => Result.Tuple;
type ResTplPromiseFn = (arg: unknown) => Promise>;

type Payload1 = Result.PayloadOf; // string
type Payload2 = Result.PayloadOf; // number
type Payload3 = Result.PayloadOf; // boolean
type Payload4 = Result.PayloadOf; // Date
`

---

@reykjavik/webtools/SiteImprove

Contains React helpers for loading SiteImprove's analytics scripts, and
perform page-view and custom event tracking in applications with client-side
(pushState) routing.

$3

A component for loading a SiteImprove analytics script and set up page-view
tracking across URL routes.

It also automatically logs all out-bound link clicks, to match the behavior of
the vanilla SiteImprove script.

Props:

The Component's props have detailed JSDoc comments (displayed in your code
editor), but there's a brief summary:

- accountId?: string — Your SiteImprove account ID. (alternative to
scriptUrl prop).
- scriptUrl?: string — The full SiteImprove analytics script URL.
(alternative to accountId prop).
- hasConsented?: boolean — Manual GDPR 'analytics' consent flag. A false
value allows hard opt-out, but defers to
CookieHubProvider values if they are available.
Defaults to undefined which means "ask CookieHub if available, otherwise
no".
- onLoad?: (e: unknown) => void — Fires when the script has loaded.
- onError?: (e: unknown) => void — Fires if loading the script failed.

Example usage somewhere in your application:

`jsz
import { SiteImprove } from '@reykjavik/webtools/SiteImprove';

const siteImproveAccountId = '[ACCOUNT_ID]'; // e.g. "7654321"

// ...then inside your main App component
;
`

In dev mode it does NOT load the SiteImprove script and merely logs page-view
events to the console.

$3

Syntax:
pingSiteImprove(category: string, action: string, label?: string): void

A small helper for tracking custom UI events and reporting them to SiteImrove.

It safely manages GDPR consent, so you can use it unconditionally.

`js
import { pingSiteImprove } from '@reykjavik/webtools/SiteImprove';

const handleSubmit = () => {
// perform submit action...
if (success) {
pingSiteImprove('application', 'add_new');
}
};
`

$3

Syntax: pingSiteImproveOutbound(ourl: string): void

A small helper for reporting to SiteImrove when the user is programmatically
being sent to a different URL/resource.

`js
import { pingSiteImproveOutbound } from '@reykjavik/webtools/SiteImprove';

const handleSubmit = () => {
// perform submit action...
if (success) {
const fileUrl = '/download/report.pdf';
pingSiteImproveOutbound(fileUrl);
document.location.href = fileUrl;
}
};
`

---

@reykjavik/webtools/CookieHubConsent

Contains React helpers for loading CookieHub's consent manager and reading
users' consent values.

$3

This context provider component loads and initialises the CookieHub consent
management script and sets up a React state object with the relevant user
consent flags.

Wrap this provider around your component tree, and then use the
useCookieHubConsent() hook to retrieve live consent
information, whereever you wish to set GDPR-affected cookies or perform any
sort of tracking/logging.

`js
import { CookieHubProvider } from '@reykjavik/webtools/CookieHubConsent';

import { AnalyticsStuff } from '../components/AnalyticsStuff';

// Maybe move this to an Env variable, or something...
const cookiehubAccountId = '[ACCOUNT_ID]'; // e.g. "a4b3c2d1"

export default function App() {
return (



- accountId?: string | undefined — Your CookieHub account ID. (alternative
to scriptUrl prop). Pass undefined to skip loading the script.
- scriptUrl?: string — The full CookieHub embed script URL. (alternative to
accountId prop).
- options?: CookieHubOptions — Raw CookieHub options object that gets used
when the script initializes.
- onError?: OnErrorEventHandlerNonNull — Fires if loading the script failed.

$3

Syntax: useCookieHubConsent(): Record

Returns up-to-date cookie consent boolean flags. For use in React components
or hook functions.

`js
import { useCookieHubConsent } from '@reykjavik/webtools/CookieHubConsent';

export const AnalyticsStuff = (props) => {
const consent = useCookieHubConsent();
if (!consent.analytics) {
return null;
}
// Perform analytics...
};
`

If the CookieHubProvider is missing from the VDOM tree above your component,
this hook will return an empty object.

---

@reykjavik/webtools/vanillaExtract

Contains helpers for writing vanilla-extract
styles using plain CSS styntax.

This provides an "escape hatch" into regular CSS, when you're willing to trade
local type-safety for access to the full features and expressiveness of real
CSS.
(Background info.)

$3

Syntax:
vanillaClass(css: string | ((className: string, classNameSelector: string) => string)): string
Syntax:
vanillaClass(debugId: string, css: string | ((className: string, classNameSelector: string) => string)): string

Returns a scoped cssClassName styled with free-form CSS. This function is a
thin wrapper around vanilla-extract's style function.

When you pass it a string, all && tokens are automatically replaced with the
selector for the auto-generated class-name. Note that in such cases EVERY
style property must be wrapped in a selector block.

To opt out of the && replacement, use the callback function signature.

`ts
// someFile.css.ts
import { vanillaClass } from '@reykjavik/webtools/vanillaExtract';

// 1) Simple class selector block — no sub-selectors — auto-wrapped
// in a class-name selector block.
export const myClass = vanillaClass(
background-color: #ccc;
padding: .5em 1em;
);
// Generated CSS:
/*
.x1y2z3 {
background-color: #ccc;
padding: .5em 1em;
}
*/

// ---------------------------------------------------------------------------

// 2) More advanced usage with && tokens that get replaced with the
// generated class-name selector (prefixed with a dot).
export const myClasWithAmp = vanillaClass(

&& {
background-color: #ccc;
padding: .5em 1em;
}
&& > strong {
color: #c00;
}
@media (min-width: 800px) {
&& {
background-color: #eee;
}
}
/* NOTE: Root-level CSS rules are NOT auto-wrapped when &&
tokens are otherwise present */
color: blue;

);
// Generated CSS:
/*
.y2X1z3 {
background-color: #ccc;
padding: .5em 1em;
}
.y2X1z3 > strong {
color: #c00;
}
@media (min-width: 800px) {
.y2X1z3 {
background-color: #eee;
}
}
/ NOTE: Root-level CSS rules are NOT auto-wrapped when && tokens are otherwise present ​/
color: blue;
*/

// ---------------------------------------------------------------------------

// 3) Advanced use: Pass a function to get the raw generated class-name,
// plus a more convenient dot-prefixed selector for the class-name.
export const myOtherClass = vanillaClass(
(classNameRaw, classNameSelector) =>
${classNameSelector} {
background-color: #ccc;
padding: .5em 1em;
}
[class="${classNameRaw}"] > strong {
color: #c00;
}
@media (min-width: 800px) {
${classNameSelector} {
background-color: #eee;
}
}
/ NOTE: '&&' tokens returned from a callback function are NOT replaced /
&& { this-is-not: interpolated; }

);
// Generated CSS:
/*
.y3z1X2 {
background-color: #ccc;
padding: .5em 1em;
}
[class="y3z1X2"] > strong {
color: #c00;
}
@media (min-width: 800px) {
.y3z1X2 {
background-color: #eee;
}
}
/ NOTE: '&&' tokens returned from a callback function are NOT replaced ​​/
&& { this-is-not: interpolated; }
*/

// ---------------------------------------------------------------------------

// 4) ...with a human readable debugId
export const humanReadableClass = vanillaClass(
'HumanReadable__classNamePrefix',

border: 1px dashed hotpink;
cursor: pointer;

);
// Generated CSS:
/*
.HumanReadable__classNamePrefix_x2y1z3 {
border: 1px dashed hotpink;
cursor: pointer;
}
*/
`

(NOTE: The dot-prefixed && pattern was chosen as to not conflict with the
bare & token in modern nested CSS.)

$3

Syntax: vanillaGlobal(css: string): void

Inserts free-form CSS as a vanilla-extract globalStyle.

`ts
// someFile.css.ts
import { vanillaGlobal } from '@reykjavik/webtools/vanillaExtract';

vanillaGlobal(
body {
background-color: rebeccapurple;
}
);
`

$3

Syntax: vanillaProps(css: string): GlobalStyleRule

Returns an object that can be safely spread into a vanilla-extract style
object, to inject free-form CSS properties (or nested blocks).

`ts
// someFile.css.ts
import { style } from '@vanilla-extract/css';
import { vanillaProps } from '@reykjavik/webtools/vanillaExtract';

const myStyle = style({
color: 'darksalmon',
// ...other style props...

...vanillaProps(
/ Plain CSS that's injected into the "myStyle" style block /
border-bottom: 1px solid red;
color: ${theme.color.primary}; / I can still use typesafe values /
random-css-prop-normally-rejected-by-vanilla-extract: 'YOLO!';
),
});
`

$3

Syntax:
vanillaVars(...varNames: Array): Record <var${Capitalize}, string>

Returns an object with privately scoped CSS variables props. Pass them around
and use them in your CSS.

`ts
// MyComponent.css.ts
import {
vanillaVars,
vanillaGlobal,
} from '@reykjavik/webtools/vanillaExtract';

const { varPrimaryColor, varSecondaryColor, setVars } = vanillaVars(
'primaryColor',
'secondaryColor'
);

export { varPrimaryColor, varSecondaryColor };

export const wrapper = vanillaClass(
${setVars({
primaryColor: '#ff0000',
secondaryColor: '#00ff00',
})}
background-color: var(${varPrimaryColor});
color: var(${varSecondaryColor});
);
`

…and then in your component:

`ts
// MyComponent.tsx
import React from 'react';
import * as cl from './someFile.css.ts';

export function MyComponent() {
return (
className={cl.wrapper}
style={{
[cl.varPrimaryColor]: 'yellow',
[cl.varSecondaryColor]: 'blue',
}}
>
...children...