@dephub/slug 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2025 Estarlin R
+
+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,201 @@
+# @dephub/slug 🔤
+
+> URL-friendly slug generator with semantic comparison and validation. Convert strings to clean slugs with full Unicode support.
+
+[![NPM version](https://img.shields.io/npm/v/@dephub/slug.svg?style=flat)](https://npmjs.org/package/@dephub/slug)
+[![ESM-only](https://img.shields.io/badge/ESM-only-brightgreen?style=flat)](https://nodejs.org/)
+[![Node.js version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+
+---
+
+## Features ✨
+
+- 🎯 **Simple API** - `slug()`, `isSlug()`, `compare()`
+- 🔒 **Type Safe** - Full TypeScript support with zero configuration
+- 🌍 **Unicode Support** - Handles accented characters and diacritics
+- 🛠️ **Dual Interface** - Use as CLI tool or programmatic API
+- ⚡ **Lightweight** - Zero dependencies, focused functionality
+- 🔧 **Configurable** - Custom separators, case handling, and fallbacks
+
+---
+
+## Installation 📲
+
+```bash
+npm install @dephub/slug
+# or
+pnpm add @dephub/slug
+# or
+yarn add @dephub/slug
+```
+
+---
+
+## Usage 🎉
+
+### CLI Usage
+
+```bash
+# Generate slugs
+slug generate "Hello World!"
+# Output: hello-world
+
+slug generate "Café & Bar" --separator "_"
+# Output: cafe_bar
+
+# Validate slugs
+slug validate "valid-slug-123"
+# Output: ✅ Valid slug format
+
+slug validate "Invalid Slug!"
+# Output: ❌ Invalid slug format
+
+# Compare strings
+slug compare "Café au lait" "cafe-au-lait"
+# Output: ✅ Strings are equivalent when slugified
+```
+
+### Programmatic Usage
+
+```typescript
+import { slug, isSlug, compare } from '@dephub/slug';
+
+// Basic slug generation
+slug('  Héllo Wörld!!!  '); // "hello-world"
+
+// Custom options
+slug('Hello World', { separator: '_' }); // "hello_world"
+slug('Hello World', { lowercase: false }); // "Hello-World"
+slug('###', { fallback: 'home' }); // "home"
+
+// Validation
+isSlug('valid-slug-name'); // true
+isSlug('Invalid Slug!'); // false
+
+// Semantic comparison
+compare('Café au lait', 'cafe-au-lait'); // true
+compare('user-profile', 'user_profile'); // false
+```
+
+### Advanced Examples
+
+```typescript
+// SEO-friendly URLs
+const title = 'My Awesome Blog Post!';
+const urlSlug = slug(title); // "my-awesome-blog-post"
+
+// Username normalization
+const username = slug(userInput, { separator: '_' });
+if (!isSlug(username)) {
+  throw new Error('Invalid username format');
+}
+
+// Database lookup with semantic comparison
+function findProduct(name: string) {
+  return products.find((product) => compare(product.name, name));
+}
+```
+
+---
+
+## API Reference 📚
+
+### `slug(str, options?)`
+
+Convert string to URL-friendly slug.
+
+**Parameters:**
+
+- `str` (string) - Input string to convert
+- `options` (SlugOptions) - Configuration options
+  - `separator` (string) - Character to replace spaces (default: `'-'`)
+  - `lowercase` (boolean) - Convert to lowercase (default: `true`)
+  - `fallback` (string) - Fallback if result empty (default: `'default-slug'`)
+
+**Returns:** `string`
+
+**Throws:** `TypeError` if input is not a string
+
+### `isSlug(str)`
+
+Check if string matches valid slug format (lowercase, hyphens, alphanumeric).
+
+**Parameters:**
+
+- `str` (string) - String to validate
+
+**Returns:** `boolean`
+
+### `compare(a, b, options?)`
+
+Compare two strings by their slugified versions.
+
+**Parameters:**
+
+- `a` (string) - First string to compare
+- `b` (string) - Second string to compare
+- `options` (SlugOptions) - Slug configuration options
+
+**Returns:** `boolean`
+
+---
+
+## CLI Commands
+
+### `slug generate <input>`
+
+Convert string to URL-friendly slug.
+
+**Options:**
+
+- `--separator` - Separator character (default: "-")
+- `--no-lowercase` - Keep original case
+- `--fallback` - Fallback text if result is empty
+
+### `slug validate <input>`
+
+Check if string is valid slug format.
+
+### `slug compare <first> <second>`
+
+Compare two strings by slugified versions.
+
+**Options:**
+
+- `--separator` - Separator character
+- `--no-lowercase` - Keep original case
+
+---
+
+## Integration Examples
+
+### With File System
+
+```typescript
+import { slug } from '@dephub/slug';
+import { writeFile } from '@dephub/write';
+
+async function createSluggedFile(content: string, filename: string) {
+  const sluggedName = slug(filename);
+  await writeFile(`./${sluggedName}.txt`, content);
+}
+```
+
+### With Configuration
+
+```typescript
+import { slug, compare } from '@dephub/slug';
+import { log } from '@dephub/log';
+
+const categoryName = 'User Settings';
+const normalized = slug(categoryName, { separator: '_' });
+log(`Category: ${normalized}`); // "user_settings"
+```
+
+---
+
+## License 📄
+
+MIT License – see [LICENSE](LICENSE) for details.
+
+**Author:** Estarlin R ([estarlincito.com](https://estarlincito.com))

package/dist/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { cli as a } from "@dephub/cli";
+import { log as l, error as n, success as c } from "@dephub/log";
+import { compare as p } from "./core/compare.js";
+import { slug as m } from "./core/slug.js";
+import { isSlug as g } from "./core/valid.js";
+import { name as u, version as f, description as d } from "./utils/pkg.js";
+a.name(u.split("/")[1] ?? "slug").version(f).description(d);
+a.command("generate", "Convert string to URL-friendly slug").argument("<input>", "Input string to convert").option("--separator", 'Separator character (default: "-")').flag("--no-lowercase", "Keep original case").option("--fallback", "Fallback text if result is empty").action(({ args: r, options: e, flags: o }) => {
+  const [s] = r;
+  try {
+    const t = {
+      fallback: e.fallback,
+      lowercase: o.lowercase,
+      separator: e.separator
+    }, i = m(s, t);
+    l(i);
+  } catch (t) {
+    n(t.message), process.exit(1);
+  }
+});
+a.command("validate", "Check if string is valid slug format").argument("<input>", "String to validate").action(({ args: r }) => {
+  const [e] = r;
+  g(e) ? c("Valid slug format") : (n("Invalid slug format"), process.exit(1));
+});
+a.command("compare", "Compare two strings by slugified versions").argument("<first>", "First string to compare").argument("<second>", "Second string to compare").option("--separator", "Separator character").flag("--no-lowercase", "Keep original case").action(({ args: r, options: e, flags: o }) => {
+  const [s, t] = r, i = {
+    lowercase: o.lowercase,
+    separator: e.separator
+  };
+  p(s, t, i) ? c("Strings are equivalent when slugified") : (n("Strings are different when slugified"), process.exit(1));
+});
+await a.run();

package/dist/core/compare.d.ts

@@ -0,0 +1,9 @@
+import { SlugOptions } from './slug.js';
+/**
+ * Compare two strings by their slugified versions
+ * @param a - First string to compare
+ * @param b - Second string to compare
+ * @param options - Slug options for comparison
+ * @returns True if slugified strings are equal
+ */
+export declare const compare: (a: string, b: string, options?: SlugOptions) => boolean;

package/dist/core/compare.js

@@ -0,0 +1,5 @@
+import { slug as m } from "./slug.js";
+const p = (o, c, r = {}) => m(o, r) === m(c, r);
+export {
+  p as compare
+};

package/dist/core/slug.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Convert string to URL-friendly slug
+ */
+export interface SlugOptions {
+    separator?: string;
+    lowercase?: boolean;
+    fallback?: string;
+}
+/**
+ * Convert string to URL-friendly slug
+ * @param str - Input string to convert
+ * @param options - Slug configuration options
+ * @returns URL-friendly slug string
+ * @throws {TypeError} If input is not a string
+ */
+export declare const slug: (str: string, options?: SlugOptions) => string;

package/dist/core/slug.js

@@ -0,0 +1,13 @@
+const o = (r, t = {}) => {
+  if (typeof r != "string") throw new TypeError("Input must be string");
+  const {
+    separator: a = "-",
+    lowercase: l = !0,
+    fallback: s = "default-slug"
+  } = t;
+  let e = r.normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-zA-Z0-9\s]/g, "").trim().replace(/\s+/g, a);
+  return l && (e = e.toLowerCase()), e || s;
+};
+export {
+  o as slug
+};

package/dist/core/valid.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Check if string matches valid slug format
+ * @param str - String to validate
+ * @returns True if string is valid slug format
+ */
+export declare const isSlug: (str: string) => boolean;

package/dist/core/valid.js

@@ -0,0 +1,4 @@
+const s = (t) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(t);
+export {
+  s as isSlug
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { compare } from './core/compare.js';
+export { slug, type SlugOptions } from './core/slug.js';
+export { slug as default } from './core/slug.js';
+export { isSlug } from './core/valid.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+import { compare as e } from "./core/compare.js";
+import { slug as l, slug as m } from "./core/slug.js";
+import { isSlug as s } from "./core/valid.js";
+export {
+  e as compare,
+  l as default,
+  s as isSlug,
+  m as slug
+};

package/dist/package.json.js

@@ -0,0 +1,11 @@
+const n = "@dephub/slug", o = "1.0.0", s = "URL-friendly slug generator with semantic comparison and validation", t = {
+  name: n,
+  version: o,
+  description: s
+};
+export {
+  t as default,
+  s as description,
+  n as name,
+  o as version
+};

package/dist/utils/pkg.d.ts

@@ -0,0 +1 @@
+export declare const version: string, name: string, description: string;

package/dist/utils/pkg.js

@@ -0,0 +1,7 @@
+import o from "../package.json.js";
+const { version: e, name: i, description: n } = o ?? {};
+export {
+  n as description,
+  i as name,
+  e as version
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@dephub/slug",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "URL-friendly slug generator with semantic comparison and validation",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "bin": {
+    "slug": "./dist/cli.js"
+  },
+  "keywords": [
+    "slug",
+    "url",
+    "seo",
+    "string",
+    "normalize",
+    "comparison",
+    "validation",
+    "typescript",
+    "nodejs",
+    "dephub"
+  ],
+  "author": {
+    "name": "Estarlin R",
+    "email": "dev@estarlincito.com",
+    "url": "https://estarlincito.com"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/dephubjs/slug#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dephubjs/slug.git",
+    "directory": "packages/slug"
+  },
+  "bugs": {
+    "url": "https://github.com/dephubjs/slug/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dephub/cli": "^1.0.0",
+    "@dephub/log": "^1.0.0"
+  },
+  "scripts": {
+    "release": "pnpm publish",
+    "check-types": "tsc --noEmit --skipLibCheck",
+    "lint": "lint . --max-warnings 0",
+    "lint:fix": "lint . --fix",
+    "clean": "rm -rf dist",
+    "build": "vite build",
+    "dev": "vite build -w --mode development"
+  }
+}