Skip to main content

FAQ

Do I need a Rust toolchain to install it?​

No. The Python wheel and the npm package bundle the native engine (prebuilt PyO3 / napi-rs binaries) for Linux, macOS, and Windows on x86-64 and arm64. You only need a Rust toolchain if you build from source or embed paginate-core directly.

Is it actually faster than my language's built-in array methods?​

It depends on the operation — and the docs are candid about it. The cursor codec and the resident Dataset pipeline are clear native wins. A single one-shot filter/sort over data your host already holds is often not faster than the host's own array methods, because marshalling the items across the boundary dominates. Use the one-shot helpers for parity and the Dataset.page pipeline for the hot path. See performance.

Can a Python service and a TypeScript client share cursors?​

Yes — that's the headline feature. The cursor codec is one implementation, so a cursor minted by pypaginate decodes byte-for-byte in @cyblow/paginate and back. See cursors and parity.

Should I use offset or keyset (cursor) pagination?​

Use offset for jump-to-page navigation, page counts, and bounded/in-memory data; use keyset for large or frequently-changing tables, deep paging, and infinite scroll. The full comparison is in pagination models.

Why aren't my one-shot filter / sort calls faster than pure host code?​

Because each call marshals the whole collection into the engine. When you query the same rows repeatedly, build a Dataset once and reuse it — that amortizes the marshalling and runs the fused filter → sort → paginate pipeline natively.

Does it support async?​

The engine itself is synchronous compute. Async lives in the adapters: the Python SQLAlchemy adapter has async backends (SQLAlchemyBackend, SQLAlchemyCursorBackend), and the FastAPI dependencies work in async handlers. See the SQLAlchemy and FastAPI guides.

Is Pydantic required?​

No. pypaginate's core has zero runtime dependencies; the spec/param/page types are plain dataclasses. Pydantic is pulled in only by the [fastapi] extra (for request / response models and OpenAPI). See choosing a package.

What Python / Node versions are supported?​

Python 3.11+ and Node 18+. The Rust core targets a recent stable toolchain.

How do operators / directions / modes work — are they enums?​

They're plain strings ("gte", "desc", "contains", "fuzzy"), defined once in the core. There are no enum classes to import — pass the string. See the filtering, sorting, and search reference.

Where is the full API reference?​

In the API Reference section: the Rust API on docs.rs, the TypeScript API generated by TypeDoc, and the Python API generated from the pypaginate docstrings.

Which package do I install?​

One per language: pip install pypaginate, npm i @cyblow/paginate, or cargo add paginate-core. They share semantics and the cursor format — see choosing a package.