Global

Members

(constant) DEFAULT_ACCEPT

Default Accept sent by the client: LINO first, JSON as a fallback.

Source:

(constant) DEFAULT_ALLOWED_HEADERS

Headers a browser must be allowed to send to negotiate Links Notation.

Source:

(constant) DEFAULT_EXPOSED_HEADERS

Headers a browser must be allowed to read to follow the protocol.

Source:

(constant) DEFAULT_LIMIT

Page size used when a request does not ask for one.

Source:

(constant) DEFAULT_MAX_BODY_BYTES

Largest request body accepted by default, in bytes.

Source:

(constant) DESCRIPTION_PATH

Where the native service description lives (specification §9).

Source:

(constant) HTTP_METHODS

Methods a handler can be registered for.

Source:

(constant) IMPLICIT_METHODS

Methods that never need to be registered explicitly.

Source:

(constant) JSON_CONTENT_TYPE

JSON fallback for clients that cannot speak Links Notation.

Source:

(constant) JSON_PROBLEM_CONTENT_TYPE

Media type of RFC 9457 problem details expressed as JSON.

Source:

(constant) LINO_API_DESCRIPTION_VERSION

Version of the description document this package emits.

Source:

(constant) LINO_COMPACT_CONTENT_TYPE

Type-tagged, base64 Links Notation that preserves object identity.

Source:

(constant) LINO_CONTENT_TYPE

Readable, indented Links Notation. The default representation.

Source:

(constant) LINO_LINE_CONTENT_TYPE

Readable Links Notation restricted to one line per value.

Source:

(constant) LINO_PROBLEM_CONTENT_TYPE

Problem details served as Links Notation.

Source:

(constant) MAX_LIMIT

Largest page a server will serve, whatever the request asks for.

Source:

(constant) OPENAPI_PATH

Where the generated OpenAPI 3.1 document lives (specification §9).

Source:

(constant) PROBLEM_BASE_MEDIA_TYPES

Representation each problem-details media type is encoded as.

Source:

(constant) PROBLEM_MEDIA_TYPES

Problem-details media type to use for each representation.

A 4xx served as text/lino is announced as application/problem+lino, which lets a client tell an error body from a successful one without parsing it.

Source:

(constant) PROBLEM_TYPE_BASE

Base URI every registered problem type is resolved against.

Source:

(constant) RESERVED_QUERY_PARAMETERS

Query parameters that are not field filters.

Source:

(constant) RESOURCE_OPERATIONS

Operations a resource can expose, in registration order.

Source:

(constant) SUPPORTED_MEDIA_TYPES :Array.<string>

Every representation a server produces, most preferred first.

Type:
  • Array.<string>
Source:

Methods

accepted(value, headersopt) → {LinoResult}

A 202 Accepted carrying a value.

Parameters:
Name Type Attributes Description
value *

Value to encode
headers object <optional>

Response headers
Source:
Returns:

Handler result

Type
LinoResult

appendVary(res, field) → {void}

Add a field name to Vary without repeating it.

Both content negotiation and CORS need to extend Vary; a plain res.set from either of them would silently drop the other one's contribution.

Parameters:
Name Type Description
res object

Express response
field string

Header field name to add
Source:
Returns:
Type
void

applyCollectionQuery(items, query) → {Object}

Run a parsed collection query against an in-memory list.

Parameters:
Name Type Description
items Array.<object>

Every item of the collection
query object

Query from parseCollectionQuery
Source:
Returns:

Collection envelope

Type
Object

buildQueryString(queryopt) → {string}

Build a query string from an object, expanding array values.

Parameters:
Name Type Attributes Description
query object <optional>

Query parameters
Source:
Returns:

Query string including ?, or an empty string

Type
string

collectionEnvelope(items, page) → {Object}

Wrap items in the collection envelope of the specification.

Parameters:
Name Type Description
items Array.<object>

Items of this page
page Object

Page metadata
Source:
Returns:

Collection envelope

Type
Object

compareValues(left, right) → {number}

Compare two values in a total order that works across LINO scalar types.

Parameters:
Name Type Description
left *

First value
right *

Second value
Source:
Returns:

Negative, zero or positive

Type
number

compilePathPattern(pattern) → {RegExp}

Compile an Express-style path pattern into a matcher.

Supports :param segments and a trailing * wildcard, which is the subset the registry needs in order to answer "does any route own this path?".

Parameters:
Name Type Description
pattern string

Path pattern
Source:
Returns:

Matcher anchored to the whole path

Type
RegExp

computeETag(body) → {string}

Compute the strong entity tag of an encoded representation.

Parameters:
Name Type Description
body string

Encoded representation
Source:
Returns:

Quoted hexadecimal SHA-256

Type
string

corsHeaders(optionsopt, requestOriginopt) → {object}

Build the CORS response headers for a request.

Parameters:
Name Type Attributes Description
options object <optional>

Policy

Properties
Name Type Attributes Description
origin string | Array.<string> <optional>

Allowed origin(s), "*" by default
methods Array.<string> <optional>

Allowed methods
allowedHeaders Array.<string> <optional>

Allowed request headers
exposedHeaders Array.<string> <optional>

Response headers exposed to scripts
credentials boolean <optional>

Allow credentialed requests
maxAge number <optional>

Preflight cache lifetime in seconds
requestOrigin string <optional>

Origin header of the request
Source:
Returns:

Response headers

Type
object

createLinoApp(optionsopt) → {LinoApp}

Create a new application.

Parameters:
Name Type Attributes Description
options object <optional>

Application options, see LinoApp
Source:
Returns:

New application

Type
LinoApp

createLinoClient(baseUrl, optionsopt) → {LinoClient}

Create a client.

Parameters:
Name Type Attributes Description
baseUrl string

Base URL of the service
options object <optional>

Client options, see LinoClient
Source:
Returns:

New client

Type
LinoClient

created(value, location, headersopt) → {LinoResult}

A 201 Created carrying a value and a Location.

Parameters:
Name Type Attributes Description
value *

Value to encode
location string

URI of the created resource
headers object <optional>

Additional response headers
Source:
Returns:

Handler result

Type
LinoResult

decode(notation) → {*}

Decode readable or compact Links Notation into a JavaScript value.

Parameters:
Name Type Description
notation string

Links Notation document
Source:
Returns:

Decoded value

Type
*

decodeFrom(body, mediaType) → {*}

Decode a representation of a concrete media type.

Parameters:
Name Type Description
body string

Raw request or response body
mediaType string

Media type the body was sent with
Source:
Throws:

When the media type is not a representation of this API

Type
TypeError
Returns:

Decoded value

Type
*

decodeSingleLine(notation) → {*}

Decode one line of single-line readable Links Notation.

Parameters:
Name Type Description
notation string

One line of readable Links Notation
Source:
Returns:

Decoded value

Type
*

encode(value) → {string}

Encode a value as readable, indented Links Notation.

Parameters:
Name Type Description
value *

Value to encode
Source:
Returns:

Readable Links Notation

Type
string

encodeCompactNotation(value) → {string}

Encode a value as compact, type-tagged Links Notation.

This is the only representation that preserves shared object identity and circular references.

Parameters:
Name Type Description
value *

Value to encode
Source:
Returns:

Compact Links Notation

Type
string

encodeFor(value, mediaType) → {string}

Encode a value for a concrete media type.

Parameters:
Name Type Description
value *

Value to encode
mediaType string

One of the media types of the specification
Source:
Throws:

When the media type is not a representation of this API

Type
TypeError
Returns:

Encoded representation

Type
string

encodeSingleLine(value) → {string}

Encode a value as single-line readable Links Notation.

Parameters:
Name Type Description
value *

Value to encode
Source:
Returns:

One line of readable Links Notation

Type
string

etagMatches(headerValueopt, currentETag) → {boolean}

Test whether an entity tag list matches the current tag.

Parameters:
Name Type Attributes Description
headerValue string <optional>

Raw If-Match / If-None-Match value
currentETag string

Entity tag of the current representation
Source:
Returns:

True when the list matches

Type
boolean

evaluatePreconditions(headers, method, currentETag, optionsopt) → {Object}

Evaluate the conditional request headers of a request.

Parameters:
Name Type Attributes Description
headers object

Request headers, lower-cased names
method string

HTTP method
currentETag string

Entity tag of the current representation
options object <optional>

Behaviour switches

Properties
Name Type Attributes Description
requirePrecondition boolean <optional>

Demand If-Match on unsafe methods
Source:
Throws:

412 on a failed If-Match, 428 when one is required

Type
LinoHttpError
Returns:

Whether the response should be 304

Type
Object

infoObject(info) → {object}

Render the info member shared by both description documents.

Parameters:
Name Type Description
info object

title, version and optional description of the service
Source:
Returns:

Info object, carrying description only when one was given

Type
object

isDecodableMediaType(mediaType) → {boolean}

Test whether a request body media type can be decoded.

Parameters:
Name Type Description
mediaType string

Bare media type of the request body
Source:
Returns:

True when the body can be decoded

Type
boolean

linoBodyParser(optionsopt) → {function}

Body parser middleware for every media type of the specification.

Decoded bodies are exposed as req.body; the media type they arrived in is exposed as req.linoRequestMediaType.

Parameters:
Name Type Attributes Description
options object <optional>

Limits

Properties
Name Type Attributes Description
maxBodyBytes number <optional>

Largest accepted body
Source:
Returns:

Express middleware

Type
function

linoCors(optionsopt) → {function}

Express middleware applying a CORS policy and answering preflight requests.

Parameters:
Name Type Attributes Description
options object <optional>

Policy, see corsHeaders
Source:
Returns:

Express middleware

Type
function

linoErrorHandler(optionsopt) → {function}

Terminal error handler turning any thrown value into problem details.

Parameters:
Name Type Attributes Description
options object <optional>

Behaviour switches

Properties
Name Type Attributes Description
exposeStack boolean <optional>

Attach the stack trace to 5xx problems
Source:
Returns:

Express error middleware

Type
function

linoMiddleware(optionsopt) → {Array.<function()>}

The full request pipeline: negotiation followed by body decoding.

Parameters:
Name Type Attributes Description
options object <optional>

Options forwarded to the individual middleware
Source:
Returns:

Express middleware chain

Type
Array.<function()>

linoNegotiation(optionsopt) → {function}

Content negotiation middleware.

Stores the selected representation on req.linoMediaType and installs the res.lino(...) and res.problem(...) helpers.

Parameters:
Name Type Attributes Description
options object <optional>

Negotiation policy

Properties
Name Type Attributes Description
supported Array.<string> <optional>

Representations the server can produce
Source:
Returns:

Express middleware

Type
function

linoResponse(res, value, statusCodeopt) → {object}

Send a value as Links Notation without the negotiation middleware.

Parameters:
Name Type Attributes Description
res object

Express response
value *

Value to encode
statusCode number <optional>

HTTP status code
Source:
Returns:

The Express response

Type
object

matchesFilters(item, filters) → {boolean}

Test whether an item satisfies every filter.

A filter whose value is a list matches when the item field equals any member, which is what repeated query parameters (?tag=a&tag=b) mean.

Parameters:
Name Type Description
item object

Candidate item
filters object

Field filters
Source:
Returns:

True when the item matches

Type
boolean

negotiateMediaType(acceptHeaderopt, supportedopt) → {string|null}

Select the representation to produce for a request.

Parameters:
Name Type Attributes Description
acceptHeader string <optional>

Raw Accept header value
supported Array.<string> <optional>

Representations the server can produce
Source:
Returns:

Selected media type, or null when none is acceptable

Type
string | null

noContent(headersopt) → {LinoResult}

A 204 No Content.

Parameters:
Name Type Attributes Description
headers object <optional>

Response headers
Source:
Returns:

Handler result

Type
LinoResult

normalizeMediaType(mediaType) → {string}

Resolve a media type to the representation it is encoded as.

Problem-details types carry the same syntax as their base representation, so they decode with the same codec.

Parameters:
Name Type Description
mediaType string

Bare media type
Source:
Returns:

Representation media type

Type
string

notFound(name, id) → {LinoHttpError}

Build the 404 raised when an item does not exist.

Parameters:
Name Type Description
name string

Human readable resource name
id *

Identifier that was looked up
Source:
Returns:

Problem to throw

Type
LinoHttpError

ok(value, headersopt) → {LinoResult}

A 200 OK carrying a value.

Parameters:
Name Type Attributes Description
value *

Value to encode
headers object <optional>

Response headers
Source:
Returns:

Handler result

Type
LinoResult

openApiDocument(info, routes, mediaTypesopt) → {object}

Build an OpenAPI 3.1 document describing the service.

Every request and response body is declared for all negotiable media types, so that a generated client knows it may ask for text/lino.

Parameters:
Name Type Attributes Description
info object

title, version and optional description of the service
routes Array.<{path: string, methods: Array.<string>, summary: string}>

Route descriptions
mediaTypes Array.<string> <optional>

Representations the service can produce
Source:
Returns:

OpenAPI 3.1 document

Type
object

paginationLinkHeader(path, query, page) → {string}

Build the RFC 8288 Link header value for a paginated collection.

Parameters:
Name Type Description
path string

Request path without a query string
query object

Original query parameters
page Object

Page metadata
Source:
Returns:

Link header value ("" when there is nothing to link to)

Type
string

parseAccept(headerValueopt) → {Array.<{type: string, quality: number, specificity: number}>}

Parse an Accept header into ranges ordered by preference.

Parameters:
Name Type Attributes Description
headerValue string <optional>

Raw Accept header value
Source:
Returns:

Ordered ranges

Type
Array.<{type: string, quality: number, specificity: number}>

parseBoundedInteger(raw, fallback, name, maximumopt) → {number}

Parse a bounded non-negative integer query parameter.

Parameters:
Name Type Attributes Description
raw string | undefined

Raw query parameter value
fallback number

Value used when the parameter is absent
name string

Parameter name, used in the error detail
maximum number <optional>

Largest accepted value
Source:
Throws:

400 when the value is not a non-negative integer

Type
LinoHttpError
Returns:

Parsed value

Type
number

parseCollectionQuery(query, optionsopt) → {Object}

Parse a full collection query from request query parameters.

Parameters:
Name Type Attributes Description
query object

Request query parameters
options object <optional>

Limits

Properties
Name Type Attributes Description
defaultLimit number <optional>

Page size when unspecified
maxLimit number <optional>

Largest accepted page size
Source:
Returns:

Parsed query

Type
Object

parseContentType(headerValueopt) → {string}

Strip parameters and normalise case, turning a header value into a media type.

Parameters:
Name Type Attributes Description
headerValue string <optional>

Raw Content-Type header value
Source:
Returns:

Bare, lower-cased media type ("" when absent)

Type
string

parseETagList(headerValueopt) → {Array.<string>}

Split an If-Match or If-None-Match header into entity tags.

Parameters:
Name Type Attributes Description
headerValue string <optional>

Raw header value
Source:
Returns:

Entity tags, with any weak prefix removed

Type
Array.<string>

parseFields(raw) → {Array.<string>|null}

Parse a fields parameter into a sparse fieldset.

Parameters:
Name Type Description
raw string | undefined

Raw fields value
Source:
Returns:

Field names, or null when every field is requested

Type
Array.<string> | null

parseScalar(raw) → {*}

Parse a filter value with the LINO scalar rules.

?done=true filters on the boolean, ?id=7 on the integer, and anything else stays a string.

Parameters:
Name Type Description
raw string

Raw query parameter value
Source:
Returns:

Parsed scalar

Type
*

parseSort(raw) → {Array.<{field: string, descending: boolean}>}

Parse a sort parameter into ordered sort keys.

Parameters:
Name Type Description
raw string | undefined

Raw sort value
Source:
Returns:

Sort keys

Type
Array.<{field: string, descending: boolean}>

pathParameters(path) → {Array.<string>}

Extract the path parameters of an Express-style path.

Parameters:
Name Type Description
path string

Path pattern
Source:
Returns:

Parameter names

Type
Array.<string>

problemDetails(status, detailopt, optionsopt) → {object}

Build problem details for a status code without throwing.

Parameters:
Name Type Attributes Description
status number

HTTP status code
detail string <optional>

Human readable explanation
options object <optional>

Additional problem members, see LinoHttpError
Source:
Returns:

Problem details ready to be encoded

Type
object

problemMediaType(mediaType) → {string}

Problem-details media type matching a representation.

Parameters:
Name Type Description
mediaType string

Representation media type
Source:
Returns:

Media type to announce for problem details

Type
string

problemSlug(title) → {string}

Kebab-case slug used as the last segment of a problem type URI.

Parameters:
Name Type Description
title string

Problem title
Source:
Returns:

Slug

Type
string

projectFields(item, fields) → {object}

Reduce an item to a sparse fieldset.

Parameters:
Name Type Description
item object

Item to project
fields Array.<string> | null

Field names, or null for every field
Source:
Returns:

Projected item

Type
object

rangeMatches(range, mediaType) → {boolean}

Test whether an Accept range matches a concrete media type.

Parameters:
Name Type Description
range string

Range from an Accept header
mediaType string

Concrete media type
Source:
Returns:

True when the range covers the media type

Type
boolean

readBody(req, maxBytes) → {Promise.<string>}

Read a request body as a UTF-8 string, refusing oversized payloads.

Parameters:
Name Type Description
req object

Express request
maxBytes number

Largest accepted body
Source:
Returns:

Raw body

Type
Promise.<string>

reasonPhrase(status) → {string}

Reason phrase of a status code, falling back to a generic class phrase.

Parameters:
Name Type Description
status number

HTTP status code
Source:
Returns:

Human readable reason phrase

Type
string

registerResource(app, basePath, store, optionsopt) → {object}

Register the routes of a CRUD resource on an application.

Parameters:
Name Type Attributes Description
app object

LinoApp to register on
basePath string

Collection path, for example /items
store object

Store implementing list, get, create, update, patch and remove
options object <optional>

Resource options

Properties
Name Type Attributes Description
idParam string <optional>

Path parameter holding the identifier
idField string <optional>

Field of an item holding the identifier
name string <optional>

Human readable name used in problem details
operations Array.<string> <optional>

Subset of RESOURCE_OPERATIONS to expose
requirePrecondition boolean <optional>

Demand If-Match on PUT, PATCH and DELETE
upsert boolean <optional>

Let PUT create a missing item
defaultLimit number <optional>

Page size when unspecified
maxLimit number <optional>

Largest accepted page size
Source:
Returns:

The application, for chaining

Type
object

representationETag(req, value) → {string}

Entity tag of a value in the representation the client asked for.

Entity tags are per representation, which is why the negotiated media type is part of the computation and why every response carries Vary: Accept.

Parameters:
Name Type Description
req object

Express request
value *

Value to tag
Source:
Returns:

Quoted entity tag

Type
string

requireBody(req) → {object}

Require a decoded request body.

Parameters:
Name Type Description
req object

Express request
Source:
Throws:

400 when the body is missing

Type
LinoHttpError
Returns:

The body

Type
object

sendProblem(req, res, error) → {object}

Write problem details for an error onto a response.

Parameters:
Name Type Description
req object

Express request
res object

Express response
error *

Thrown value
Source:
Returns:

The Express response

Type
object

serviceDescription(info, routes, mediaTypesopt) → {object}

Build the native service description.

Parameters:
Name Type Attributes Description
info object

title, version and optional description of the service
routes Array.<{path: string, methods: Array.<string>, summary: string}>

Route descriptions
mediaTypes Array.<string> <optional>

Representations the service can produce
Source:
Returns:

Description ready to be encoded as Links Notation

Type
object

sortItems(items, sort) → {Array.<object>}

Sort items by the sort keys of a collection query.

Parameters:
Name Type Description
items Array.<object>

Items to sort (not mutated)
sort Array.<{field: string, descending: boolean}>

Sort keys
Source:
Returns:

Sorted copy

Type
Array.<object>

status(statusCode, valueopt, headersopt) → {LinoResult}

A response with an explicit status code.

Parameters:
Name Type Attributes Description
statusCode number

HTTP status code
value * <optional>

Value to encode
headers object <optional>

Response headers
Source:
Returns:

Handler result

Type
LinoResult

toEnvelope(result, query) → {Object}

Normalise whatever a store's list returned into a collection envelope.

Parameters:
Name Type Description
result *

Array of items, or an envelope
query object

Parsed collection query
Source:
Returns:

Collection envelope

Type
Object

toHttpError(error) → {LinoHttpError}

Turn any thrown value into a LinoHttpError.

Errors that are already problem-shaped keep their status and details; anything else becomes a 500 whose detail is the original message.

Parameters:
Name Type Description
error *

Thrown value
Source:
Returns:

Normalised error

Type
LinoHttpError

toOpenApiPath(path) → {string}

Convert an Express-style path to the OpenAPI template syntax.

Parameters:
Name Type Description
path string

Path pattern with :param segments
Source:
Returns:

Path template with {param} segments

Type
string

validationError(errors, detailopt) → {LinoHttpError}

A 422 carrying field-level validation failures.

Parameters:
Name Type Attributes Description
errors Array.<{field: string, message: string}>

Field failures
detail string <optional>

Human readable explanation
Source:
Returns:

Error ready to be thrown

Type
LinoHttpError

withCharset(mediaType) → {string}

Add charset=utf-8 to a media type so that bytes are unambiguous.

Parameters:
Name Type Description
mediaType string

Bare media type
Source:
Returns:

Media type with an explicit charset

Type
string