@sambuddha_npm_dev/pagecraft 0.0.0-stage → 1.0.0

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,95 @@
-# 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 small, dependency-free JavaScript utility for filtering, searching, sorting, and paginating arrays. It uses ES modules and runs on Node.js 18 or newer.
+
+## Install
+
+```sh
+npm install pagecraft
+```
+
+## Quick start
+
+```js
+import { paginate } from "pagecraft";
+
+const users = [
+  { id: 1, name: "Sam", role: "student" },
+  { id: 2, name: "Alex", role: "admin" },
+  { id: 3, name: "Samira", 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); // Sam, Samira
+console.log(result.pagination);
+```
+
+## API
+
+### `paginate(data, options)`
+
+Options are `page` (default `1`), `limit` (default `10`, maximum `100`), `filters` (exact matches; all must match), `search` (`{ query, fields }`, case-insensitive substring match), `sortBy` (property name), and `order` (`"asc"` or `"desc"`, default `"asc"`). Processing order is filtering, searching, sorting, then pagination. Inputs are not mutated. An out-of-range page returns an empty `data` array; empty input has `totalPages: 0`.
+
+Result shape:
+
+```js
+{
+  data: [],
+  pagination: {
+    page: 1, limit: 10, totalItems: 0, totalPages: 0,
+    hasNextPage: false, hasPreviousPage: false
+  }
+}
+```
+
+### Helpers
+
+- `filterData(data, filters)` returns items that exactly match every filter.
+- `searchData(data, query, fields)` searches selected properties. A blank query returns a shallow copy of the input array.
+- `sortData(data, field, order)` returns a sorted copy; numbers compare numerically and other values compare as case-insensitive strings. Missing values sort last in ascending order.
+- `validateQuery(options)` checks pagination and sorting options and returns normalized `{ page, limit, order }` values.
+
+Invalid arrays, options, page values, limits, orders, and search configurations throw `TypeError` or `RangeError` with a descriptive message.
+
+## Express example
+
+```js
+import express from "express";
+import { paginate } from "pagecraft";
+
+const app = express();
+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 });
+  }
+});
+```
+
+## Development
+
+```sh
+npm test
+npm pack
+```
+
+Tests use Node's built-in test runner. PageCraft only operates on arrays already in memory; use database-level queries for large datasets.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@sambuddha_npm_dev/pagecraft",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "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",
+  "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");
+}