ScrewtopDB API Reference

A name is not a key. Several distinct topic nodes may carry the same name, and
`topicByName` returns every one of them the caller can see -- each with its own
`topicId`. That is what instancing means in v2: identity is the node id, not an
ordinal.

Mint a distinct node by passing a spec with `instance: 'new'`. Both arities work,
and every key in the spec other than `text` and `instance` becomes a tag on the
new node:

db().addTopics({ text: 'blog-article', instance: 'new', status: 'draft' }).end();
db().addTopics({ text: 'blog-article', instance: 'new' }, 'status', 'draft').end();

Capture the returned `topicId` -- it is the only durable handle to that node:

db().addTopics({ text: 'blog-article', instance: 'new' }, 'status', 'draft')
.fn(function(ts) { articleId = ts[0].topicId; })
.end();

Read one node with `topicById(articleId)`, or narrow the by-name set with the
`hasTag` option -- `topicByName('blog-article', { hasTag: 'items' })` keeps only
the nodes carrying that tag, which is the usual way to pick the container out of a
set of same-named nodes. Delete one node with `deleteTopics(articleId)`.

Writes by an ambiguous name are refused rather than guessed: once a name has more
than one node, `addTopics('blog-article', tag, value)` is rejected. Pin the write
with the id instead -- `addTopics(articleId, tag, value)`.

There are no instance NUMBERS. The v1 model -- instance 0 as a shared public copy,
1 and higher as per-user copies, numbered monotonically and never reused -- went
away with the v1 engine, and with it the `instance` option, topicByNameAndInstance,
deleteInstance, and GET/DELETE /:app/instances.json/:text/:instance. The
`apiVersion` option is accepted and ignored, because the behaviour it used to
select is now unconditional.

The **via** option turns a reader step (topicByName, topicById, findTopics) into a multi-level graph traversal. Each hop follows tag values to the referenced topics, optionally filtering along the way. The result set is replaced by the topics reached at the final hop.

**Shapes:**
- **String**: `via: "friends"` — a single outbound hop on the tag named "friends" (the whole string is one tag name; it is NOT split on dots).
- **Object**: `via: { tag: "friends", with: { age: { $gt: 18 } } }` — single hop with a filter.
- **Array**: `via: [{ tag: "friends" }, { tag: "employer", with: { region: "US" } }]` — explicit multi-hop list.
- **Inbound**: add `inbound: true` to a hop to traverse the reverse edge ("who references this topic?"): `via: { tag: "friends", inbound: true }`.

**Filtering with `with`:** a hop may carry a `with` object that keeps only destinations matching the given outbound tag:value pairs. Keys AND together. The filter key is `with` (NOT `filter`). Per-value operators:
- plain string — exact match
- `$not: X` — negation
- `$contains: "X"` — substring match
- `$gt` / `$gte` / `$lt` / `$lte: "X"` — comparison (numeric or lexicographic)
- `$none: X` — passes only when NO value on the tag matches X
- `$or: [ { tag: val }, ... ]` — OR across AND-clauses

**Returning edge values (`as: "values"`):** add `as: "values"` to the FINAL hop to return the traversed edge’s values instead of the destination topics.

**Shaping the result (`include`):** the `include` option applies only to the TERMINAL topics; intermediate hops always carry a full include so `with` filters can see every edge. `include` accepts CSV ("inbound,outbound") or an array (["inbound","outbound"]).

See also the related option **recursevia** for unbounded recursive traversal of a single tag name.

Set or get the application ID to be used in subsequent query sequence steps.

ScrewtopDB applications have both a name and an ID. The application's creator specifies the application name
when the app is created with the ScrewtopDB Application Dashboard.
The app ID is assigned by the ScrewtopDB software. Retrieval by ID is slightly more efficient than
retrieval by name.

Set or get the application name to be used in subsequent query sequence steps.

ScrewtopDB applications have both a name and an ID. The application's creator specifies the application name
when the app is created with the ScrewtopDB Application Dashboard.
The app ID is assigned by the ScrewtopDB software. Retrieval by ID is slightly more efficient than
retrieval by name.

Set authentication information for use in later server interactions

Users must always log in to add or make changes to application database contents. Depending on
options set for the application, logging in may also be necessary to read database contents.

Authentication information is sent in plaintext and the session identifier assigned to the session
is afterward included in all requests. Thus, only secure connections (those starting with https://)
should be used for authenticated sessions. (This is the default for both authenticated and unauthenticated
requests, so generally you needn't be concerned unless you have specified an alternate URL for interaction
with ScrewtopDb.)

Note that when authentication information is set using this method, session timeouts are disabled.

This is an alternative to the login method. No server communication is performed by this method.
Use authentication when you know the user's credentials are valid to avoid an unnecessary server
interaction. Use login when it is necessary to confirm the validity of the user's credentials immediately,
or a session timeout must be set, or an app login is desired.

Authenticate a user and create a session for further interaction.

Users must be authenticated to add or make changes to application database contents. Depending on
options set for the application, logging in may also be necessary to read database contents.

Authentication information is sent in plaintext and the session identifier assigned to the session
is afterward included in all requests. Thus, only secure connections (those starting with https://)
should be used for authenticated sessions. (This is the default for both authenticated and unauthenticated
requests, so generally you needn't be concerned unless you have specified an alternate URL for interaction
with ScrewtopDb.)

End a ScrewtopDb session

Manually set the current session state from a previously obtained session object, bypassing the
normal login flow.

Sets the sessionId, appId, appName, username, userTopicId, and version from the provided session object.
Clears the password.

Set the API version number used for subsequent requests.

Updates the version at both the chain-local and global level. The version affects version-dependent
behavior such as tag text matching (e.g. how `./` and `../` prefixes are expanded).

Add tag and value to each of the topics in the current result set.

Add a new topic to the screwtopDb database.

If the topic already exists, the tags and values are merged into the existing topic.

Atomically increase a numeric value.

The single value (or the first value if the tag contains multiple values) in the specified tag within
the specified topic is increased by a specified amount in a single operation, eliminating the possibility of a buried update.

The updated value is returned.

If the tag does not exist, it and the value (set to one) are created and the increase amount is returned.

The returned object replaces the current result set.

Add a value to each of the tags in the current result set.

Create or update a value.

Update the text of a value if it exists. Create the value (and topic and tag if necessary) if it does not exist.
This method cane be used to maintain a single value in a topic's tag, creating the topic and/or tag if necessary
the first time it is invoked, eliminating the need to first check if a value exists before attempting to update
it.

This method does not update the local cache. Thus, invalidation of the cache is necessary if the new value is
to be retrieved after an update using this method. The updateValue method might be a
better choice in this case.

This method does not alter the result set.

Atomically decrement a numeric value.

The single value (or the first value if the tag contains multiple values) in the specified tag within
the specified topic is decremented in a single operation, eliminating the possibility of a buried update.

The value is not allowed to fall below zero.

The updated value is returned. If the value was zero before the attempt to decrement it, the value is unchanged,
but -1 is returned to indicate that no actual decrement of the value occurred.

If the tag does not exist, it and the value (set to zero) are created and -1 is returned.

The returned object replaces the current result set.

REMOVED in v2, along with the instance numbers it took. The method is still on the
chain, and its result-set form still looks for `topic.instance`, but v2 frames carry
no such field and the server answers DELETE /:app/instances.json/:text/:instance
with HTTP 409 -- so the call silently does nothing.

Delete one node with `deleteTopics(topicId)`. `topicByName(name)`, optionally with
`hasTag`, enumerates the ids. See Topic Instancing (concept).

Delete tags in the result set from the ScrewtopDB database

Tags are deleted using a cascade delete operation. This means that the tag and all the
values contained in the tags are deleted. Then any topics
named by the deleted values are deleted if they contain no inbound tags (i.e. they are not referenced
by any remaining topic.) This process continues until there are no unreferenced topics left that were
reachable via outbound tags from the starting topics.

If you want to retain topics referenced only by topics you intend to delete, add a tag to a topic that
will not be deleted with a value referring to the topic you wish to retain. Often, the user topic is a
convenient topic in which to place such a tag.

Topics will not be deleted if they contain a tag owned by a user other than the deleting user. Instead,
all tags owned by the deleting user will be deleted from the topic. An exception to this rule is made for
unique topics. Unique topics owned by the deleting user are deleted regardless of whether they contain
tags owned by another user.

Note that if you delete all the tags of a topic, the topic will automatically be deleted as well.

The argument may also be a FUNCTION returning an id or an array of ids. Chain
arguments are evaluated when the chain is BUILT, so an id captured by an earlier
`.fn()` in the same chain is still undefined by the time a plain argument is read;
a function is called when the step RUNS, which is when the id exists. A function
that returns nothing deletes nothing.

Delete topics in the result set from the ScrewtopDB database

Topics are deleted using a cascade delete operation. This means that the topics, all the
tags contained in the topics, and all the values contained in the tags are deleted. Then any topics
named by the deleted values are deleted if they contain no inbound tags (i.e. they are not referenced
by any remaining topic.) This process continues until there are no unreferenced topics left that were
reachable via outbound tags from the starting topics.

If you want to retain topics referenced only by topics you intend to delete, add a tag to a topic that
will not be deleted with a value referring to the topic you wish to retain. Often, the user topic is a
convenient topic in which to place such a tag.

Topics will not be deleted if they contain a tag owned by a user other than the deleting user. Instead,
all tags owned by the deleting user will be deleted from the topic. An exception to this rule is made for
unique topics. Unique topics owned by the deleting user are deleted regardless of whether they contain
tags owned by another user.

With no `topicIds` argument the ids come from the result set: each element
contributes its `topicId`, and an element that IS a bare topic id (a ULID, as
left by `.fn(function(ts) { return ts[0].topicId; })`) is taken as that id --
the same address form the `topicIds` argument accepts. Elements carrying no
topic id contribute nothing, so a result set holding tags, values or plain
strings deletes nothing rather than issuing a delete for a missing id.

The argument may also be a FUNCTION returning an id or an array of ids. Chain
arguments are evaluated when the chain is BUILT, so an id captured by an earlier
`.fn()` in the same chain is still undefined by the time a plain argument is read;
a function is called when the step RUNS, which is when the id exists. A function
that returns nothing deletes nothing.

Delete values in the result set from the ScrewtopDB database

Values are deleted using a cascade delete operation. This means that the
values are deleted and then any topics
named by the deleted values are deleted if they contain no inbound tags (i.e. they are not referenced
by any remaining topic.) This process continues until there are no unreferenced topics left that were
reachable via outbound tags from the starting topics.

If you want to retain topics referenced only by topics you intend to delete, add a tag to a topic that
will not be deleted with a value referring to the topic you wish to retain. Often, the user topic is a
convenient topic in which to place such a tag.

Topics will not be deleted if they contain a tag owned by a user other than the deleting user. Instead,
all tags owned by the deleting user will be deleted from the topic. An exception to this rule is made for
unique topics. Unique topics owned by the deleting user are deleted regardless of whether they contain
tags owned by another user.

Note that if you delete all the values of a tag, the tag will automatically be deleted as well.

The current result set is unaffected by this method.

Fetch topics whose name matches a regular expression -- not a shell glob. The pattern matches anywhere in the name, so 'milk' finds 'shopping milk list'; anchor it with ^ and/or $ to pin the match to the start or end of the name. Note that 'user:*' is NOT a glob: read as a regex it means "user" followed by zero or more colons, so it matches every name containing "user" -- write '^user:' instead.

The topics fetched are passed to the following query sequence step as an array. If no topics were
found, an empty array is passed.

This function will initiate a request to the ScrewtopDB server regardless of whether the topics are already in cache.

List topics that carry a specific tag:value combination. Returns an array of stub
objects {text, topicInstance, topicId} -- one per source topic node that has
tagName=valueText. Follow up with topicById(topicId) for the full topic. The
`topicInstance` field is a v1 vestige and is always 0 in v2; `topicId` is the handle
that actually addresses the node.

Use this instead of findTopics(regex) when you want "topics where tag = value" (the
schema-correct enumeration). findTopics(regex) is a substring/regex search of topic
names with a default page size of 100 -- a different operation. Implemented by
walking the inbound tagName slot on the topic named valueText, so it is correct even
when several distinct nodes share the source name.

Trigger a full (re)build of the native FTS index for the current app. Issues POST `/:app/fts.json`.
Result set becomes `[{ count, durationMs }]`. Usually only needed the first time FTS is used against an
app, or after a mass import that bypassed the normal topic-creation path.

Run a native full-text search over the current app's topics. The result set is replaced with an array of hit
objects of the form `{ topic_id, topicId, text, rank }`, which composes directly with
topics or topicById to fetch the full topic records.

Uses the server's LevelDB-backed FTS5 index. The index is maintained incrementally as topics/tags/values are
added or modified. If the index is missing or stale for an app, call ftsBuildIndex
first. Check availability with ftsStatus.

Report whether the native FTS index is available for the current app, and summarize corpus statistics. The result
set is replaced with a single-element array `[{ available, N, dlSum, loaded, impl }]` where
`N` is the document count and `dlSum` is the total token count.

Atomically increment a numeric value.

The single value (or the first value if the tag contains multiple values) in the specified tag within
the specified topic is incremented in a single operation, eliminating the possibility of a buried update.

The updated value is returned.

If the tag does not exist, it and the value (set to one) are created and 1 is returned.

The returned object replaces the current result set.

Relocate a tag within its topic's tag list.

Moving is a modification: the caller must be allowed to modify the topic (its owner, an ACL grant, the app's responsible user, or the super-admin) or must own the tag being moved. Otherwise the server refuses with 403.

This method replaces the current result set with the updated topic.

Note that this method is ineffective in deferredWrite mode.

Relocate a value within its tag's value list.

Moving is a modification: the caller must be allowed to modify the value (its owner, an ACL grant, the app's responsible user, or the super-admin) or must own the tag it is in. Otherwise the server refuses with 403.

This method replaces the current result set with the updated topic.

Note that this method is ineffective in deferredWrite mode.

Publish an arbitrary payload to all SSE subscribers of a given notificationId within the current app. Use this to
fan out application-level events (not bound to topic changes) to connected clients.

Atomically set a numeric value.

The single value (or the first value if the tag contains multiple values) in the specified tag within
the specified topic is set to the value specified in a single operation, eliminating the possibility of a buried update.

The updated value is returned.

If the tag does not exist, it and the value (set to one) are created and the specified value is returned.

The returned object replaces the current result set.

Atomically decrease a numeric value.

The single value (or the first value if the tag contains multiple values) in the specified tag within
the specified topic is decreased by a specified amount in a single operation, eliminating the possibility of a buried update.

The updated value is returned.

If the tag does not exist, it and the value (set to one) are created and the negative amount is returned.

The returned object replaces the current result set.

Fetch a topic given its ID.

This step passes its result set (an array of topic objects) to the next step.
Typically, there will be zero or one element in the array.

An options object may be included that specifies any combination of the following options:

- **include** - Specify any combination of: "outbound" to include outbound tags, "inbound" to include inbound tags, "allTopics"
to include all topics containing the topicText parameter as a tag, and "allValues" to include all values in tags named with
the topicText parameter. The default is "outbound".

- **via** - Multi-level graph traversal. Either a string (e.g. `"friends.name"`) for simple hops, or an
object/array describing one or more hops with per-hop filters. Each hop may specify a tag name, filter expression, and
direction (`{ inbound: true }` for reverse-direction traversal). Filter expressions support the operators
`$eq`, `$contains`, `$not`, `$none`, `$gt`, `$lt`,
`$or`, `$and`, and `$regex`. The result set is replaced by the topics reached at the
final hop. See via option for full syntax.

- **recursevia** - Recursively adds topics to the result array (which would otherwise contain a single topic) that
are encountered by retrieving the topics of values found in tags matching the value of the recursevia option. Applies
only to outbound tags. (The legacy name `recurseVia` is also accepted.)

- **instance** - NOT IMPLEMENTED in v2, and will not be. It selected an instance by ORDINAL, a v1 model where
instance 0 was the shared public copy and 1+ were per-user copies. v2 instancing is identity-based rather than
ordinal: a distinct same-named node is minted with `instance:'new'` and addressed thereafter by its ULID. There is
no ordinal to select by; to read one specific instance, address it by id.

- **apiVersion** - Accepted and ignored by the v2 server, because the behaviour it selected is now unconditional: a
name resolves to EVERY node carrying it (topicByName hydrates each and returns them as a list), so a response
already describes all visible instances. There is no single-instance mode to fall back to. Expect `data` to be a
list; do not assume it holds exactly one topic, though for names never explicitly instanced it always will.

Ths function will initiate a request to the ScrewtopDB server if the topic requested is not in cache with the options
specified.

Fetch a topic given its name (i.e. its topicText).

The topic fetched is passed to the following query sequence step as a single element array. If the topic was not
found, an empty array is passed.

This function will initiate a request to the ScrewtopDB server if the topic requested is not in cache with the options
specified.

REMOVED in v2. It addressed an instance by ORDINAL, and ordinals no longer exist:
a name resolves to a set of distinct nodes identified by `topicId`, not to a
numbered series. The method is still on the chain, but the server answers
GET /:app/instances.json/:text/:instance with HTTP 409 and the call yields an
empty result set.

Use `topicById(topicId)` to fetch one specific node, or `topicByName(name)` for the
whole same-named set -- the `hasTag` option narrows that set to the nodes playing a
given role. See Topic Instancing (concept).

Add a query step to fetch the topics identified by the topicId properties of the current result set.

This step passes its result set (an array of values) to the next step.

The options parameter may specify one or more include specifications. The possible specifications are:

- **outbound** - These are the tags that were explicitly specified by the user who added the tag or created the topic.

- **inbound** - Inbound tags are the reverse of outbound tags. The values of the inbound tags of topic A are the topics
that contain an outbound tag containing a value referencing topic A.

- **allvalues** - The allvalues specification, when applied to a tag topic (i.e. the topic created for the tag when the
tag is first used), returns the tag named values whose value array contains all the values contained in the tag
in all topics in which it occurs.

- **alltopics** - The alltopics specification, when applied to a tag topic (i.e. the topic created automatically for
the tag when it is first used), returns in the topics tag all the topics that contain the tag.

Note that the parameters of this method are accepted in any order. This to allow either parameter to be included without requiring
the other.

Retract a prior vote on a topic

See userVotes for a description of voting in ScrewtopDb.

Users must be authenticated to unvote. A user can only retract their own votes. The existing vote type
must match the vote type specified in this method.

Modify a topic's text

Only unique topics and topics which have only tags owned by the authenticated user may be updated. Note that this includes
private topics as well.

Update the text of a value.

This method replaces the current result set with the updated value.

Return the user votes array.

Any ScrewtopDb topic may receive votes. A vote may be designated as up, down, or none.
These are designated as 1, 0, and -1 votes, respectively.
Separate counts are maintained for each vote type. A user may vote only once on a topic, but users may
retract their votes and cast a new vote if they wish.

Each user's votes are recorded in their votes user attribute. The attribute contains an array of arrays where the inner
array elements are the topicId and the vote type (-1, 0, or 1).

Each topic that has received votes includes a tally member that in turn contains the members up,
down, none, score, and, if the current user voted for the topic, a voted member.
The first three members are the integer counts of the vote type for that topic. The voted member indicates
how the current user voted on the topic, -1, 0, or 1.

The score member contains an integer between 0 and 10,000,000. It is calculated using the Wilson score
interval. (The lower bound value of which is normally between 0 and 1. The score value is obtained by multiplying the
lower bound by 10 million to allow integer math to be used.) This is intended to be used to sort voted topics for
display based on their relative up- and down-votes.

To include an age component in the score so that newer topics get higher scores than older topics,
divide the score by a value related to the age of the topic. (This is shown in the example.)

Fetch a value given its ID.

This step passes its result set (an array of topic objects) to the next step.
Typically, there will be zero or one element in the array.

An options object may be included that specifies any combination of the following options:

- **excludeValueText** True to exclude the value text from the response. The default is false.

Ths function always initiates a request to the ScrewtopDB server even if the topic requested is in cache.

Cast a vote on a topic

See userVotes for a description of voting in ScrewtopDb.

Users must be authenticated to vote.

Replace the result set with the collection or results returned when the supplied function is called
for each member of the current result set.

Replace the result set with the first match in the result set based on a supplied match string,
regular expression, or comparison function. If no match is found, the result is set to an empty array.

Eliminate duplicate elements in the current result set.

This is most useful when duplicate values have been returned from a topics()
request with options including "alltopics" or "allvalues" and the set of distinct topics or values
(i.e. no duplicates) is desired.

Filter the current result set to only items whose `.text` property ends with the given suffix.
The comparison is case-insensitive. Items whose text exactly equals the suffix (same length) are excluded;
the text must be strictly longer than the suffix.

Internally delegates to select with a predicate function.

Transform the current result set of topic objects into a single minimized plain-object representation.

For each topic that has tags, creates a key equal to the topic's text, whose value is an object mapping
tag text to arrays of value text strings. The result is a single-element array containing the minimized object.

Remove topics, tags, or values from the result set based on a supplied match string,
regular expression, or comparison function.

Select topics, tags, or values from the result set based on a supplied match string,
regular expression, or comparison function.

Replace the current result set with the provided value or array of values.

If `newValues` is an array, it is used directly as the new result set. Otherwise it is wrapped
in a single-element array.

Extract tags from the current result set that match a specified pattern.

The tagText argument may be one of the following:

- **owner/tagtext** - where owner is the usernamer of the tag owner and tagtext is the
text of the tag.

- **./tagtext** - ./ is replaced by the current logged-in user, if any, or the username
set as the default username with the options() method.

- **../tagtext** - ../ is replaced by the app name of the current application.

This step passes its result set (an array of tag objects) to the following step.
There will be zero or one element in the array.

Select the subset of the current query result set having text with a specified suffix.

This step passes its result set (an array of selected objects) to the next step.

Extract all tags from all topics in the current result set.

This step passes its result set (array of tag objects) to the following step.

Extract the values for a tag in the current result set given a tag text pattern.

This step passes its result set (an array of value objects) to the following step.
There will be zero or more elements in the array.

The tagText argument may be one of the following:

- **owner/tagtext** - where owner is the usernamer of the tag owner and tagtext is the
text of the tag.

- **./tagtext** - ./ is replaced by the current logged-in user, if any, or the username
set as the default username with the options() method.

- **../tagtext** - ../ is replaced by the app name of the current application.

Extract the values of the tags in the current result set.

This step passes its result set (an array of values) to the next step. If the current result set contains topics,
the values of all tags in all topics will be selected. If the current result set contains tags, then all the values
of all tags wiull be selected. If the current result set contains values, the result set will be
passed to the following step unchanged.

Invoke a user-supplied function for each element in the result set, passing the following arguments:

- The current result set element

- An environment object whose contents are retained across successive function calls. This
object can be used to accumulate information across function invocations.

- The zero-based integer index of the current result set element.

- The result set array

This method passes the input result set on to the following query sequence step unchanged (unless it is
modified by the user-supplied function.)

Invoke a user-supplied function that invokes a callback function, optionally passing to it
the current result set.

The function must expect the callback function as the last argument.

If arguments other than the function are provided, they are passed to the function before the
callback argument. If the string "RS" is passed as an argument, it is replaced by the
current result set when the function is invoked. A callback function is automatically
provided as the last argument.

If the callback function returns a result, the result replaces the current result set.

Select the first element of the result set and optionally pass it to a user-supplied function.

This step passes its result (an array of zero or one element) to the following step in the query sedquence.

Invoke a user-supplied function, passing to it the current result set.

If this function returns a result, the result replaces the current result set.

Perform an action if the result set contains one or more elements.

The actions that may be performed include stopping the currently executing query sequence, aborting all
query sequences, or invoking a user-supplied function.

Perform an action if the result set contains more than one element.

The actions that may be performed include stopping the currently executing query sequence, aborting all
query sequences, or invoking a user-supplied function.

Perform an action if the result set is empty.

The actions that may be performed include stopping the currently executing query sequence, aborting all
query sequences, or invoking a user-supplied function.

Perform an action if the result set contains one and only one element.

The actions that may be performed include stopping the currently executing query sequence, aborting all
query sequences, or invoking a user-supplied function.

Select the last element of the result set and optionally pass it to a user-supplied function.

This step passes its result (an array of zero or one element) to the following step in the query sequence.

Invoke a user-supplied function that returns a promise. Execute the next step when the promise is resolved.

If the promise returns a result, the result replaces the current result set.

The promise may contain a ScrewtopDB query sequence. In this case the end method typically calls the promise's
resolve callback.

Reverse the order of the elements in the current result set.

Sort the elements of the result set.

By default, the text members of the result set elements are sorted in ascending order. If the result set
contains strings, the strings are sorted in ascending order.

If a function argument is provided, the result of the function is used to sort the elements.

Extract the text properties from the current result set.

This step passes a new result set consisting of text strings to the following step.

Notes

- The order of arguments to this method is not enforced (i.e. the arguments may be passed in any order.)

- If the result set is an array of test strings, the strings are processed as if they were the values of text
properties.

Abort all query sequences in execution.

This method terminates execution of the current sequence, as well as any enclosing sequences. It does not
terminate execution of sequences initiated using the fork or go methods.

Send the sequence steps beginning with the next step to the server for execution.

The steps beginning with the next step and ending with the step before the next endServerExecution
are sent to the server for execution. The result is returned as if the sequence steps had been executed locally.

This facility is provided to allow avoiding passing large volumes of data back to the client for processing when that processing
could be executed on the server where no network traffic is generated.

Not all methods are candidates for execution on the server in this way. Only those methods that do not expect function arguments
may be executed on the server. Methods that produce console output such as log are, of course, useless for
debugging in server-side execution. The best way to prepare server-side sequences is to debug them in the client first.

Delay execution of the current query sequence for a specified number of milliseconds.

Execution of this method will allow other query sequences to execute, just as the method
waitForCompletion and requests to the server do.

Initiates execution of the query, beginning at the first step.

Note that a new query may be constructed and executed within a function invoked by methods including
each and func. When this occurs, the nested sequence's steps
are executed immediately. The parent is resumed after the sub-sequence has completed. The result set
of the parent query sequence is unaffected by the execution of any sub-sequences unless the argument to
this function is true or the function returns a value.

This method is the most common way to initiate query sequence execution.

Marks the end of sequence steps executed on the server.

See beginServerExecution.

Defer execution of a nested query sequence until the enclosing sequence has completed.

A seldom-used alternative to the end method.

Resume a query sequence whose execution was suspended with wait.

See wait for more information about the wait/resume feature.

Note that no other methods should be chained to the resume method, including end.

Note also that resume may be invoked on a screwtopDb sequence or on the screwtopDb object directly as
is done in the example below.

Send a pre-built chain expression (as a string) to the server's `/:app/scripts.json` endpoint for
execution in the server's own ScrewtopDB interpreter. The response data replaces the current result set.
Most apps should use the beginServerExecution / endServerExecution
pair instead — those build the script string automatically from the wrapped chain steps. Use serverExecute directly
only when you need to construct the script text yourself.

Suspend query sequence until resume is called.

This method allows you to suspend execution of a query sequence until the occurrence of an
external event. When the external event occurs (it might be a user-initiated event, a network
event, or a timeout) invoke the resume method to restart query execution.

Only one wait at a time is supported.

Wait for any parallel-executing query sequences to complete.

The function argument is invoked when there are no parallel query sequences
in execution except the caller.

Delete a previously saved context

This step passes the incoming result set unchanged to the following step.

Restore the last pushed result set from the stack without removing it from the stack.

Restore a previously saved session and result set.

Push the current result set onto the result set stack.

Restore a previously saved result set.

Restore a previously saved session.

Save session information and the current result set for later restoration.

This method is the equivalent of executing saveContext() and
saveSession() with the same index argument.

Save the current result set so that it can be restored in a later step.

This step passes the input result set unchanged to the following query sequence step.

Save session information for later restoration.

Session information includes the session identifier, the server URL, the application name,
the current username, and the contents of the in-memory client-side cache. (The session identifier
is assigned by the server after user authentication (i.e. a successful login.)

Note that this method does not save the current result set with the session information. If you wish to
save both, use save() instead.

Only a single session may be active at any time. You might want to change sessions dynamically
if you were, for example, copying information from one application to another or if you were copying
information from one user to another within an application.

Invoke a user-supplied function passing the current stack array as its single argument.

The array passed to the supplied function is not a copy of the stack, but the stack array itself. Thus
any changes made to it within the invoked function will persist after the function returns.

Invoke a user-supplied function that is passed a session information object.

The members of the returned object are

- sessionId - the session identifier assigned on login by the server

- url - the URL of the server. Normally https://www.screwtopdb.com

- appId - the application ID of the application

- appName - the application name

- username - the username of the currently logged-in user

If a login has not been performed, the session information object passed is undefined.

Add a topic to the local cache without "writing through" to the server.

Normally, unless offline, added topics are transmitted to the server and
the server response is used to update the cache, including the server-assigned
topic, tag, and value IDs. This method does not update the server, thus behaving
as if the client was offline.

Delete topics in the current result set from the local cache without "writing through" to the server.

Normally, unless offline, topic deletions are transmitted to the server and
the server response is used to update the cache. This method does not update
the server, thus behaving as if the client was offline.

Delete values in the current result set from the local cache without "writing through" to the server.

Normally, unless offline, value deletions are transmitted to the server and
the server response is used to update the cache. This method does not update
the server, thus behaving as if the client was offline.

Enable or disable caching of topics

By default, the ScrewtopDB Javascript library caches retrieved topics and thereafter if the same topic
is referenced again, it is retrieved from cache rather than requiring that another request
be sent to the server.

This function allows you to disable the caching feature. This might be desirable if, for example, you
are accessing a highly interactive application where ScrewtopDB topics are used to communicate between
multiple on-line clients.

Remove all entries from the local topic cache.

The ScrewtopDB Javascript library caches retrieved topics and thereafter if the same topic
is referenced again, it is retrieved from cache rather than requiring that another request
be sent to the server.

InvalidateCache is used when you want to be sure that you are using the server's copy of a
topic. This might be necessary if, for example, there are multiple clients accessing the
same topic simultaneously.

Call the provided function passing the current contents of the local in-memory cache.

This method is intended for debugging of the ScrewtopDb library and is not likely to
be generally useful. The web page ScrewtopDb Cache Demo
uses this method to display cache content changes in real time.

Call the provided function passing the current contents of the browser's local storage cache.

This method is intended for debugging of the ScrewtopDb library and is not likely to
be generally useful. The web page ScrewtopDb Cache Demo
uses this method to display cache content changes in real time.

Set the deferredWrite state or passes the current deferredWrite state to a function.

When deferredeWrite is **true** all ScrewtopDb write requests will update the local cache only; no
server communication will be attempted. Later invocation of the synchronize method
will update the server with the new and changed content of the local cache. Use of deferredWrite and
synchroinize allow disconnected operation of ScrewtoDb applications.

Delete a previously saved cache from the browser's local storage.

The in-memory cache is unaffected by this operation.

Restore a previously saved cache from the browser's local storage.

The cache is restored to the state it was in when it was saved. This is useful, for example, when
continuing a session across browser restarts when the user has been working off-line and was not
able to synchronize with the server database.

Set the off-line state or passes the current off-line state to a function.

An off-line state of **true** affects only the login
method and then only when deferredWrite is also true. When both are true, the login method
does not attempt to communicate with the server to authenticate the user, but instead assumes
login success and continues. This is done to allow applications that perform a login to operate
when not connected to the Internet.

Save the ScrewtopDb cache in the browser's local storage.

This is useful, for example, when the user is working off-line and was not able to
synchronize with the server database.

Synchronize the local in-memory cache with the server database.

During synchronization, differences between the server database content and the current in-memory cache
contents are resolved. Additions, modifications and deletions are propagated between the the two. If
a conflict arises, it is resolved by honoring the change with the later timestamp.

Synchronize is most useful when used in conjunction with deferredWrite(true).

Creates a real-time auto-rendering system for a topic. Returns the chain instance with two new methods attached:
`subscribe` and `unsubscribe`.

An autoRenderer manages subscribing to server-sent notifications for a topic. When events occur
(additions, deletions, modifications, re-ordering of values), the autoRenderer updates the local cache
and re-populates the data. On connection errors, it automatically reconnects with retry logic.

**subscribe(notifyId, topicText, tagPrefix, renderOptions, eventFn, fetchOptions)**

Subscribes to real-time notifications for a topic. After subscribing, performs an initial fetch
of the topic data (invalidating the cache first). On subsequent events (`add`,
`delete`, `update`, `move`, `ts`), updates the local
cache and calls the `cb` callback. If the connection is lost, unsubscribes, waits 2 seconds,
and re-subscribes automatically. The optional `eventFn` is called with raw event data after
each event is processed. The `fetchOptions` parameter defaults to `{elide:true}`.

**unsubscribe(notifyId)**

Unsubscribes from notifications for the given `notifyId`.

Populate DOM objects from a ScrewtopDb topic using jQuery's html() and val() functions.

The text of the topic's tags specify the DOM element IDs. The tag values contain the text to be
inserted using the html() or val() function. DOM element IDs are assumed to be prefixed with the topic
name followed by a dash. Here is an example ID: myform-newpassword. The topic is myform and the
tag might be <username>/newpassword.

The ScrewtopDB Application Dashboard is populated using this method.

Open a server-sent-events connection and re-render a topic into the DOM whenever the server broadcasts a change.
**subscribe** and unsubscribe are attached to a chain instance by
autoRenderer — they are not standalone chain steps. Browser-only (depends on
`EventSource`).

Close the SSE connection opened by an earlier subscribe call. Like subscribe, this is
attached by autoRenderer.

Invoke a specified function when an error occurs.

By default errors are logged and query sequence execution is terminated when an error occurs. This function allows you to
specify additional actions to be executed when an error occurs.

Disable or enable query sequence termination when an error occurs.

By default query sequence execution is terminated when an error occurs. This function allows you to
allow termination to continue after an error.

This function is most useful during testing.

Throw an exception when an error occurs.

By default errors are logged. This function allows you to cause errors to throw exceptions.

**Note:** You cannot catch exceptions thrown by ScrewtopDb query sequences by enclosing the sequence
in a try block because the query is not actually executed until after the try-catch block has been
exited. This means that error exceptions will always cause termination of the script. In almost all
cases, the onError function is a better choice.

Run an operation as an isolated sub-chain, capture whether it produced an error, then run exactly one branch — onSuccess or onFailure — before continuing the enclosing chain. A failure inside the operation is captured: it does NOT invoke the module-level onError handler and does NOT terminate the enclosing chain. onFailure receives the captured error object as its second argument.

Each branch callback receives a fresh chain to build on and must NOT call .end() — try() owns the sub-chain lifecycle. The operation fragment is seeded with the enclosing result set so opFn can read its inbound context, but try() is a control-flow bracket: the enclosing result set passes through UNCHANGED to the steps after .try(), and onSuccess cannot see what the operation produced. If you need the operation’s output downstream, use a plain chain with explicit error handling instead.

Output the current result set or a text string.

In the Node.js environment, output is directed by default to the console. In the browser
environment, output is displayed by default in an alert box. The output destination may be
changed using the logFunc method.

This step passes the current result set unchanged to the following step.

Suppress or enable logging of errors.

By default errors are logged. This function allows you to cause errors not to be displayed in any way.
This function is most useful during testing.

Replace the default logging function.

The default logging function displays an alert dialog when in the browser environment and logs to the console in the
Node.js environment. This function allows to replace the default logging function with one of your own.

Log HTTP requests to the server.

This function is only functional in the Node.js environment.

By default server requests and responses are not logged.

Outgoing requests are prefixed with "`-->`" to distinguish them from server responses.