Added sanitize function, test cases, and we have a stable release

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @samocodes/s3-safe-key
 
+## 1.0.1
+
+### Patch Changes
+
+- Added sanitize function, test cases, and we have a stable release
+
 ## 0.1.0
 
 ### Minor Changes

README.md

@@ -1 +1,59 @@
-# Objects Keys Sanitizer
+# Object Keys Sanitizer 💉
+
+This utility provides a function to sanitize S3 keys by removing or replacing unsafe characters. It ensures that the keys only contain safe characters, defined as `A-Za-z0-9!-_.'()`.
+
+## Installation 📦
+
+To use this utility, you need to install this package.
+
+```bash
+npm install @samocodes/s3-safe-key
+pnpm add @samocodes/s3-safe-key
+yarn add @samocodes/s3-safe-key
+bun add @samocodes/s3-safe-key
+```
+
+## Usage 🧰
+
+### Importing the Function
+
+To use the `sanitize` function, first import it into your project:
+
+```typescript
+import { sanitize } from "@samocodes/s3-safe-key";
+```
+
+`sanitize(key: string, options: Options): string`
+
+- key (string): The key to be sanitized.
+- options (Optional): An object with the following optional properties:
+  - replacement (string): The string to replace unsafe characters with. Default is an empty string ("").
+  - strict (boolean): If true, includes \* and / as safe characters. Default is false.
+
+Returns:
+
+A sanitized string with only safe characters. If the resulting string is empty, it returns a random hexadecimal string of 10 bytes.
+
+## Example
+
+```typescript
+import { sanitize } from "@samocodes/s3-safe-key";
+
+const key = "/example/key/with unsafe*characters?";
+const options = { replacement: "_", strict: true };
+
+const sanitizedKey = sanitize(key, options);
+
+console.log(sanitizedKey); // Output: example_key_with_unsafe_characters_
+```
+
+## Contributing 🤝
+
+Feel free to fork the repository and submit pull requests. For major changes, please open an issue first to discuss what you would like to change.
+
+## License 📜
+
+This project is licensed under the MIT License.
+
+This README covers the usage, API documentation and installation guide.
+`https://github.com/samocodes/s3-safe-key.git`

index.test.ts

@@ -0,0 +1,19 @@
+import {sanitize} from '.'
+
+test('sanitize key', () => {
+  const key = "/example/key/with unsafe*characters?";
+  const sanitizedKey = sanitize(key);
+  expect(sanitizedKey).toBe("examplekeywithunsafecharacters");
+});
+
+test('sanitize key with replacement', () => {
+  const key = "/example/key/with unsafe*characters?";
+  const sanitizedKey = sanitize(key, { replacement: "_" });
+  expect(sanitizedKey).toBe("example_key_with_unsafe_characters_");
+});
+
+test('sanitize key with strict mode', () => {
+  const key = "/example/key/with unsafe*characters?";
+  const sanitizedKey = sanitize(key, { replacement: "_", strict: true });
+  expect(sanitizedKey).toBe("example/key/with_unsafe*characters_");
+});

index.ts

@@ -1,3 +1,29 @@
-export function add(a: number, b: number): number {
-  return a + b;
+import { randomBytes } from "crypto";
+
+const BASE_SAFE_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!-_.'()";
+const STRICT_ADDITIONS = "*/";
+
+export type Options = Partial<{
+  replacement: string;
+  strict: boolean;
+}>;
+
+export function sanitize(key: string, options?: Options): string {
+  if (typeof key !== "string") throw new Error("key must be a string");
+
+  const replacement = options?.replacement ?? "";
+
+  const safeChars = new Set(BASE_SAFE_CHARS + (options?.strict ? STRICT_ADDITIONS : ""));
+
+  let sanitizedKey = "";
+
+  // Start from index 1 if key starts with '/'
+  let startIndex = key.startsWith("/") ? 1 : 0;
+
+  for (let i = startIndex; i < key.length; i++) {
+    const char = key[i] || "";
+    sanitizedKey += safeChars.has(char) ? char : replacement;
+  }
+
+  return sanitizedKey || randomBytes(10).toString("hex");
 }

jest.config.js

@@ -0,0 +1,5 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+};

package.json

@@ -1,20 +1,25 @@
 {
   "name": "@samocodes/s3-safe-key",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "description": "Package that sanitizes s3 object keys",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsup index.ts --format cjs,esm --dts",
     "lint": "tsc",
-    "release": "pnpm run build && changeset publish --public"
+    "release": "pnpm run build && changeset publish --public",
+    "test": "jest"
   },
   "keywords": [],
   "author": "Samir <samirdiff@proton.me>",
   "license": "ISC",
   "devDependencies": {
     "@changesets/cli": "^2.27.5",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.14.2",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.4",
     "tsup": "^8.1.0",
     "typescript": "^5.4.5"
   },