@8ms/helpers 3.0.13 → 3.0.15

package/AGENTS.md

@@ -0,0 +1,110 @@
+# AGENTS.md
+
+Guidelines for AI coding agents working in this repository.
+
+## What this repo is
+
+`@8ms/helpers` is an internal TypeScript utility library published as an npm package. It wraps common operations (string, number, date, array, HTTP, environment detection) and provides thin, lazily-initialised clients for third-party services (AWS, Google Cloud, 1Password, OpenAI, Snapchat, etc.). It is **not** an application — there is no server to run and no UI to render.
+
+## Build
+
+```bash
+npm run build    # tsdown — compiles src/**/*.ts to dist/ as ESM + CJS with .d.ts
+npm test         # jest
+npx tsc --noEmit # type-check only
+```
+
+Output goes to `dist/`. Never commit `dist/` changes manually; the build generates them.
+
+## Repository layout
+
+```
+src/
+  _class/          # BaseClass, BaseNamespace — all service clients extend BaseNamespace
+  api/             # HTTP helpers (get, post, deleteRequest) + ApiResponseClass
+  array/
+  boolean/
+  crud/
+  date/            # Luxon-based, UTC only
+  drizzle/         # ORM client (PlanetScale / MySQL / PostgreSQL)
+  environment/     # getEnvironment(), isVercel(), isDevelopment(), etc.
+  file/
+  geo/             # countries, languages data
+  googleCloud/     # BigQuery, Storage, Sheets, Google Ads
+  inngest/         # inngestState enum
+  json/
+  lodash/          # drop-in wrappers — no lodash runtime dependency
+  nextAuth/
+  nextJs/          # LazyLoad component, useAsyncEffect hook
+  number/
+  object/
+  onePassword/     # 1Password SDK client (server-only)
+  openAi/
+  prisma/
+  snapchat/
+  sorting/
+  stream/
+  string/
+  swr/             # SWR state helpers (client-only)
+  url/
+  util/            # defaultTo, getError, promiseChunks, sleep, etc.
+  webWorker/
+  xml/
+  aws/             # S3, SES, Lambda, EC2, SQS, SSM, Glue, ECS, CloudWatch
+  emsApi/          # internal 8MS API client
+```
+
+Server-only code lives in `<module>/server/`, client-only in `<module>/client/`. Do not import server modules from client entry points or vice versa.
+
+## Key patterns
+
+**Service clients all extend `BaseNamespace`.** They expose an async `init(config)` method and lazy-load their SDK inside it. Do not instantiate the underlying SDK client at the top of the file — follow the existing pattern of dynamic `import()` inside `init`.
+
+**`ApiResponseClass`** is the standard HTTP response wrapper used by all functions in `src/api/`. New HTTP helpers should return it and follow the existing IDLE/PENDING/SUCCESS/ERROR state pattern.
+
+**No bundling.** `tsdown` outputs unbundled files. Every source file maps to a dist file. Do not introduce barrel re-exports that would force consumers to load unrelated code.
+
+**Peer dependencies.** AWS SDK, Google Cloud SDK, Prisma, Drizzle, Next.js, React — all are peer deps. Never add them as direct dependencies. Import them only inside `init()` or behind a dynamic import so consumers who don't use that module pay no cost.
+
+**TypeScript target is ES2024, module resolution is `bundler`.** Use native ES features freely. No CommonJS patterns in source files.
+
+**No comments by default.** Only add a comment when the *why* is non-obvious (a workaround, a hidden constraint). Do not document what the code does — naming should do that.
+
+## Adding a new module
+
+1. Create `src/<name>/` with an `index.ts` re-exporting the public surface.
+2. If the module has a server and a client variant, use `src/<name>/server/` and `src/<name>/client/` subdirectories with their own `index.ts`.
+3. If the module wraps a third-party SDK, extend `BaseNamespace` and lazy-load the SDK inside `init()`.
+4. Do not add the SDK as a direct dependency — add it as a peer dependency in `package.json`.
+5. Export the new module from the relevant top-level entry point (`src/aws/server/index.ts`, etc.) or create a new one if the module stands alone.
+
+## Adding a new service method
+
+Follow the existing pattern in the relevant class. For example, when adding a method to `OnePassword`:
+- Update methods take the full item URL, fetch the item with `getItem(url)`, mutate it, then call `this.client.items.put(item)`.
+- Create methods take a vault URL (to extract `vaultId` via `getIdsFromUrl`) plus a `title` and content value.
+- Use `ItemCategory.SecureNote` for secure note items.
+
+## Testing
+
+Tests live alongside source as `*.test.ts`. Run with `npm test`. Coverage is collected but not enforced at a threshold — add tests for any pure utility functions you introduce. Service client methods (AWS, Google Cloud, etc.) are not tested; do not mock them.
+
+## Environment variables
+
+The library reads these at runtime — do not hardcode them:
+
+| Variable | Used by |
+| --- | --- |
+| `EMS_ENVIRONMENT` | `getEnvironment()` |
+| `NEXT_PUBLIC_EMS_ENVIRONMENT` | `getEnvironment()` in Next.js |
+| `VERCEL_GIT_COMMIT_REF` | `getEnvironment()` on Vercel |
+
+AWS and GCP credentials are passed explicitly via `init(config)` — the library does not read `AWS_*` or `GOOGLE_*` env vars directly.
+
+## What to avoid
+
+- Do not alter `tsconfig.json` or `tsdown.config.ts` without a clear reason — the build pipeline is intentional.
+- Do not add runtime dependencies that duplicate an existing peer dependency.
+- Do not use `any` except where the public API genuinely accepts arbitrary JSON (e.g. `setJsonNote`, `createJsonNote`).
+- Do not introduce default exports — everything is named.
+- Do not run `npm run build` as a validation step; use `npx tsc --noEmit` to type-check only.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/dist/drizzle/server/Drizzle.cjs

@@ -6,38 +6,38 @@ var Drizzle = class extends require__class_BaseNamespace.BaseNamespace {
 	init = async (config) => {
 		if (!this.client) {
 			let logger = void 0;
-			if (this.config.isDebug) {
+			if (true === config?.isDebug) {
 				const { DefaultLogger } = await import("drizzle-orm/logger");
 				logger = new DefaultLogger();
 			}
 			let casing = void 0;
-			if ("snake" === this.config?.casing) casing = "snake_case";
-			else if ("camel" === this.config?.casing) casing = "camelCase";
-			if (this.config.isPlanetScale) try {
+			if ("snake" === config?.casing) casing = "snake_case";
+			else if ("camel" === config?.casing) casing = "camelCase";
+			if (true === config?.isPlanetScale) try {
 				const { drizzle } = await import("drizzle-orm/planetscale-serverless");
 				this.client = drizzle({
 					casing,
-					connection: { url: this.config.url },
-					relations: this.config?.relations,
-					schema: this.config?.schema,
+					connection: { url: config?.url },
+					relations: config?.relations,
+					schema: config?.schema,
 					logger
 				});
 			} catch (e) {
 				throw new Error(`PlanetScale driver not installed - ${require_util_getError.getError(e)}`);
 			}
-			else if (this.config.isMysql) try {
+			else if (true === config?.isMysql) try {
 				const { drizzle } = await import("drizzle-orm/mysql2");
 				const pool = (await import("mysql2/promise")).createPool({
-					uri: this.config.url,
-					connectionLimit: this.config.pool?.max ?? 10,
-					idleTimeout: this.config.pool?.idleTimeoutMs ?? 3e4,
-					connectTimeout: this.config.pool?.connectTimeoutMs ?? 5e3,
+					uri: config.url,
+					connectionLimit: config.pool?.max ?? 10,
+					idleTimeout: config.pool?.idleTimeoutMs ?? 3e4,
+					connectTimeout: config.pool?.connectTimeoutMs ?? 5e3,
 					waitForConnections: true,
 					queueLimit: 0
 				});
 				this.client = drizzle(pool, {
-					schema: this.config.schema,
-					relations: this.config.relations,
+					schema: config.schema,
+					relations: config.relations,
 					casing,
 					logger,
 					mode: "default"
@@ -45,18 +45,18 @@ var Drizzle = class extends require__class_BaseNamespace.BaseNamespace {
 			} catch (e) {
 				throw new Error(`MySQL2 driver not installed - ${require_util_getError.getError(e)}`);
 			}
-			else if (this.config.isPostgres) try {
+			else if (true === config?.isPostgres) try {
 				const { drizzle } = await import("drizzle-orm/node-postgres");
 				const { Pool } = await import("pg");
 				const pool = new Pool({
-					connectionString: this.config.url,
-					max: this.config.pool?.max ?? 10,
-					idleTimeoutMillis: this.config.pool?.idleTimeoutMs ?? 3e4,
-					connectionTimeoutMillis: this.config.pool?.connectTimeoutMs ?? 5e3
+					connectionString: config.url,
+					max: config.pool?.max ?? 10,
+					idleTimeoutMillis: config.pool?.idleTimeoutMs ?? 3e4,
+					connectionTimeoutMillis: config.pool?.connectTimeoutMs ?? 5e3
 				});
 				this.client = drizzle(pool, {
-					schema: this.config.schema,
-					relations: this.config.relations,
+					schema: config.schema,
+					relations: config.relations,
 					casing,
 					logger
 				});
@@ -64,6 +64,7 @@ var Drizzle = class extends require__class_BaseNamespace.BaseNamespace {
 				throw new Error(`Postgres (pg) driver not installed - ${require_util_getError.getError(e)}`);
 			}
 			else throw new Error(`No database type configured`);
+			this.config = config;
 		}
 		return this;
 	};

package/dist/drizzle/server/Drizzle.mjs

@@ -5,38 +5,38 @@ var Drizzle = class extends BaseNamespace {
 	init = async (config) => {
 		if (!this.client) {
 			let logger = void 0;
-			if (this.config.isDebug) {
+			if (true === config?.isDebug) {
 				const { DefaultLogger } = await import("drizzle-orm/logger");
 				logger = new DefaultLogger();
 			}
 			let casing = void 0;
-			if ("snake" === this.config?.casing) casing = "snake_case";
-			else if ("camel" === this.config?.casing) casing = "camelCase";
-			if (this.config.isPlanetScale) try {
+			if ("snake" === config?.casing) casing = "snake_case";
+			else if ("camel" === config?.casing) casing = "camelCase";
+			if (true === config?.isPlanetScale) try {
 				const { drizzle } = await import("drizzle-orm/planetscale-serverless");
 				this.client = drizzle({
 					casing,
-					connection: { url: this.config.url },
-					relations: this.config?.relations,
-					schema: this.config?.schema,
+					connection: { url: config?.url },
+					relations: config?.relations,
+					schema: config?.schema,
 					logger
 				});
 			} catch (e) {
 				throw new Error(`PlanetScale driver not installed - ${getError(e)}`);
 			}
-			else if (this.config.isMysql) try {
+			else if (true === config?.isMysql) try {
 				const { drizzle } = await import("drizzle-orm/mysql2");
 				const pool = (await import("mysql2/promise")).createPool({
-					uri: this.config.url,
-					connectionLimit: this.config.pool?.max ?? 10,
-					idleTimeout: this.config.pool?.idleTimeoutMs ?? 3e4,
-					connectTimeout: this.config.pool?.connectTimeoutMs ?? 5e3,
+					uri: config.url,
+					connectionLimit: config.pool?.max ?? 10,
+					idleTimeout: config.pool?.idleTimeoutMs ?? 3e4,
+					connectTimeout: config.pool?.connectTimeoutMs ?? 5e3,
 					waitForConnections: true,
 					queueLimit: 0
 				});
 				this.client = drizzle(pool, {
-					schema: this.config.schema,
-					relations: this.config.relations,
+					schema: config.schema,
+					relations: config.relations,
 					casing,
 					logger,
 					mode: "default"
@@ -44,18 +44,18 @@ var Drizzle = class extends BaseNamespace {
 			} catch (e) {
 				throw new Error(`MySQL2 driver not installed - ${getError(e)}`);
 			}
-			else if (this.config.isPostgres) try {
+			else if (true === config?.isPostgres) try {
 				const { drizzle } = await import("drizzle-orm/node-postgres");
 				const { Pool } = await import("pg");
 				const pool = new Pool({
-					connectionString: this.config.url,
-					max: this.config.pool?.max ?? 10,
-					idleTimeoutMillis: this.config.pool?.idleTimeoutMs ?? 3e4,
-					connectionTimeoutMillis: this.config.pool?.connectTimeoutMs ?? 5e3
+					connectionString: config.url,
+					max: config.pool?.max ?? 10,
+					idleTimeoutMillis: config.pool?.idleTimeoutMs ?? 3e4,
+					connectionTimeoutMillis: config.pool?.connectTimeoutMs ?? 5e3
 				});
 				this.client = drizzle(pool, {
-					schema: this.config.schema,
-					relations: this.config.relations,
+					schema: config.schema,
+					relations: config.relations,
 					casing,
 					logger
 				});
@@ -63,6 +63,7 @@ var Drizzle = class extends BaseNamespace {
 				throw new Error(`Postgres (pg) driver not installed - ${getError(e)}`);
 			}
 			else throw new Error(`No database type configured`);
+			this.config = config;
 		}
 		return this;
 	};

package/dist/stream/server/sort.cjs

@@ -1,46 +1,43 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_stream = require("node:stream");
 //#region src/stream/server/sort.ts
-const Transform = require("stream").Transform;
 const batch = 15e3;
-/**
-* Batch sort stream without overloading the memory limit.
-* https://www.npmjs.com/package/fast-stream-sort
-*/
-var SortStreamer = class extends Transform {
+var SortStreamer = class extends node_stream.Transform {
+	a;
+	i;
+	k;
+	currentSize;
+	sortedArray;
+	comp;
 	constructor(options, comp) {
 		super(options);
 		this.a = new Array(batch);
 		this.i = 0;
 		this.k = 0;
 		this.currentSize = batch;
-		this.isDone = false;
 		this.sortedArray = void 0;
 		this.comp = comp;
 	}
 	_transform(data, _, callback) {
 		if (data) {
 			this.a[this.i++] = data;
-			if (this.i == this.currentSize) {
-				this.currentSize = this.currentSize * 2;
-				var tmp = new Array(this.currentSize);
-				for (var j = 0; j < this.i; j++) tmp[j] = this.a[j];
+			if (this.i === this.currentSize) {
+				this.currentSize *= 2;
+				const tmp = new Array(this.currentSize);
+				for (let j = 0; j < this.i; j++) tmp[j] = this.a[j];
 				this.a = tmp;
 			}
 		}
 		callback();
 	}
-	_flush() {
+	_flush(callback) {
 		this.sortedArray = this.a.slice(0, this.i).sort(this.comp);
-		this.fullflush();
-	}
-	fullflush() {
 		while (this.k < this.i) this.push(this.sortedArray[this.k++]);
-		this.push(null);
+		callback();
 	}
 };
 const sort = (comp, options) => {
-	options = options || { objectMode: true };
-	return new SortStreamer(options, comp);
+	return new SortStreamer(options ?? { objectMode: true }, comp);
 };
 //#endregion
 exports.sort = sort;

package/dist/stream/server/sort.d.cts

@@ -1,15 +1,17 @@
+import { Transform, TransformCallback, TransformOptions } from "node:stream";
+
 //#region src/stream/server/sort.d.ts
-declare const Transform: any;
-/**
- * Batch sort stream without overloading the memory limit.
- * https://www.npmjs.com/package/fast-stream-sort
- */
-declare class SortStreamer extends Transform {
-  constructor(options: any, comp: any);
-  _transform(data: any, _: any, callback: any): void;
-  _flush(): void;
-  fullflush(): void;
+declare class SortStreamer<T> extends Transform {
+  private a;
+  private i;
+  private k;
+  private currentSize;
+  private sortedArray;
+  private readonly comp;
+  constructor(options: TransformOptions, comp: (a: T, b: T) => number);
+  _transform(data: T, _: BufferEncoding, callback: TransformCallback): void;
+  _flush(callback: TransformCallback): void;
 }
-declare const sort: (comp: any, options: any) => SortStreamer;
+declare const sort: <T>(comp: (a: T, b: T) => number, options?: TransformOptions) => SortStreamer<T>;
 //#endregion
 export { sort };

package/dist/stream/server/sort.d.mts

@@ -1,15 +1,17 @@
+import { Transform, TransformCallback, TransformOptions } from "node:stream";
+
 //#region src/stream/server/sort.d.ts
-declare const Transform: any;
-/**
- * Batch sort stream without overloading the memory limit.
- * https://www.npmjs.com/package/fast-stream-sort
- */
-declare class SortStreamer extends Transform {
-  constructor(options: any, comp: any);
-  _transform(data: any, _: any, callback: any): void;
-  _flush(): void;
-  fullflush(): void;
+declare class SortStreamer<T> extends Transform {
+  private a;
+  private i;
+  private k;
+  private currentSize;
+  private sortedArray;
+  private readonly comp;
+  constructor(options: TransformOptions, comp: (a: T, b: T) => number);
+  _transform(data: T, _: BufferEncoding, callback: TransformCallback): void;
+  _flush(callback: TransformCallback): void;
 }
-declare const sort: (comp: any, options: any) => SortStreamer;
+declare const sort: <T>(comp: (a: T, b: T) => number, options?: TransformOptions) => SortStreamer<T>;
 //#endregion
 export { sort };

package/dist/stream/server/sort.mjs

@@ -1,46 +1,42 @@
-import { __require } from "../../_virtual/_rolldown/runtime.mjs";
+import { Transform } from "node:stream";
 //#region src/stream/server/sort.ts
-const Transform = __require("stream").Transform;
 const batch = 15e3;
-/**
-* Batch sort stream without overloading the memory limit.
-* https://www.npmjs.com/package/fast-stream-sort
-*/
 var SortStreamer = class extends Transform {
+	a;
+	i;
+	k;
+	currentSize;
+	sortedArray;
+	comp;
 	constructor(options, comp) {
 		super(options);
 		this.a = new Array(batch);
 		this.i = 0;
 		this.k = 0;
 		this.currentSize = batch;
-		this.isDone = false;
 		this.sortedArray = void 0;
 		this.comp = comp;
 	}
 	_transform(data, _, callback) {
 		if (data) {
 			this.a[this.i++] = data;
-			if (this.i == this.currentSize) {
-				this.currentSize = this.currentSize * 2;
-				var tmp = new Array(this.currentSize);
-				for (var j = 0; j < this.i; j++) tmp[j] = this.a[j];
+			if (this.i === this.currentSize) {
+				this.currentSize *= 2;
+				const tmp = new Array(this.currentSize);
+				for (let j = 0; j < this.i; j++) tmp[j] = this.a[j];
 				this.a = tmp;
 			}
 		}
 		callback();
 	}
-	_flush() {
+	_flush(callback) {
 		this.sortedArray = this.a.slice(0, this.i).sort(this.comp);
-		this.fullflush();
-	}
-	fullflush() {
 		while (this.k < this.i) this.push(this.sortedArray[this.k++]);
-		this.push(null);
+		callback();
 	}
 };
 const sort = (comp, options) => {
-	options = options || { objectMode: true };
-	return new SortStreamer(options, comp);
+	return new SortStreamer(options ?? { objectMode: true }, comp);
 };
 //#endregion
 export { sort };

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@8ms/helpers",
 	"license": "UNLICENSED",
-	"version": "3.0.13",
+	"version": "3.0.15",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/8millionstories-organisation/8ms-helpers-ts.git"
@@ -51,7 +51,6 @@
 		"pg": "^8.0.0",
 		"react": "^19.0.0",
 		"react-intersection-observer": "^10.0.0",
-		"stream-chain": "^3.0.0",
 		"swr": "^2.0.0"
 	},
 	"peerDependenciesMeta": {
@@ -154,35 +153,32 @@
 		"react": {
 			"optional": true
 		},
-		"stream-chain": {
-			"optional": true
-		},
 		"swr": {
 			"optional": true
 		}
 	},
 	"devDependencies": {
 		"@1password/sdk": "^0.4.0",
-		"@aws-sdk/client-cloudwatch": "^3.1057.0",
-		"@aws-sdk/client-cloudwatch-logs": "^3.1057.0",
-		"@aws-sdk/client-ec2": "^3.1057.0",
-		"@aws-sdk/client-ecs": "^3.1057.0",
-		"@aws-sdk/client-glue": "^3.1057.0",
-		"@aws-sdk/client-lambda": "^3.1057.0",
-		"@aws-sdk/client-s3": "^3.1057.0",
-		"@aws-sdk/client-ses": "^3.1057.0",
-		"@aws-sdk/client-sqs": "^3.1057.0",
-		"@aws-sdk/client-ssm": "^3.1057.0",
-		"@aws-sdk/lib-storage": "^3.1057.0",
-		"@aws-sdk/s3-request-presigner": "^3.1057.0",
-		"@aws-sdk/types": "^3.973.9",
+		"@aws-sdk/client-cloudwatch": "^3.1068.0",
+		"@aws-sdk/client-cloudwatch-logs": "^3.1068.0",
+		"@aws-sdk/client-ec2": "^3.1068.0",
+		"@aws-sdk/client-ecs": "^3.1068.0",
+		"@aws-sdk/client-glue": "^3.1068.0",
+		"@aws-sdk/client-lambda": "^3.1068.0",
+		"@aws-sdk/client-s3": "^3.1068.0",
+		"@aws-sdk/client-ses": "^3.1068.0",
+		"@aws-sdk/client-sqs": "^3.1068.0",
+		"@aws-sdk/client-ssm": "^3.1068.0",
+		"@aws-sdk/lib-storage": "^3.1068.0",
+		"@aws-sdk/s3-request-presigner": "^3.1068.0",
+		"@aws-sdk/types": "^3.973.12",
 		"@babel/core": "7.29.7",
 		"@babel/preset-env": "7.29.7",
 		"@babel/preset-flow": "7.29.7",
 		"@babel/preset-typescript": "7.29.7",
 		"@google-cloud/bigquery": "^8.3.1",
-		"@google-cloud/common": "^6.0.0",
-		"@google-cloud/storage": "^7.19.0",
+		"@google-cloud/common": "^6.0.1",
+		"@google-cloud/storage": "^7.21.0",
 		"@googleapis/sheets": "^13.0.2",
 		"@planetscale/database": "^1.20.1",
 		"@prisma/adapter-mariadb": "^7.8.0",
@@ -193,27 +189,26 @@
 		"@types/fs-extra": "^11.0.4",
 		"@types/jest": "30.0.0",
 		"@types/luxon": "3.7.1",
-		"@types/node": "^24.12.4",
-		"@types/react": "^19.2.15",
-		"@vercel/oidc": "^3.5.0",
-		"@vercel/oidc-aws-credentials-provider": "^3.1.2",
+		"@types/node": "^24.13.2",
+		"@types/react": "^19.2.17",
+		"@vercel/oidc": "^3.6.1",
+		"@vercel/oidc-aws-credentials-provider": "^3.1.4",
 		"babel-jest": "30.4.1",
 		"dotenv": "^17.4.2",
 		"drizzle-orm": "beta",
 		"fs-extra": "^11.3.5",
-		"gaxios": "^7.1.4",
-		"google-auth-library": "^10.6.2",
-		"googleapis-common": "^8.0.1",
+		"gaxios": "^7.1.5",
+		"google-auth-library": "^10.7.0",
+		"googleapis-common": "^8.0.2",
 		"jest": "^30.4.2",
-		"mysql2": "^3.22.4",
-		"next": "^16.2.6",
+		"mysql2": "^3.22.5",
+		"next": "^16.2.9",
 		"pg": "^8.21.0",
-		"react": "^19.2.6",
+		"react": "^19.2.7",
 		"react-intersection-observer": "^10.0.3",
-		"stream-chain": "^3.6.3",
 		"swr": "^2.4.1",
 		"ts-node": "^10.9.2",
-		"tsdown": "^0.22.1",
+		"tsdown": "^0.22.2",
 		"tslib": "^2.8.1",
 		"typescript": "^6.0.3"
 	},