@centralping/ergo 0.1.0-beta.1 → 0.1.0-beta.3

package/types/lib/link.d.ts

@@ -35,3 +35,31 @@ export function paginationLinks({ baseUrl, page, perPage, total, searchParams }:
     href: string;
     rel: string;
 }>;
+/**
+ * Generates cursor-based pagination link objects for first, prev, and next pages.
+ *
+ * Unlike offset pagination, cursor-based pagination uses opaque continuation
+ * tokens instead of page numbers. There is no `last` link because the total
+ * number of pages is unknown in cursor-based schemes.
+ *
+ * The `first` link is always present and points to the base URL without any
+ * cursor parameter (requesting the first page). `prev` and `next` are
+ * included only when the corresponding cursor token is provided.
+ *
+ * @param {object} options - Cursor pagination parameters
+ * @param {string} options.baseUrl - Base URL path (e.g. '/articles')
+ * @param {string} [options.searchParams=''] - Additional query parameters to preserve
+ *   (e.g. 'sort=date&filter=active'). Appended before the cursor parameter.
+ * @param {string} [options.nextCursor] - Opaque cursor token for the next page
+ * @param {string} [options.prevCursor] - Opaque cursor token for the previous page
+ * @returns {Array<{href: string, rel: string}>} - Array of link objects
+ */
+export function cursorPaginationLinks({ baseUrl, searchParams, nextCursor, prevCursor }: {
+    baseUrl: string;
+    searchParams?: string | undefined;
+    nextCursor?: string | undefined;
+    prevCursor?: string | undefined;
+}): Array<{
+    href: string;
+    rel: string;
+}>;

package/types/lib/prefer.d.ts

@@ -13,11 +13,10 @@
  * - `http/prefer.js` (ergo pipeline middleware)
  *
  * @module lib/prefer
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import parsePrefer from 'ergo/lib/prefer';
+ * import parsePrefer from '@centralping/ergo/lib/prefer';
  *
  * parsePrefer('return=minimal');
  * // {return: 'minimal'}

package/types/lib/rate-limit.d.ts

@@ -39,11 +39,10 @@ export function defaultKeyGenerator(req: object): string;
  * - `ergo-router/lib/transport/rate-limit.js` (transport-level rate limiting)
  *
  * @module lib/rate-limit
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import {MemoryStore, checkRateLimit, defaultKeyGenerator} from 'ergo/lib/rate-limit';
+ * import {MemoryStore, checkRateLimit, defaultKeyGenerator} from '@centralping/ergo/lib/rate-limit';
  *
  * const store = new MemoryStore();
  * const key = defaultKeyGenerator(req);

package/types/lib/sanitize-quoted-string.d.ts

@@ -7,7 +7,6 @@
  * `WWW-Authenticate`, `Link`, and `Set-Cookie`.
  *
  * @module lib/sanitize-quoted-string
- * @version 0.1.0
  * @since 0.1.0
  */
 /**

package/types/lib/vary.d.ts

@@ -5,7 +5,6 @@
  * Uses Set-based deduplication with case-insensitive comparison.
  *
  * @module lib/vary
- * @version 0.1.0
  * @since 0.1.0
  */
 /**

package/types/utils/compose.d.ts

@@ -20,11 +20,10 @@ export default compose;
  * of ergo's built-in middleware).
  *
  * @module utils/compose
- * @version 0.2.0
  * @since 0.1.0
  *
  * @example
- * import compose from 'ergo/utils/compose';
+ * import compose from '@centralping/ergo/utils/compose';
  *
  * const pipeline = compose(
  *   async (req, res) => ({user: await getUser(req)}),

package/types/utils/iterables/range.d.ts

@@ -5,11 +5,10 @@
  * stepping by `step`. Mirrors Python's `range()` behaviour.
  *
  * @module utils/iterables/range
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import range from 'ergo/utils/iterables/range';
+ * import range from '@centralping/ergo/utils/iterables/range';
  *
  * [...range(5)]        // => [0, 1, 2, 3, 4]
  * [...range(1, 5)]     // => [1, 2, 3, 4]

package/utils/attempt.js

@@ -7,11 +7,10 @@
  * Used by `http/handler.js` to wrap the try pipeline with an error handler pipeline.
  *
  * @module utils/attempt
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import attempt from 'ergo/utils/attempt';
+ * import attempt from '@centralping/ergo/utils/attempt';
  *
  * const safe = attempt(
  *   async (req, res) => { throw new Error('oops'); },

package/utils/buffers/index.js

@@ -4,7 +4,6 @@
  * Provides `match` (KMP substring search in Buffers) and `split` (Buffer split by separator).
  *
  * @module utils/buffers
- * @version 0.1.0
  * @since 0.1.0
  * @requires ./match.js
  * @requires ./split.js

package/utils/buffers/match.js

@@ -9,11 +9,10 @@
  * match state (`partial`) for the next chunk.
  *
  * @module utils/buffers/match
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import bufferMatch from 'ergo/utils/buffers/match';
+ * import bufferMatch from '@centralping/ergo/utils/buffers/match';
  *
  * const {matches} = bufferMatch(Buffer.from('hello world'), Buffer.from('l'));
  * // matches => [2, 3, 9]

package/utils/buffers/split.js

@@ -8,13 +8,12 @@
  * Returns `{buffers, partial, lookup}` where `buffers` is the array of Buffer slices.
  *
  * @module utils/buffers/split
- * @version 0.1.0
  * @since 0.1.0
  * @requires ./match.js
  * @requires ../get.js
  *
  * @example
- * import bufferSplit from 'ergo/utils/buffers/split';
+ * import bufferSplit from '@centralping/ergo/utils/buffers/split';
  *
  * const {buffers} = bufferSplit(Buffer.from('a--b--c'), Buffer.from('--'));
  * // buffers => [Buffer<'a'>, Buffer<'b'>, Buffer<'c'>]

package/utils/compose-with.js

@@ -21,13 +21,12 @@
  * for compatibility with simple middleware that only produce domain data.
  *
  * @module utils/compose-with
- * @version 0.2.0
  * @since 0.1.0
  * @requires ./compose.js
  * @requires ./set.js
  *
  * @example
- * import compose, {createResponseAcc} from 'ergo/utils/compose-with';
+ * import compose, {createResponseAcc} from '@centralping/ergo/utils/compose-with';
  *
  * const responseAcc = createResponseAcc();
  * const pipeline = compose(

package/utils/compose.js

@@ -19,11 +19,10 @@
  * of ergo's built-in middleware).
  *
  * @module utils/compose
- * @version 0.2.0
  * @since 0.1.0
  *
  * @example
- * import compose from 'ergo/utils/compose';
+ * import compose from '@centralping/ergo/utils/compose';
  *
  * const pipeline = compose(
  *   async (req, res) => ({user: await getUser(req)}),

package/utils/flat-array.js

@@ -5,11 +5,10 @@
  * Equivalent to `[...args].flat()` — accepts any mix of scalars and nested arrays.
  *
  * @module utils/flat-array
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import flatArray from 'ergo/utils/flat-array';
+ * import flatArray from '@centralping/ergo/utils/flat-array';
  *
  * flatArray('a', ['b', 'c'], 'd') // => ['a', 'b', 'c', 'd']
  * flatArray(1, [2, 3], 4)         // => [1, 2, 3, 4]

package/utils/get.js

@@ -6,11 +6,10 @@
  * - Returns `undefined` gracefully when a step is missing (`safe: true`)
  *
  * @module utils/get
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import get from 'ergo/utils/get';
+ * import get from '@centralping/ergo/utils/get';
  *
  * get({a: {b: {c: 42}}}, 'a.b.c') // => 42
  * get({a: null}, 'a.b.c', {safe: true}) // => undefined (no throw)

package/utils/http-errors.js

@@ -15,14 +15,13 @@
  * catches them and forwards to `send()` for serialization.
  *
  * @module utils/http-errors
- * @version 0.1.0
  * @since 0.1.0
  * @requires node:http
  *
  * @see {@link https://www.rfc-editor.org/rfc/rfc9457 RFC 9457 - Problem Details for HTTP APIs}
  *
  * @example
- * import httpErrors from 'ergo/utils/http-errors';
+ * import httpErrors from '@centralping/ergo/utils/http-errors';
  *
  * throw httpErrors(404);
  * // Error { name: 'NotFound', status: 404, type: 'https://...', title: 'Not Found', detail: 'Not Found' }

package/utils/iterables/buffer-split.js

@@ -8,12 +8,11 @@
  * Used by `lib/body/multiparse.js` for multipart boundary splitting.
  *
  * @module utils/iterables/buffer-split
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../buffers/split.js
  *
  * @example
- * import {chain, bufferSplit, reduce} from 'ergo/utils/iterables';
+ * import {chain, bufferSplit, reduce} from '@centralping/ergo/utils/iterables';
  *
  * const chunks = [Buffer.from('a--b--c')];
  * const result = chain(chunks, bufferSplit('--'), reduce((acc, [, b]) => [...acc, b.toString()], []));

package/utils/iterables/chain.js

@@ -8,11 +8,10 @@
  * This is the core primitive for building lazy data pipelines with the iterable utilities.
  *
  * @module utils/iterables/chain
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import {chain, map, filter, reduce} from 'ergo/utils/iterables';
+ * import {chain, map, filter, reduce} from '@centralping/ergo/utils/iterables';
  *
  * chain(
  *   [1, 2, 3, 4, 5],

package/utils/iterables/exec-all.js

@@ -6,11 +6,10 @@
  * flag is added to avoid infinite loops with stateful regexes.
  *
  * @module utils/iterables/exec-all
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import execAll from 'ergo/utils/iterables/exec-all';
+ * import execAll from '@centralping/ergo/utils/iterables/exec-all';
  *
  * const findWords = execAll(/([a-z]+)/ig);
  * [...findWords('hello world')] // => [['hello'], ['world']]

package/utils/iterables/filter.js

@@ -6,11 +6,10 @@
  * to the predicate (same signature as `Array.prototype.filter`).
  *
  * @module utils/iterables/filter
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import {chain, filter} from 'ergo/utils/iterables';
+ * import {chain, filter} from '@centralping/ergo/utils/iterables';
  *
  * [...chain([1, 2, 3, 4], filter(x => x % 2 === 0))] // => [2, 4]
  */

package/utils/iterables/for-each.js

@@ -6,12 +6,11 @@
  * for iterables, but composable in a `chain()` pipeline.
  *
  * @module utils/iterables/for-each
- * @version 0.1.0
  * @since 0.1.0
  * @requires ./map.js
  *
  * @example
- * import {chain, forEach, reduce} from 'ergo/utils/iterables';
+ * import {chain, forEach, reduce} from '@centralping/ergo/utils/iterables';
  *
  * chain(
  *   [1, 2, 3],

package/utils/iterables/from-stream.js

@@ -6,11 +6,10 @@
  * interface for code that receives streams and needs to iterate them.
  *
  * @module utils/iterables/from-stream
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import fromStream from 'ergo/utils/iterables/from-stream';
+ * import fromStream from '@centralping/ergo/utils/iterables/from-stream';
  * import {Readable} from 'node:stream';
  *
  * const readable = Readable.from(['hello', ' ', 'world']);

package/utils/iterables/index.js

@@ -6,7 +6,6 @@
  *   `chain(source, bufferSplit(sep), map(fn), reduce(fn, init))`
  *
  * @module utils/iterables
- * @version 0.1.0
  * @since 0.1.0
  */
 export {default as bufferSplit} from './buffer-split.js';

package/utils/iterables/map.js

@@ -6,12 +6,11 @@
  * async generators; sync transforms produce sync generators.
  *
  * @module utils/iterables/map
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../type.js
  *
  * @example
- * import {chain, map} from 'ergo/utils/iterables';
+ * import {chain, map} from '@centralping/ergo/utils/iterables';
  *
  * [...chain([1, 2, 3], map(x => x * 2))] // => [2, 4, 6]
  *

package/utils/iterables/range.js

@@ -5,11 +5,10 @@
  * stepping by `step`. Mirrors Python's `range()` behaviour.
  *
  * @module utils/iterables/range
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import range from 'ergo/utils/iterables/range';
+ * import range from '@centralping/ergo/utils/iterables/range';
  *
  * [...range(5)]        // => [0, 1, 2, 3, 4]
  * [...range(1, 5)]     // => [1, 2, 3, 4]

package/utils/iterables/reduce.js

@@ -6,11 +6,10 @@
  * least one element, the first element is used as the initial accumulator.
  *
  * @module utils/iterables/reduce
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import {chain, reduce} from 'ergo/utils/iterables';
+ * import {chain, reduce} from '@centralping/ergo/utils/iterables';
  *
  * chain([1, 2, 3, 4], reduce((sum, x) => sum + x, 0)) // => 10
  */

package/utils/iterables/take.js

@@ -5,11 +5,10 @@
  * then returns (stops iteration).
  *
  * @module utils/iterables/take
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import {chain, take} from 'ergo/utils/iterables';
+ * import {chain, take} from '@centralping/ergo/utils/iterables';
  *
  * [...chain([1, 2, 3, 4, 5], take(3))] // => [1, 2, 3]
  */

package/utils/observables/buffer-split.js

@@ -6,7 +6,6 @@
  * integration with observable-style pipelines built with `utils/observables/chain`.
  *
  * @module utils/observables/buffer-split
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../buffers/split.js
  *

package/utils/observables/chain.js

@@ -6,7 +6,6 @@
  * The last generator in the array is the sink.
  *
  * @module utils/observables/chain
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../type.js
  */

package/utils/observables/index.js

@@ -6,7 +6,6 @@
  * body parsing and other real-time data flows.
  *
  * @module utils/observables
- * @version 0.1.0
  * @since 0.1.0
  * @requires ./buffer-split.js
  * @requires ./chain.js

package/utils/observables/map.js

@@ -5,7 +5,6 @@
  * transformed and forwarded downstream via the iterator's `.next()`.
  *
  * @module utils/observables/map
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example

package/utils/observables/take.js

@@ -5,7 +5,6 @@
  * downstream iterator, then calls `.return()` to signal completion.
  *
  * @module utils/observables/take
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example

package/utils/pick.js

@@ -6,13 +6,12 @@
  * - Rename tuples: `pick(obj, ['a.b', 'c'])` extracts `obj.a.b` as `result.c`
  *
  * @module utils/pick
- * @version 0.1.0
  * @since 0.1.0
  * @requires ./get.js
  * @requires ./set.js
  *
  * @example
- * import pick from 'ergo/utils/pick';
+ * import pick from '@centralping/ergo/utils/pick';
  *
  * pick({a: {b: 1}, c: 2}, 'a.b', 'c')
  * // => {a: {b: 1}, c: 2}

package/utils/set.js

@@ -6,11 +6,10 @@
  * Array nodes are created when the next path segment is a valid integer string.
  *
  * @module utils/set
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import set from 'ergo/utils/set';
+ * import set from '@centralping/ergo/utils/set';
  *
  * const obj = {};
  * set(obj, 'a.b.c', 42);   // obj => {a: {b: {c: 42}}}

package/utils/streams/index.js

@@ -2,7 +2,6 @@
  * @fileoverview Streams utilities barrel export.
  *
  * @module utils/streams
- * @version 0.1.0
  * @since 0.1.0
  * @requires ./meter.js
  * @requires ./tee.js

package/utils/streams/meter.js

@@ -6,13 +6,12 @@
  * (InvalidLength). Used by `http/body.js` to enforce size constraints.
  *
  * @module utils/streams/meter
- * @version 0.1.0
  * @since 0.1.0
  * @requires node:stream
  *
  * @example
  * import {pipeline} from 'node:stream';
- * import meter from 'ergo/utils/streams/meter';
+ * import meter from '@centralping/ergo/utils/streams/meter';
  *
  * const m = meter({limit: 1024 * 1024, expected: 512});
  * pipeline(readable, m, writable, err => {

package/utils/streams/tee.js

@@ -8,13 +8,12 @@
  * If no generator is provided, a no-op generator is used (pure passthrough).
  *
  * @module utils/streams/tee
- * @version 0.1.0
  * @since 0.1.0
  * @requires node:stream
  *
  * @example
  * import {pipeline} from 'node:stream';
- * import tee from 'ergo/utils/streams/tee';
+ * import tee from '@centralping/ergo/utils/streams/tee';
  *
  * async function* inspect(gen) {
  *   let chunk;

package/utils/type.js

@@ -9,11 +9,10 @@
  * Used throughout Ergo for duck-typing checks (e.g. `type(x) === 'AsyncGeneratorFunction'`).
  *
  * @module utils/type
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import type from 'ergo/utils/type';
+ * import type from '@centralping/ergo/utils/type';
  *
  * type(42)              // 'Number'
  * type(NaN)             // 'NaN'