feat: add pathnorm & pathnorm/posix + update README.md

Author: ashuvssut

README.md

@@ -1,31 +1,17 @@
-# NPM package template
+# pathnorm
 
-## Development
-
-- Install dependencies: `yarn`
-- Run development server + build package on changes: `yarn dev`
-  - Check `./package.json` for `dev` script. It runs dev commands for docusaurus and package concurrently.
-  - Run only docusaurus dev server: `yarn workspace docs start`
-  - Run only package build: `yarn workspace your-package-name dev`
-    - Package is pre-configured to build out 2 dist paths:
-      - `dist/index.*js` for vanilla JS exports
-      - `dist/react.*js` for React exports
-    - Docs has an example of importing an example `addNumber` export from `your-package-name` package in `getting-started.mdx`
+Normalize and join path/URL segments. Full Win32, UNC, POSIX, and URL support.
 
-## Configure package and its deployment on NPM
+Read the [`README.md`](./package/README.md) documentation for more details.
 
-- Replace all instances of `your-package-name` with your package name
-- Replace all instances of `your-org` with your GitHub org name / your username
-- Required Settings in Github Repo Settings:
-  - Enable Permission: Allow GitHub Actions to create and approve pull requests: <https://github.com/changesets/changesets/discussions/1090>
-  - Add `NPM_TOKEN` to your Repo Actions Secrets.
-
-## Deploy Docusaurus on GitHub pages
+## Development
 
-- Set GitHub Pages source to "GitHub Actions"
-  - Go to Settings -> Pages section -> Build and deployment -> Source: GitHub Actions
+```sh
+yarn install
+yarn build
+yarn test
+```
 
-## Issues
+## Contributing
 
-- Is `changeset` unable to publish?
-  - <https://github.com/changesets/action/issues/98#issuecomment-2546826646>
+Contributions are welcome! Please open an issue or submit a pull request.

package.json

@@ -5,7 +5,9 @@
   "scripts": {
     "publish": "yarn changeset publish",
     "version": "yarn changeset",
-    "dev": "yarn workspace your-package-name dev"
+    "dev": "yarn workspace pathnorm dev",
+    "build": "yarn workspace pathnorm build",
+    "test": "yarn workspace pathnorm-test test"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.4",
@@ -15,7 +17,7 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },
-  "author": "Author of your-package-name",
+  "author": "Ashutosh Khanduala <https://github.com/ashuvssut>",
   "license": "MIT",
   "workspaces": [
     "package"

package/README.md

@@ -1,3 +1,150 @@
-# your-package-name
+# pathnorm
 
-Package Description
+Normalize and join path or URL segments into a single clean string.
+
+- Zero dependencies
+- Dual CJS + ESM build
+- Full TypeScript support
+- Tree-shakeable
+
+## Installation
+
+```sh
+npm install pathnorm
+# or
+yarn add pathnorm
+# or
+pnpm add pathnorm
+```
+
+## Two Entry Points
+
+| Import | Win32 | UNC | Namespace | URLs | POSIX |
+|---|---|---|---|---|---|
+| `pathnorm` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `pathnorm/posix` | ❌ | ❌ | ❌ | ✅ | ✅ |
+
+Use `pathnorm/posix` in browser or web server contexts where Win32 paths will never appear — it's lighter and purpose-built for URLs and POSIX paths.
+
+---
+
+## `pathnorm`
+
+Exports `np` and `unixNp`.
+
+```ts
+import { np, unixNp } from 'pathnorm'
+```
+
+### `np(...parts)`
+
+Joins and normalizes path or URL segments. Detects and handles URLs, POSIX paths, Win32 drive letters, UNC paths, and Win32 namespace paths automatically.
+
+```ts
+import { np } from 'pathnorm'
+// URLs
+np("https://abc.def//212/", "dw//we", "23123")
+// → "https://abc.def/212/dw/we/23123"
+
+np("exp://abc.def//212/", "dw/we")
+// → "exp://abc.def/212/dw/we"
+
+// POSIX
+np("abc.def//212/", "dwwe", "23123")
+// → "abc.def/212/dwwe/23123"
+
+np("foo//bar", "/baz")
+// → "/foo/bar/baz"
+
+np("/foo//bar", "baz")
+// → "/foo/bar/baz"
+
+// Win32 drive letter
+np("C:\\foo\\\\bar", "baz")
+// → "C:\foo\bar\baz"
+
+// UNC
+np("\\\\server\\share\\\\folder", "file.txt")
+// → "//server/share/folder/file.txt"
+
+// Win32 namespace
+np("\\\\?\\C:\\foo\\\\bar", "baz")
+// → "//?/C:/foo/bar/baz"
+
+// Mixed slashes in Win32
+np("C:\\foo//bar\\\\baz")
+// → "C:\foo\bar\baz"
+```
+
+### `unixNp(...parts)`
+
+Like `np`, but always returns a Unix-style path. Useful when working with Win32 paths but the consumer expects forward slashes.
+
+```ts
+import { unixNp } from 'pathnorm'
+unixNp("C:\\foo\\\\bar", "baz")
+// → "C:/foo/bar/baz"
+
+unixNp("\\\\server\\share\\\\folder", "file.txt")
+// → "//server/share/folder/file.txt"
+
+unixNp("\\\\?\\C:\\foo\\\\bar", "baz")
+// → "//?/C:/foo/bar/baz"
+
+// POSIX paths pass through unchanged
+unixNp("/foo//bar", "baz")
+// → "/foo/bar/baz"
+```
+
+---
+
+## `pathnorm/posix`
+
+Exports `np`. No Win32 support — ideal for browser and web server environments.
+
+```ts
+import { np } from 'pathnorm/posix'
+```
+
+### `np(...parts)` (POSIX + URLs)
+
+Joins and normalizes URL or POSIX path segments.
+
+```ts
+import { np } from 'pathnorm/posix'
+// URLs
+np("https://abc.def//212/", "dw//we", "23123")
+// → "https://abc.def/212/dw/we/23123"
+
+np("exp://abc.def//212/", "dw/we")
+// → "exp://abc.def/212/dw/we"
+
+// POSIX
+np("abc.def//212/", "dwwe", "23123")
+// → "abc.def/212/dwwe/23123"
+
+np("foo//bar", "/baz")
+// → "/foo/bar/baz"
+
+np("/foo//bar", "baz")
+// → "/foo/bar/baz"
+
+// Typical web usage
+np(window.location.origin, "/api/proxy//betterauth")
+// → "https://myapp.com/api/proxy/betterauth"
+```
+
+---
+
+## Behavior Notes
+
+- Only the **first** segment is checked for a URL scheme (`://`). Subsequent segments that look like URLs are treated as plain path parts.
+- Leading slashes are preserved if **any** segment introduces one.
+- Consecutive slashes (or backslashes in Win32 mode) are collapsed into one.
+- Trailing slashes are not preserved.
+
+```ts
+// Only first scheme is treated as prefix
+np("exp://", "sdfasdf", "abc.def//212/", "dw//we", "23123", "https://")
+// → "exp://sdfasdf/abc.def/212/dw/we/23123/https:/"
+```

package/package.json

@@ -1,28 +1,38 @@
 {
-  "name": "your-package-name",
+  "name": "pathnorm",
   "version": "0.0.0",
-  "description": "description of your-package-name",
+  "description": "Normalize and join path and URL segments. Supports URLs, POSIX paths, Win32 drive letters, UNC, and namespace paths.",
   "source": "src/index.ts",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
     },
-    "./react": {
-      "types": "./dist/react.d.ts",
-      "import": "./dist/react.mjs",
-      "require": "./dist/react.js"
+    "./posix": {
+      "import": {
+        "types": "./dist/posix.d.mts",
+        "default": "./dist/posix.mjs"
+      },
+      "require": {
+        "types": "./dist/posix.d.ts",
+        "default": "./dist/posix.js"
+      }
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "files": [
-    "**"
+    "dist"
   ],
   "scripts": {
     "dev:tsc": "tsc -w -p tsc.tsconfig.json",
@@ -33,13 +43,22 @@
     "lint": "yarn lint:tsc && yarn lint:biome",
     "format": "biome check --write ./src"
   },
-  "author": "Author of your-package-name",
+  "author": "Ashutosh Khanduala <https://github.com/ashuvssut>",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/your-org/your-package-name/issues"
+    "url": "https://github.com/stacknide/pathnorm/issues"
   },
-  "homepage": "https://github.com/your-org/your-package-name#readme",
-  "keywords": [],
+  "homepage": "https://github.com/stacknide/pathnorm#readme",
+  "keywords": [
+    "path",
+    "url",
+    "normalize",
+    "join",
+    "posix",
+    "win32",
+    "unc",
+    "cross-platform"
+  ],
   "devDependencies": {
     "@biomejs/biome": "2.4.4",
     "lefthook": "^2.1.1",