@typescriptprime/securereq 1.0.0 → 1.1.0

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/dist/index.js

@@ -6,6 +6,7 @@ var __export = (target, all) => {
 
 // sources/index.ts
 import * as HTTPS from "node:https";
+import * as HTTP2 from "node:http2";
 import * as TLS from "node:tls";
 import * as Process from "node:process";
 
@@ -4241,6 +4242,7 @@ async function HTTPSRequest(Url, Options) {
       Ciphers: ["TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256"],
       KeyExchanges: ["X25519MLKEM768", "X25519"]
     },
+    HttpMethod: "GET",
     HttpHeaders: {
       "User-Agent": `node/${Process.version} ${Process.platform} ${Process.arch} workspace/false`
     }
@@ -4258,6 +4260,7 @@ async function HTTPSRequest(Url, Options) {
       KeyExchanges: array(string2()).optional()
     }).partial().optional(),
     HttpHeaders: record(string2(), string2()).optional(),
+    HttpMethod: _enum(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]).optional(),
     ExpectedAs: _enum(["JSON", "String", "ArrayBuffer"]).optional()
   }).parseAsync(Options ?? {});
   if (MergedOptions.TLS?.IsHTTPSEnforced && Url.protocol !== "https:") {
@@ -4274,7 +4277,8 @@ async function HTTPSRequest(Url, Options) {
       minVersion: MergedOptions.TLS?.MinTLSVersion,
       maxVersion: MergedOptions.TLS?.MaxTLSVersion,
       ciphers: MergedOptions.TLS?.Ciphers?.join(":"),
-      ecdhCurve: MergedOptions.TLS?.KeyExchanges?.join(":")
+      ecdhCurve: MergedOptions.TLS?.KeyExchanges?.join(":"),
+      method: MergedOptions.HttpMethod
     }, (Res) => {
       const Chunks = [];
       Res.on("data", (Chunk) => {
@@ -4311,7 +4315,116 @@ async function HTTPSRequest(Url, Options) {
   });
   return HTTPSResponse;
 }
+async function HTTPS2Request(Url, Options) {
+  const DefaultOptions = {
+    TLS: {
+      IsHTTPSEnforced: true,
+      MinTLSVersion: "TLSv1.3",
+      MaxTLSVersion: "TLSv1.3",
+      Ciphers: ["TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256"],
+      KeyExchanges: ["X25519MLKEM768", "X25519"]
+    },
+    HttpHeaders: {
+      "User-Agent": `node/${Process.version} ${Process.platform} ${Process.arch} workspace/false`
+    },
+    HttpMethod: "GET"
+  };
+  const MergedOptions = { ...DefaultOptions, ...Options ?? {} };
+  if (Url instanceof URL === false) {
+    throw new TypeError("Url must be an instance of URL");
+  }
+  await strictObject({
+    TLS: strictObject({
+      IsHTTPSEnforced: boolean2().optional(),
+      MinTLSVersion: _enum(["TLSv1.2", "TLSv1.3"]).optional(),
+      MaxTLSVersion: _enum(["TLSv1.2", "TLSv1.3"]).optional(),
+      Ciphers: array(string2().refine((Cipher) => TLS.getCiphers().map((C) => C.toLowerCase()).includes(Cipher.toLowerCase()))).optional(),
+      KeyExchanges: array(string2()).optional()
+    }).partial().optional(),
+    HttpHeaders: record(string2(), string2()).optional(),
+    ExpectedAs: _enum(["JSON", "String", "ArrayBuffer"]).optional(),
+    HttpMethod: _enum(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]).optional()
+  }).parseAsync(Options ?? {});
+  if (MergedOptions.TLS?.IsHTTPSEnforced && Url.protocol !== "https:") {
+    throw new Error("HTTPS is enforced, but the URL protocol is not HTTPS");
+  }
+  const ExpectedAs = Options?.ExpectedAs ?? (Url.pathname.endsWith(".json") ? "JSON" : Url.pathname.endsWith(".txt") ? "String" : "ArrayBuffer");
+  const HTTPSResponse = await new Promise((Resolve, Reject) => {
+    const NormalizedHeaders = Object.fromEntries(Object.entries(MergedOptions.HttpHeaders ?? {}).map(([Key, Value]) => [Key.toLowerCase(), Value]));
+    const HTTP2Session = HTTP2.connect(`https://${Url.hostname}${Url.port ? `:${Url.port}` : ""}`, {
+      createConnection: () => TLS.connect({
+        host: Url.hostname,
+        port: Number(Url.port || 443),
+        servername: Url.hostname,
+        minVersion: MergedOptions.TLS?.MinTLSVersion,
+        maxVersion: MergedOptions.TLS?.MaxTLSVersion,
+        ciphers: MergedOptions.TLS?.Ciphers?.join(":"),
+        ecdhCurve: MergedOptions.TLS?.KeyExchanges?.join(":"),
+        ALPNProtocols: ["h2"]
+      })
+    });
+    HTTP2Session.on("error", (Error2) => {
+      Reject(Error2);
+    });
+    const RequestHeaders = {
+      ":method": MergedOptions.HttpMethod,
+      ":path": Url.pathname + Url.search,
+      ":scheme": "https",
+      ":authority": Url.host,
+      ...NormalizedHeaders
+    };
+    const Request = HTTP2Session.request(RequestHeaders);
+    const Chunks = [];
+    let StatusCode = 0;
+    let ResponseHeaders = {};
+    Request.on("response", (Headers) => {
+      StatusCode = Number(Headers[":status"] ?? 0);
+      ResponseHeaders = Object.fromEntries(Object.entries(Headers).filter(([Key]) => !Key.startsWith(":")).map(([Key, Value]) => {
+        if (Array.isArray(Value)) {
+          return [Key, Value.map((Item) => Item?.toString())];
+        }
+        return [Key, Value?.toString()];
+      }));
+    });
+    Request.on("data", (Chunk) => {
+      Chunks.push(Chunk.buffer.slice(Chunk.byteOffset, Chunk.byteOffset + Chunk.byteLength));
+    });
+    Request.on("end", () => {
+      const BodyBuffer = ConcatArrayBuffers(Chunks);
+      let Body;
+      switch (ExpectedAs) {
+        case "JSON":
+          try {
+            Body = JSON.parse(new TextDecoder("utf-8").decode(BodyBuffer));
+          } catch (Error2) {
+            HTTP2Session.close();
+            return Reject(new Error2("Failed to parse JSON response body"));
+          }
+          break;
+        case "String":
+          Body = new TextDecoder("utf-8").decode(BodyBuffer);
+          break;
+        case "ArrayBuffer":
+          Body = BodyBuffer;
+          break;
+      }
+      HTTP2Session.close();
+      Resolve({
+        StatusCode,
+        Headers: ResponseHeaders,
+        Body
+      });
+    });
+    Request.on("error", (Error2) => {
+      HTTP2Session.close();
+      Reject(Error2);
+    });
+    Request.end();
+  });
+  return HTTPSResponse;
+}
 export {
+  HTTPS2Request,
   HTTPSRequest
 };
 //# sourceMappingURL=index.js.map