@sambuddha_npm_dev/pagecraft 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 PageCraft contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# PageCraft
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+PageCraft is a dependency-free JavaScript utility for filtering, searching, sorting, and paginating arrays of records. It uses ES modules and supports Node.js 18 or newer.
+
+## Install
+
+```sh
+npm install @sambuddha_npm_dev/pagecraft
+```
+
+## Quick start
+
+```js
+import { paginate } from "@sambuddha_npm_dev/pagecraft";
+
+const users = [
+  { id: 1, name: "Sam", role: "student" },
+  { id: 2, name: "Alex", role: "admin" },
+  { id: 3, name: "Samira", role: "student" },
+  { id: 4, name: "Jordan", role: "student" }
+];
+
+const result = paginate(users, {
+  page: 1,
+  limit: 2,
+  filters: { role: "student" },
+  search: { query: "sam", fields: ["name"] },
+  sortBy: "name",
+  order: "asc"
+});
+
+console.log(result.data.map((user) => user.name)); // ["Sam", "Samira"]
+console.log(result.pagination);
+```
+
+## API
+
+### `paginate(data, options = {})`
+
+Processes an array in this order: filters, search, sorting, then pagination. It returns a new array and does not mutate the input.
+
+| Option | Type | Default | Behavior |
+|---|---|---|---|
+| `page` | integer | `1` | One-based page number; must be positive. |
+| `limit` | integer | `10` | Items per page; must be from `1` to `100`. |
+| `filters` | object | none | Each property must match a record property using strict equality; every filter must match. |
+| `search` | `{ query, fields }` | none | Case-insensitive substring search in the listed fields. `query` is a string and `fields` is an array of strings. |
+| `sortBy` | string | none | Record property to sort by. An empty string does not enable sorting. |
+| `order` | `"asc"` or `"desc"` | `"asc"` | Sort direction. |
+
+Example result:
+
+```js
+{
+  data: [{ id: 1, name: "Sam", role: "student" }],
+  pagination: {
+    page: 1,
+    limit: 10,
+    totalItems: 1,
+    totalPages: 1,
+    hasNextPage: false,
+    hasPreviousPage: false
+  }
+}
+```
+
+`totalItems` and `totalPages` describe the filtered, searched, and sorted records before slicing. A page beyond the last page returns an empty `data` array. Empty input has `totalPages: 0`.
+
+### `filterData(data, filters = {})`
+
+Returns records matching every filter with strict equality (`===`).
+
+```js
+import { filterData } from "@sambuddha_npm_dev/pagecraft";
+
+const students = filterData(
+  [{ name: "Sam", role: "student" }, { name: "Alex", role: "admin" }],
+  { role: "student" }
+);
+```
+
+### `searchData(data, query, fields)`
+
+Returns records where at least one selected field contains the trimmed query, case-insensitively. Field values are converted to strings. A blank query returns a shallow copy of the input array.
+
+```js
+import { searchData } from "@sambuddha_npm_dev/pagecraft";
+
+const matches = searchData([{ name: "Sam" }, { name: "Alex" }], "SAM", ["name"]);
+```
+
+### `sortData(data, field, order = "asc")`
+
+Returns a sorted copy. When both values are numbers they sort numerically; otherwise they compare as case-insensitive strings with numeric-aware ordering. Null or missing values sort last ascending and first descending.
+
+```js
+import { sortData } from "@sambuddha_npm_dev/pagecraft";
+
+const sorted = sortData([{ name: "Sam" }, { name: "Alex" }], "name", "desc");
+```
+
+### `validateQuery(options = {})`
+
+Validates the `page`, `limit`, and `order` values and checks the types of `sortBy`, `filters`, and `search`. It returns normalized pagination and order defaults:
+
+```js
+import { validateQuery } from "@sambuddha_npm_dev/pagecraft";
+
+const query = validateQuery({ page: 2, limit: 5 });
+// { page: 2, limit: 5, order: "asc" }
+```
+
+Invalid top-level inputs and malformed filters/search options throw `TypeError`; invalid page, limit, or order values throw `RangeError`. `paginate`, `filterData`, `searchData`, and `sortData` require `data` to be an array. Filtering and searching are intended for arrays of object records; non-object entries do not match those operations.
+
+## Express example
+
+```js
+import express from "express";
+import { paginate } from "@sambuddha_npm_dev/pagecraft";
+
+const app = express();
+const users = [
+  { id: 1, name: "Sam", role: "student" },
+  { id: 2, name: "Alex", role: "admin" }
+];
+
+app.get("/users", (req, res) => {
+  try {
+    const result = paginate(users, {
+      page: req.query.page === undefined ? 1 : Number(req.query.page),
+      limit: req.query.limit === undefined ? 10 : Number(req.query.limit),
+      sortBy: req.query.sortBy,
+      order: req.query.order
+    });
+    res.json(result);
+  } catch (error) {
+    res.status(400).json({ error: error.message });
+  }
+});
+
+app.listen(3000);
+```
+
+## Development
+
+```sh
+npm test
+npm pack
+```
+
+The tests use Node.js's built-in test runner. PageCraft processes data in memory; for large datasets, use database-level filtering and pagination.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@sambuddha_npm_dev/pagecraft",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Small in-memory helpers for pagination, sorting, filtering, searching, and query validation.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SammyBanner45/PageCraft.git"
+  },
+  "homepage": "https://github.com/SammyBanner45/PageCraft#readme",
+  "bugs": {
+    "url": "https://github.com/SammyBanner45/PageCraft/issues"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "test:watch": "node --test --watch"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["pagination", "sorting", "filtering", "search", "query"]
+}

package/src/index.js

@@ -0,0 +1,109 @@
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 100;
+
+export function validateQuery(options = {}) {
+  if (options === null || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("options must be an object");
+  }
+
+  const page = options.page ?? 1;
+  const limit = options.limit ?? DEFAULT_LIMIT;
+  const order = options.order ?? "asc";
+
+  if (!Number.isInteger(page) || page < 1) {
+    throw new RangeError("page must be a positive integer");
+  }
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+    throw new RangeError(`limit must be an integer between 1 and ${MAX_LIMIT}`);
+  }
+  if (order !== "asc" && order !== "desc") {
+    throw new RangeError('order must be "asc" or "desc"');
+  }
+  if (options.sortBy !== undefined && typeof options.sortBy !== "string") {
+    throw new TypeError("sortBy must be a string");
+  }
+  if (options.filters !== undefined && (options.filters === null || typeof options.filters !== "object" || Array.isArray(options.filters))) {
+    throw new TypeError("filters must be an object");
+  }
+  if (options.search !== undefined) {
+    const search = options.search;
+    if (search === null || typeof search !== "object" || Array.isArray(search)) {
+      throw new TypeError("search must be an object with query and fields");
+    }
+    if (typeof search.query !== "string") throw new TypeError("search.query must be a string");
+    if (!Array.isArray(search.fields) || search.fields.some((field) => typeof field !== "string")) {
+      throw new TypeError("search.fields must be an array of strings");
+    }
+  }
+
+  return { page, limit, order };
+}
+
+export function filterData(data, filters = {}) {
+  assertArray(data);
+  if (filters === null || typeof filters !== "object" || Array.isArray(filters)) {
+    throw new TypeError("filters must be an object");
+  }
+  const entries = Object.entries(filters);
+  return data.filter((item) => item !== null && typeof item === "object" && entries.every(([key, value]) => item[key] === value));
+}
+
+export function searchData(data, query, fields) {
+  assertArray(data);
+  if (typeof query !== "string") throw new TypeError("query must be a string");
+  if (!Array.isArray(fields) || fields.some((field) => typeof field !== "string")) {
+    throw new TypeError("fields must be an array of strings");
+  }
+  const needle = query.trim().toLocaleLowerCase();
+  if (!needle) return [...data];
+  return data.filter((item) => item !== null && typeof item === "object" && fields.some((field) => {
+    const value = item[field];
+    return value !== null && value !== undefined && String(value).toLocaleLowerCase().includes(needle);
+  }));
+}
+
+export function sortData(data, field, order = "asc") {
+  assertArray(data);
+  if (typeof field !== "string" || !field) throw new TypeError("field must be a non-empty string");
+  if (order !== "asc" && order !== "desc") throw new RangeError('order must be "asc" or "desc"');
+  const direction = order === "asc" ? 1 : -1;
+  return [...data].sort((left, right) => {
+    const a = left?.[field];
+    const b = right?.[field];
+    if (a == null && b == null) return 0;
+    if (a == null) return 1;
+    if (b == null) return -1;
+    const comparison = typeof a === "number" && typeof b === "number"
+      ? a - b
+      : String(a).localeCompare(String(b), undefined, { numeric: true, sensitivity: "base" });
+    return comparison * direction;
+  });
+}
+
+export function paginate(data, options = {}) {
+  assertArray(data);
+  const { page, limit } = validateQuery(options);
+  let result = [...data];
+  if (options.filters) result = filterData(result, options.filters);
+  if (options.search) result = searchData(result, options.search.query, options.search.fields);
+  if (options.sortBy) result = sortData(result, options.sortBy, options.order ?? "asc");
+
+  const totalItems = result.length;
+  const totalPages = Math.ceil(totalItems / limit);
+  const start = (page - 1) * limit;
+  return {
+    data: result.slice(start, start + limit),
+    pagination: {
+      page,
+      limit,
+      totalItems,
+      totalPages,
+      hasNextPage: page < totalPages,
+      hasPreviousPage: page > 1 && totalPages > 0
+    }
+  };
+}
+
+function assertArray(data) {
+  if (!Array.isArray(data)) throw new TypeError("data must be an array");
+}