Docs / Data & bulk sync

a9script authoring pack — pagination functions

The pagination functions, with their arguments and a line of real script each. Called by bare name; nothing is imported. A call marked pauses does real work outside the script: the run is saved, and continues on the next line with the result.

This is one part of the authoring pack — how a script is executed at all is the model part, and the other groups of functions are parts of their own. All of them are named at the end.

Generated — do not edit. Every block of script below is executed by the platform’s own test suite, and every error message is the one the platform produces today, so none of this can be what was true when someone last wrote it down.

fetchPage(functionName, arguments, cursor?) — pauses

Reads ONE page from a configured function that was set up to page, and tells you how to ask for the next one. The hand-written way through a collection — reach for dsFetchInto when the pages are only going into a dataset anyway.

• functionName (string) — The configured function to call. It must have a pagination block: without one it answers a single result, and paging it is refused rather than guessed at.
• arguments (object) — The arguments that function declares, exactly as a bare call passes them. They are sent again for every page — a page is the same call, asked for a different slice.
• cursor (any, optional) — Where to continue: what the previous page answered as next. Left out, the walk starts at the first page.

Answers: { items, next, delta }. items is this page’s records as a list. next is what to pass as the cursor for the page after this one — ABSENT when this was the last page, which is how the walk ends. delta is the provider’s sync token when the function’s block names where it lives, usually only on the last page; store it with setState if the next sync should ask for changes only.

const page = fetchPage("MyPagedFunction", {});
log(page.items.length + " records on the first page");
if (page.next === undefined) { log("that was all of them"); }

dsFetchInto(functionName, arguments, dataset, options?) — pauses

Pulls EVERY page of a configured function into a dataset — one call instead of a cursor loop. The platform fetches a page, stages it, and pauses the run between pages, so a pull of a hundred pages costs a hundred short segments instead of one run holding a worker; if the far end says it is being called too often, the run waits and continues from the page it was on rather than starting over.

• functionName (string) — The configured function to walk. It must have a pagination block.
• arguments (object) — The arguments that function declares — sent again for every page.
• dataset (string) — Where the records are staged. A run: name is private to this run and cleaned up after it — dsRename it to a durable name to keep it, which is how a pulled set becomes the next sync’s baseline.
• options (object, optional) — { keyPath } — which field of a record is its key in the dataset. Left out, the record’s own id is used: id, Id or ID, whichever it has. A record with none of them, and no keyPath to say otherwise, is refused rather than given an invented key.

Answers: { pages, rows, delta } once the whole collection is in: how many pages were fetched, how many records were staged, and the provider’s sync token when its block names one. The pull stops early — with what it has — when the function’s configured page limit is reached.

const pull = dsFetchInto("MyPagedFunction", {}, "run:contacts");
log("staged " + pull.rows + " records from " + pull.pages + " pages");
dsRename("run:contacts", "contacts");

The rest of this pack

The page above is everything that is true only HERE. Ask for these parts by name for the rest:

• model — how a script is executed, the shape of its input, the rules enforced while it runs, and the mistakes that do not work here.
• functions-core — the core functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-encoding — the encoding functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-crypto — the crypto functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-text — the text functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-number — the numbers functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-structured — the structured data functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-document — the documents functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-markdown — the markdown functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-datetime — the date & time functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-email — the email functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-blob — the files functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-mapping — the mapping functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-dataset — the datasets functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-state — the state functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-control — the run control functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-functions — the config functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• mistakes — the habits from general JS that do not work here — each with the exact error it produces and the shape to write instead.
• standard-library — every built-in the language itself provides — JSON, Math, Object, String, Array, Number, Map, Set, Date, RegExp and the bare globals — one line each, with an example and its answer.