@javelina/npmhelpers 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jack-npmhelpers 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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @javelina/npmhelpers
+
+一组日常使用的 JavaScript 小工具函数集合。
+
+## 安装
+
+    npm install @javelina/npmhelpers
+
+## 使用
+
+```js
+import { slugify, chunked, flatten, truncate, sha256File } from "@javelina/npmhelpers";
+
+slugify("Hello, World!");        // 'hello-world'
+[...chunked([0, 1, 2, 3, 4], 2)] // [[0, 1], [2, 3], [4]]
+flatten([[1, 2], [3, 4]]);       // [1, 2, 3, 4]
+truncate("a long sentence", 8);  // 'a long...'
+sha256File("some-file.bin");     // 'e3b0c442...'
+```
+
+## 命令行
+
+    npx npmhelpers slug "Hello, World!"   # hello-world
+    npx npmhelpers hash <file>            # 打印文件的 SHA-256 摘要
+
+## 提供的函数
+
+| 函数 | 说明 |
+|------|------|
+| `slugify(text)` | 把文本转换成 URL 安全的 slug |
+| `chunked(iterable, size)` | 把可迭代对象按固定大小分块 |
+| `flatten(nested)` | 展平一层嵌套的数组 |
+| `truncate(text, length)` | 截断文本并追加后缀 |
+| `sha256File(path)` | 计算文件的 SHA-256 摘要 |
+
+## 二进制资源
+
+二进制文件统一放在 `asset/` 目录下，发布 npm 时会随包一起发布。
+
+## 发布
+
+包名是 scoped 包（`@javelina/npmhelpers`），已在 `package.json` 中配置 `publishConfig.access = "public"`，会作为公开包发布：
+
+    npm login
+    npm publish
+
+## 开发
+
+    npm test

package/asset/README.md

@@ -0,0 +1,17 @@
+# asset
+
+这个文件夹用于存放二进制文件（例如 `.wasm`、`.bin`、图片、模型文件、字体等）。
+
+- 放在这里的文件会被一起发布到 npm（`package.json` 的 `files` 字段已经包含 `asset`）。
+- 发布前请确认要发布的二进制文件都放在这个目录下，不要放在其他地方。
+- 较大的二进制文件建议先在 npm 上确认包体积限制，必要时改用 CDN 或按需下载。
+
+示例：
+
+    asset/
+      fonts/
+        example.woff2
+      wasm/
+        helper.wasm
+      bin/
+        tool.exe

package/bin/npmhelpers.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.js";
+
+process.exitCode = main();

package/index.js

@@ -0,0 +1 @@
+export { chunked, flatten, sha256File, slugify, truncate } from "./src/helpers.js";

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@javelina/npmhelpers",
+  "version": "0.1.0",
+  "description": "A small collection of everyday JavaScript helper utilities.",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "bin": {
+    "npmhelpers": "./bin/npmhelpers.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "index.js",
+    "src",
+    "bin",
+    "asset"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "helpers",
+    "utilities",
+    "text",
+    "files",
+    "hashing"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">10"
+  }
+}

package/src/cli.js

@@ -0,0 +1,44 @@
+/** Command-line entry point for npmhelpers. */
+
+import { sha256File, slugify } from "./helpers.js";
+
+const USAGE = [
+  "usage: npmhelpers <command>",
+  "",
+  "commands:",
+  "  slug <text>   Convert text into a URL-safe slug",
+  "  hash <file>   Print the SHA-256 digest of a file",
+].join("\n");
+
+/**
+ * @param {string[]} [argv]
+ * @returns {number}
+ */
+export function main(argv = process.argv.slice(2)) {
+  const [command, ...rest] = argv;
+
+  switch (command) {
+    case "slug": {
+      const text = rest.join(" ");
+      if (!text) {
+        console.error("usage: npmhelpers slug <text>");
+        return 2;
+      }
+      console.log(slugify(text));
+      return 0;
+    }
+    case "hash": {
+      const [path] = rest;
+      if (!path) {
+        console.error("usage: npmhelpers hash <file>");
+        return 2;
+      }
+      console.log(sha256File(path));
+      return 0;
+    }
+    default: {
+      console.error(USAGE);
+      return command ? 2 : 0;
+    }
+  }
+}

package/src/helpers.js

@@ -0,0 +1,88 @@
+/** Everyday helper functions. */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+const SEP_REGEX_SPECIALS = /[.*+?^${}()|[\]\\]/g;
+
+/**
+ * Convert text into a URL-safe slug.
+ * @param {string} text
+ * @param {string} [sep]
+ * @returns {string}
+ */
+export function slugify(text, sep = "-") {
+  const escapedSep = String(sep).replace(SEP_REGEX_SPECIALS, "\\$&");
+  return String(text)
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, sep)
+    .replace(new RegExp(`^${escapedSep}+|${escapedSep}+$`, "g"), "");
+}
+
+/**
+ * Yield successive chunks of `size` items from `iterable`.
+ * @template T
+ * @param {Iterable<T>} iterable
+ * @param {number} size
+ * @returns {Generator<T[], void, unknown>}
+ */
+export function* chunked(iterable, size) {
+  if (size <= 0) {
+    throw new RangeError("size must be positive");
+  }
+  /** @type {T[]} */
+  let batch = [];
+  for (const item of iterable) {
+    batch.push(item);
+    if (batch.length === size) {
+      yield batch;
+      batch = [];
+    }
+  }
+  if (batch.length > 0) {
+    yield batch;
+  }
+}
+
+/**
+ * Flatten one level of nesting.
+ * @template T
+ * @param {T[][]} nested
+ * @returns {T[]}
+ */
+export function flatten(nested) {
+  return nested.flat(1);
+}
+
+/**
+ * Truncate `text` to at most `length` characters, appending `suffix`.
+ * @param {string} text
+ * @param {number} length
+ * @param {string} [suffix]
+ * @returns {string}
+ */
+export function truncate(text, length, suffix = "...") {
+  if (length < 0) {
+    throw new RangeError("length must be non-negative");
+  }
+  const str = String(text);
+  if (str.length <= length) {
+    return str;
+  }
+  if (length <= suffix.length) {
+    return suffix.slice(0, length);
+  }
+  return str.slice(0, length - suffix.length) + suffix;
+}
+
+/**
+ * Return the hex SHA-256 digest of a file.
+ * @param {string} path
+ * @returns {string}
+ */
+export function sha256File(path) {
+  const data = readFileSync(path);
+  return createHash("sha256").update(data).digest("hex");
+}