@typescriptprime/securereq 1.0.0-build.2 → 1.0.1

package/README.md

@@ -1,145 +1,105 @@
-# @typescriptprime/parsing
+# SecureReq 🔐
 
-Lightweight helper utilities for parsing CLI-style arguments, implemented in TypeScript.
-
-This package provides two small helpers:
-
-- `PreProcessing` — trims `process.argv` to remove the node executable and optional script filename, returning the array of option tokens.
-- `PostProcessing` — parses the token list that looks like `--Name Value` into a typed options object and an array of positional arguments (everything after `--`).
+**SecureReq** is a lightweight TypeScript utility for making secure HTTPS requests with strict TLS defaults and typed response parsing.
 
 ---
 
-## 📦 Install
-
-```bash
-npm install @typescriptprime/parsing
-```
+## 🚀 Quick Summary
 
-> [!NOTE]
-> This repo is authored as an ES module and fully typed with TypeScript.
+- **Small, dependency-light** wrapper around Node's `https` for typed responses and safer TLS defaults.
+- Defaults to **TLSv1.3**, Post Quantum Cryptography key exchange, a limited set of strongest ciphers, and a `User-Agent` header.
+- Supports typed response parsing: `JSON`, `String`, or raw `ArrayBuffer`.
 
 ---
 
-## Usage
-
-Import the helpers from the package and combine them to parse `process.argv`:
+## 📦 Installation
 
-```typescript
-import { PreProcessing, PostProcessing } from '@typescriptprime/parsing'
-
-async function Main(Argv: string[]) {
-  // Step 1: Trim the node executable and optional script path
-  const Filtered = PreProcessing(Argv)
-
-  // Step 2: Parse CLI-style parameters into an options object and positional arguments
-  const { Options, Positional } = await PostProcessing(Filtered)
-
-  console.log('Options:', Options)
-  console.log('Positional args:', Positional)
-}
-
-Main(process.argv)
+```bash
+npm install @typescriptprime/securereq
 ```
 
-### Naming Convention
-
-By default, `PostProcessing` converts parameter names into PascalCase using `es-toolkit` (so `--parameter-name` becomes `ParameterName`). You can supply a custom `NamingConvention` function via `IParsingOptions`:
-
-```typescript
-import * as ESToolkit from 'es-toolkit'
-
-await PostProcessing(argv, { NamingConvention: ESToolkit.camelCase })
-// or custom:
-await PostProcessing(argv, { NamingConvention: (s) => s.replace(/^--/, '') })
-```
+**Requirements:** Node.js >= 24
 
 ---
 
-## ⚡ Quick Examples
+## Usage Examples 🔧
 
-From `process.argv` in Node.js:
+Import and call the helper:
 
-```typescript
-const Argv = ['/usr/local/bin/node', '/path/to/script.js', '--enable-feature', '--parameter', 'value', '--', 'positional1', 'positional2']
-
-const Tokens = PreProcessing(Argv)
-// tokens === ['--enable-feature', '--parameter', 'value', '--', 'positional1', 'positional2']
+```ts
+import { HTTPSRequest } from '@typescriptprime/securereq'
 
-const { Options, Positional } = await PostProcessing(Tokens)
-// Options === { EnableFeature: true, Parameter: 'value' }
-// Positional === ['positional1', 'positional2']
-```
+// JSON (auto-detected by .json path) or explicit
+const url = new URL('https://api64.ipify.org?format=json')
+const res = await HTTPSRequest(url)
+console.log(res.StatusCode) // number
+console.log(res.Body) // ArrayBuffer or parsed JSON depending on `ExpectedAs` and URL
 
-Boolean flags example:
+// Force string
+const html = await HTTPSRequest(new URL('https://www.example.com/'), { ExpectedAs: 'String' })
+console.log(typeof html.Body) // 'string'
 
-```ts
-const Tokens = PreProcessing(['/usr/bin/node', '/script.js', '--flag', '--other', 'value'])
-// tokens === ['--flag', '--other', 'value']
-const { Options } = await PostProcessing(Tokens)
-// Options === { Flag: true, Other: 'value' }
+// Force ArrayBuffer
+const raw = await HTTPSRequest(new URL('https://example.com/'), { ExpectedAs: 'ArrayBuffer' })
+console.log(raw.Body instanceof ArrayBuffer)
 ```
 
 ---
 
-## API
-
-- `PreProcessing(argv: typeof process.argv): string[]`
-  - Removes the node executable and optional file argument and returns the tokens starting at the first option.
+## API Reference 📚
 
-- `PostProcessing<I extends JSONValue>(Args: string[], FuncOptions?: IParsingOptions): Promise<{ Options: I, Positional: string[] }>`
-  - Converts `--key value` pairs into a typed `Options` object; flags without values are treated as `true`.
-  - Stops parsing options when it hits `--` and returns the rest as `Positional` arguments.
+### HTTPSRequest(Url, Options?)
 
-### Types
+- `Url: URL` — Target URL (must be an instance of `URL`).
+- `Options?: HTTPSRequestOptions` — Optional configuration object.
 
-- `JSONValue`, `JSONObject`, `JSONArray`, `JSONPrimitive` — standard JSON type helpers
-- `IParsingOptions` — currently supports:
-  - `NamingConvention?: (PropertyName: string) => string | Promise<string>`
+Returns: `Promise<HTTPSResponse<T>>` where `T` is determined by `ExpectedAs`.
 
----
+Throws:
+- `TypeError` when `Url` is not a `URL` instance.
+- `Error` on request failure or on failed response parsing (e.g., invalid JSON).
 
-## Scripts
+### HTTPSRequestOptions
 
-- `npm run build` — runs: `esbuild` to bundle the compiled JS and TypeScript compiler to emit declarations.
-- `npm test` — runs AVA tests.
-- `npm run lint` — runs ESLint checks.
+Fields:
+- `TLS?: { IsHTTPSEnforced?: boolean, MinTLSVersion?: 'TLSv1.2'|'TLSv1.3', MaxTLSVersion?: 'TLSv1.2'|'TLSv1.3', Ciphers?: string[], KeyExchanges?: string[] }`
+  - Defaults: `IsHTTPSEnforced: true`, both Min and Max set to `TLSv1.3`, a small secure cipher list and key exchange choices.
+  - When `IsHTTPSEnforced` is `true`, a non-`https:` URL will throw.
+- `HttpHeaders?: Record<string,string>` — Custom headers. A `User-Agent` header is provided by default.
+- `ExpectedAs?: 'JSON'|'String'|'ArrayBuffer'` — How to parse the response body.
 
-This project is published as an ES module. If you are developing locally, the following commands are useful:
+### HTTPSResponse
 
-- `npm run build:esbuild` — bundle with esbuild (JS output)
-- `npm run build:tsc` — emit TypeScript declarations only
+- `{ StatusCode: number, Headers: Record<string,string|string[]|undefined>, Body: T }`
 
-The package `exports` are configured in `package.json` so importing the default entry works with ESM loaders.
+Notes:
+- If `ExpectedAs` is omitted, a heuristic is used: `.json` → `JSON`, `.txt` → `String`, otherwise `ArrayBuffer`.
+- When `ExpectedAs` is `JSON`, the body is parsed and an error is thrown if parsing fails.
 
 ---
 
-## Tests
+## Security & Behavior Notes 🔐
 
-The `tests/` directory contains unit tests for both `PreProcessing` and `PostProcessing` with AVA. They include:
+- Strict TLS defaults lean on **TLSv1.3** and a reduced cipher list to encourage secure transport out of the box.
+- TLS options are forwarded to Node's HTTPS layer (`minVersion`, `maxVersion`, `ciphers`, `ecdhCurve`).
+- The library uses `zod` for runtime validation of options.
 
-- PreProcessing: removes node executable and file name using different `process.argv` shapes
-- PostProcessing: parsing single/two parameters, boolean flags, and the `--` positional argument separator.
+---
 
-Run tests with:
+## Development & Testing 🧪
 
-```bash
-npm test
-```
+- Build: `npm run build` (uses `esbuild` + `tsc` for types)
+- Test: `npm test` (uses `ava`)
+- Lint: `npm run lint`
 
 ---
 
-## Project Layout
+## Contributing
 
-- `sources/` — TypeScript source files for the package
-  - `index.ts` — entry exports
-  - `preprocessing/index.ts` — `PreProcessing` implementation
-  - `postprocessing/index.ts` — `PostProcessing` implementation
-  - `types.ts` — JSON types and `IParsingOptions`
-- `dist/` — build output (ignored in source control)
-- `tests/` — unit tests using AVA
+Contributions, bug reports and PRs are welcome — please follow the repository's contribution guidelines.
 
 ---
 
 ## License
 
-Licensed under the Apache-2.0 license — see `LICENSE` for details.
+This project is licensed under the **Apache-2.0** License. See the `LICENSE` file for details.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@typescriptprime/securereq",
   "type": "module",
-  "version": "1.0.0-build.2",
+  "version": "1.0.1",
   "description": "SecureReq is a lightweight utility for making secure HTTP requests, implemented in TypeScript",
   "keywords": [
     "https",