@cyblow/paginate-core 0.1.3

package/README.md

@@ -0,0 +1,68 @@
+# paginate-node
+
+napi-rs (Node-API) adapter that exposes the pure-Rust [`paginate-core`](../core)
+engine to Node.js / TypeScript. It mirrors the [PyO3 adapter](../py) surface so
+both runtimes share one engine and one set of behaviours (the cursor wire format
+is byte-identical across Python, Node, and the core itself).
+
+## What it exposes
+
+Rust function names are exported to JavaScript as camelCase (napi-rs convention):
+
+| JS export | Signature | Description |
+|-----------|-----------|-------------|
+| `normalizeText` | `(value: string) => string` | NFKD accent-stripping text normalization. |
+| `offset` | `(page: number, limit: number) => number` | Zero-based row offset. |
+| `maxPages` | `(total: number, limit: number) => number` | Total page count (ceil). |
+| `clampPage` | `(page, limit, total) => number` | Clamp page into `[1, maxPage]`. |
+| `offsetMeta` | `(page, limit, total) => OffsetMeta` | `{ page, pages, hasNext, hasPrevious }`. |
+| `encodeCursor` | `(values: unknown) => string` | Encode ordering values into a URL-safe cursor. |
+| `decodeCursor` | `(cursor: string) => unknown[]` | Decode a cursor back into its ordering values. |
+| `filterIndices` | `(items, specs) => number[]` | Indices matching flat filter specs `[{field,op,value,logic?}]`. |
+| `sortIndices` | `(items, specs) => number[]` | Index permutation for sort specs `[{field,direction?,nulls?}]`. |
+| `searchIndices` | `(items, query, fields, …) => number[]` | Ranked search indices over `fields`. |
+
+### Cursor values
+
+Ordering values cross the boundary as plain JSON (`serde_json::Value`):
+`null` / `bool` / `number` (integral -> Int, otherwise Float) / `string` /
+`array` / `object`. JavaScript has no native datetime / Decimal / UUID types, so
+the typed-scalar variants the Python codec round-trips are not minted here —
+pass their ISO/canonical strings instead. Cursors remain interoperable: a cursor
+produced by Python or the Rust core decodes here and vice versa.
+
+### Performance — prefer native Array methods for in-memory work
+
+`filterIndices` / `sortIndices` / `searchIndices` exist for **behaviour parity**
+with pypaginate's exact semantics — **not** for speed. Marshalling a large array
+across the napi boundary costs far more than the per-item work, so V8's
+`Array.filter` / `Array.sort` are **40–230× faster** (see
+[../../BENCHMARKS.md](../../BENCHMARKS.md)). Reach for the native engines only
+when you need pypaginate's precise operator / ranking behaviour; otherwise use
+plain JS. The **cursor codec** and `normalizeText` are the consistency-critical
+paths genuinely worth crossing the boundary for.
+
+## Building
+
+This crate compiles to a Node-API addon (`crate-type = ["cdylib"]`). The native
+addon plus its generated `index.js` / `index.d.ts` glue are produced by
+[`@napi-rs/cli`](https://www.npmjs.com/package/@napi-rs/cli):
+
+```bash
+npm install        # installs @napi-rs/cli
+npm run build      # napi build --platform --release  -> *.node + index.{js,d.ts}
+```
+
+`build.rs` calls `napi_build::setup()` so the linker is configured for the host
+Node-API toolchain.
+
+A plain `cargo build -p paginate-node` / `cargo check -p paginate-node` compiles
+the Rust object too, but only `@napi-rs/cli` emits the loadable addon and TS
+type definitions.
+
+## Status
+
+Builds and is validated from Node — cursor wire-identical to Python/core, and
+filter/sort/search return correct results. The generated artifacts (`index.js`,
+`index.d.ts`, `*.node`) are build outputs and are not checked in. Consumed by
+the `packages/ts` TypeScript package.

package/index.d.ts

@@ -0,0 +1,85 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/**
+ * One page of results returned by [`Dataset::page`]. Numeric fields export as
+ * JS `number`; `has_next`/`has_previous` as `hasNext`/`hasPrevious`.
+ */
+export interface DatasetPage {
+  /** Indices (into the original array) of this page's rows, in final order. */
+  indices: Array<number>
+  /** Total matched rows after filtering, before paging. */
+  total: number
+  /** The requested page number. */
+  page: number
+  /** Total number of pages. */
+  pages: number
+  /** Whether a following page exists. */
+  hasNext: boolean
+  /** Whether a preceding page exists. */
+  hasPrevious: boolean
+}
+/** Indices of items matching flat filter specs `[{field, op, value, logic?}]`. */
+export declare function filterIndices(items: Json, specs: Json): Array<number>
+/**
+ * Indices of items matching a nested filter `group`. A leaf is
+ * `{field, op, value, logic?}`; a group is `{logic, conditions: [node, ...]}`.
+ * Mirrors the PyO3 `filter_group_indices` so JS/TS gets nested And/Or filters.
+ */
+export declare function filterGroupIndices(items: Json, group: Json): Array<number>
+/** A permutation of item indices for sort specs `[{field, direction?, nulls?}]`. */
+export declare function sortIndices(items: Json, specs: Json): Array<number>
+/** Ranked search: indices of items by relevance of `query` over `fields`. */
+export declare function searchIndices(items: Json, query: string, fields: Array<string>, mode?: string | undefined | null, fuzzy?: string | undefined | null, threshold?: number | undefined | null, minLength?: number | undefined | null, maxResults?: number | undefined | null): Array<number>
+/** Encode a list of ordering values into a URL-safe cursor string. */
+export declare function encodeCursor(values: Json): string
+/** Decode a cursor string back into its array of ordering values. */
+export declare function decodeCursor(cursor: string): Json
+/** Normalize text for search/filtering (ASCII fast path + NFKD accent strip). */
+export declare function normalizeText(value: string): string
+/**
+ * Page metadata returned by [`offset_meta`]. Fields export as camelCase
+ * (`hasNext`, `hasPrevious`) under napi-rs.
+ */
+export interface OffsetMeta {
+  /** The (possibly clamped) 1-based page number. */
+  page: number
+  /** Total number of pages. */
+  pages: number
+  /** Whether a following page exists. */
+  hasNext: boolean
+  /** Whether a preceding page exists. */
+  hasPrevious: boolean
+}
+/** Zero-based row offset for `(page, limit)`. */
+export declare function offset(page: number, limit: number): number
+/** Total page count for `total` rows at `limit` per page. */
+export declare function maxPages(total: number, limit: number): number
+/** Page metadata as an [`OffsetMeta`] object for `(page, limit, total)`. */
+export declare function offsetMeta(page: number, limit: number, total: number): OffsetMeta
+/** Clamp `page` into the valid `[1, max_page]` range. */
+export declare function clampPage(page: number, limit: number, total: number): number
+/**
+ * An in-memory dataset held in Rust as `core::Value` rows, queried by index.
+ * Build it once from a JS array of objects, then call `filter`/`sort`/`search`/
+ * `page`; each returns indices the caller maps back to its own objects.
+ */
+export declare class Dataset {
+  /** Marshal a JS array of objects into the resident dataset once. */
+  constructor(items: Json)
+  /** Number of rows. */
+  get size(): number
+  /** Indices matching flat filter specs `[{field, op, value, logic?}]`. */
+  filter(specs: Json): Array<number>
+  /** A permutation of row indices for sort specs `[{field, direction?, nulls?}]`. */
+  sort(specs: Json): Array<number>
+  /** Ranked-search indices over `fields`. */
+  search(query: string, fields: Array<string>, mode?: string | undefined | null, fuzzy?: string | undefined | null, threshold?: number | undefined | null, minLength?: number | undefined | null, maxResults?: number | undefined | null): Array<number>
+  /**
+   * Filter + sort + offset-paginate in ONE native call. Returns the page's
+   * row indices + offset metadata; the caller selects its rows by index.
+   */
+  page(page: number, limit: number, filters?: Json | undefined | null, sorts?: Json | undefined | null): DatasetPage
+}

package/index.js

@@ -0,0 +1,326 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, '@cyblow/paginate-core.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./@cyblow/paginate-core.android-arm64.node')
+          } else {
+            nativeBinding = require('@cyblow/paginate-core-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, '@cyblow/paginate-core.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./@cyblow/paginate-core.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@cyblow/paginate-core-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, '@cyblow/paginate-core.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./@cyblow/paginate-core.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@cyblow/paginate-core-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, '@cyblow/paginate-core.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./@cyblow/paginate-core.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@cyblow/paginate-core-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, '@cyblow/paginate-core.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./@cyblow/paginate-core.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@cyblow/paginate-core-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, '@cyblow/paginate-core.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./@cyblow/paginate-core.darwin-universal.node')
+      } else {
+        nativeBinding = require('@cyblow/paginate-core-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, '@cyblow/paginate-core.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./@cyblow/paginate-core.darwin-x64.node')
+          } else {
+            nativeBinding = require('@cyblow/paginate-core-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, '@cyblow/paginate-core.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./@cyblow/paginate-core.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@cyblow/paginate-core-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, '@cyblow/paginate-core.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./@cyblow/paginate-core.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@cyblow/paginate-core-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, '@cyblow/paginate-core.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./@cyblow/paginate-core.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@cyblow/paginate-core-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, '@cyblow/paginate-core.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./@cyblow/paginate-core.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@cyblow/paginate-core-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, '@cyblow/paginate-core.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./@cyblow/paginate-core.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@cyblow/paginate-core-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, '@cyblow/paginate-core.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./@cyblow/paginate-core.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@cyblow/paginate-core-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, '@cyblow/paginate-core.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./@cyblow/paginate-core.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@cyblow/paginate-core-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, '@cyblow/paginate-core.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./@cyblow/paginate-core.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@cyblow/paginate-core-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, '@cyblow/paginate-core.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./@cyblow/paginate-core.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@cyblow/paginate-core-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, '@cyblow/paginate-core.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./@cyblow/paginate-core.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@cyblow/paginate-core-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, '@cyblow/paginate-core.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./@cyblow/paginate-core.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@cyblow/paginate-core-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { Dataset, filterIndices, filterGroupIndices, sortIndices, searchIndices, encodeCursor, decodeCursor, normalizeText, offset, maxPages, offsetMeta, clampPage } = nativeBinding
+
+module.exports.Dataset = Dataset
+module.exports.filterIndices = filterIndices
+module.exports.filterGroupIndices = filterGroupIndices
+module.exports.sortIndices = sortIndices
+module.exports.searchIndices = searchIndices
+module.exports.encodeCursor = encodeCursor
+module.exports.decodeCursor = decodeCursor
+module.exports.normalizeText = normalizeText
+module.exports.offset = offset
+module.exports.maxPages = maxPages
+module.exports.offsetMeta = offsetMeta
+module.exports.clampPage = clampPage

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@cyblow/paginate-core",
+  "version": "0.1.3",
+  "description": "Node/TypeScript native bindings for paginate-core (cursor codec, text normalization, pagination math, filtering, sorting, search).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CybLow/paginate"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "napi": {
+    "name": "@cyblow/paginate-core",
+    "triples": {
+      "defaults": true,
+      "additional": [
+        "aarch64-apple-darwin",
+        "aarch64-unknown-linux-gnu",
+        "x86_64-unknown-linux-musl",
+        "aarch64-unknown-linux-musl",
+        "aarch64-pc-windows-msvc"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">=12.22.0"
+  },
+  "scripts": {
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "artifacts": "napi artifacts",
+    "prepublishOnly": "napi prepublish -t npm"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.0"
+  },
+  "_note": "Scaffold. Generated bindings (index.js/index.d.ts/*.node) are produced by `@napi-rs/cli` (`npm run build`) and are not checked in. Consumed by packages/ts.",
+  "optionalDependencies": {
+    "@cyblow/paginate-core-win32-x64-msvc": "0.1.3",
+    "@cyblow/paginate-core-darwin-x64": "0.1.3",
+    "@cyblow/paginate-core-linux-x64-gnu": "0.1.3",
+    "@cyblow/paginate-core-darwin-arm64": "0.1.3",
+    "@cyblow/paginate-core-linux-arm64-gnu": "0.1.3",
+    "@cyblow/paginate-core-linux-x64-musl": "0.1.3",
+    "@cyblow/paginate-core-linux-arm64-musl": "0.1.3",
+    "@cyblow/paginate-core-win32-arm64-msvc": "0.1.3"
+  }
+}