@8ms/helpers 3.2.6 → 3.2.8

package/AGENTS.md

@@ -64,12 +64,32 @@ Server-only code lives in `<module>/server/`, client-only in `<module>/client/`.
 
 **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.
 
+**One `index.ts` per module boundary, not per subfolder.** A folder gets its own `index.ts` only when it's a public module boundary — what `tsdown`'s per-folder export generation turns into a `@8ms/helpers/<path>` subpath (`server/`, `client/`, `_shared/` folders). A subfolder created purely to split a large file into smaller ones for readability (e.g. `stream/server/json/`) is internal organisation, not a module boundary, and should not have its own `index.ts` — the nearest module-boundary `index.ts` above it imports directly from its files instead.
+
 **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.
 
+**No single-line implicit-return function bodies.** A function or arrow function body is always a brace block with an explicit `return`, never a bare expression after `=>`. Write:
+
+```ts
+const toRowReadable = <T>(source: RowSource<T>): Readable =>
+{
+	return source instanceof Readable ? source : Readable.from(source, {objectMode: true});
+};
+```
+
+not:
+
+```ts
+const toRowReadable = <T>(source: RowSource<T>): Readable =>
+	source instanceof Readable ? source : Readable.from(source, {objectMode: true});
+```
+
+This matches the brace-on-its-own-line style already used for `if`/`for`/class bodies throughout the codebase. It applies to a function's own body, not to every inline arrow passed as a callback argument (e.g. `.then(result => callback(null, result))` is unaffected).
+
 ## Adding a new module
 
 1. Create `src/<name>/` with an `index.ts` re-exporting the public surface.

package/dist/aws/s3/{server → _shared}/awsS3File.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_date__shared_date = require("../../../date/_shared/date.cjs");
 require("../../../date/_shared/index.cjs");
-//#region src/aws/s3/server/awsS3File.ts
+//#region src/aws/s3/_shared/awsS3File.ts
 const readFileDefault = {
 	body: void 0,
 	now: void 0,

package/dist/aws/s3/{server → _shared}/awsS3File.d.cts

@@ -1,4 +1,4 @@
-//#region src/aws/s3/server/awsS3File.d.ts
+//#region src/aws/s3/_shared/awsS3File.d.ts
 export type Modified = {
   now?: number;
   modified: string;

package/dist/aws/s3/{server → _shared}/awsS3File.d.mts

@@ -1,4 +1,4 @@
-//#region src/aws/s3/server/awsS3File.d.ts
+//#region src/aws/s3/_shared/awsS3File.d.ts
 export type Modified = {
   now?: number;
   modified: string;

package/dist/aws/s3/{server → _shared}/awsS3File.mjs

@@ -1,6 +1,6 @@
 import { defaultDateTime } from "../../../date/_shared/date.mjs";
 import "../../../date/_shared/index.mjs";
-//#region src/aws/s3/server/awsS3File.ts
+//#region src/aws/s3/_shared/awsS3File.ts
 const readFileDefault = {
 	body: void 0,
 	now: void 0,

package/dist/aws/s3/_shared/index.cjs

@@ -0,0 +1,3 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_aws_s3__shared_awsS3File = require("./awsS3File.cjs");
+exports.readFileDefault = require_aws_s3__shared_awsS3File.readFileDefault;

package/dist/aws/s3/_shared/index.d.cts

@@ -0,0 +1,3 @@
+import { Modified, ReadFileResponse, readFileDefault } from "./awsS3File.cjs";
+import { FileHeadResponse, JsonStreamOptions, Options, ReadBufferResponse, WritePresignedPostProps } from "./types.cjs";
+export { FileHeadResponse, JsonStreamOptions, Modified, Options, ReadBufferResponse, ReadFileResponse, WritePresignedPostProps, readFileDefault };

package/dist/aws/s3/_shared/index.d.mts

@@ -0,0 +1,3 @@
+import { Modified, ReadFileResponse, readFileDefault } from "./awsS3File.mjs";
+import { FileHeadResponse, JsonStreamOptions, Options, ReadBufferResponse, WritePresignedPostProps } from "./types.mjs";
+export { FileHeadResponse, JsonStreamOptions, Modified, Options, ReadBufferResponse, ReadFileResponse, WritePresignedPostProps, readFileDefault };

package/dist/aws/s3/_shared/index.mjs

@@ -0,0 +1,2 @@
+import { readFileDefault } from "./awsS3File.mjs";
+export { readFileDefault };

package/dist/aws/s3/_shared/types.d.cts

@@ -0,0 +1,35 @@
+import { Modified } from "./awsS3File.cjs";
+import { RowCallback, SortCallback } from "../../../stream/server/json/logic.cjs";
+//#region src/aws/s3/_shared/types.d.ts
+export type Options = {
+  [key: string]: any;
+};
+export type ReadBufferResponse = Modified & {
+  buffer: any;
+};
+export type FileHeadResponse = {
+  exists: boolean;
+  fileType: string | null;
+  size: number;
+  modified: string;
+  etag: string | null;
+  versionId: string | null;
+  encoding: string | null;
+  cacheControl: string | null;
+  meta: Record<string, string>;
+  expires: string | null;
+};
+export type WritePresignedPostProps = {
+  bucket: string;
+  fields: Record<string, string>;
+  file: File | Blob;
+  key: string;
+  url: string;
+};
+/** Shared options for writeJson(Gzip)Stream/readJson(Gzip)Stream. */
+export type JsonStreamOptions<T = any> = {
+  rowCallback?: RowCallback<T>;
+  sortCallback?: SortCallback<T>;
+  awsS3Options?: Options;
+};
+//#endregion

package/dist/aws/s3/_shared/types.d.mts

@@ -0,0 +1,35 @@
+import { Modified } from "./awsS3File.mjs";
+import { RowCallback, SortCallback } from "../../../stream/server/json/logic.mjs";
+//#region src/aws/s3/_shared/types.d.ts
+export type Options = {
+  [key: string]: any;
+};
+export type ReadBufferResponse = Modified & {
+  buffer: any;
+};
+export type FileHeadResponse = {
+  exists: boolean;
+  fileType: string | null;
+  size: number;
+  modified: string;
+  etag: string | null;
+  versionId: string | null;
+  encoding: string | null;
+  cacheControl: string | null;
+  meta: Record<string, string>;
+  expires: string | null;
+};
+export type WritePresignedPostProps = {
+  bucket: string;
+  fields: Record<string, string>;
+  file: File | Blob;
+  key: string;
+  url: string;
+};
+/** Shared options for writeJson(Gzip)Stream/readJson(Gzip)Stream. */
+export type JsonStreamOptions<T = any> = {
+  rowCallback?: RowCallback<T>;
+  sortCallback?: SortCallback<T>;
+  awsS3Options?: Options;
+};
+//#endregion

package/dist/aws/s3/_shared/types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/aws/s3/server/AwsS3.cjs

@@ -3,9 +3,12 @@ const require_runtime = require("../../../_virtual/_rolldown/runtime.cjs");
 const require__class__shared_BaseNamespace = require("../../../_class/_shared/BaseNamespace.cjs");
 const require_date__shared_calculation = require("../../../date/_shared/calculation.cjs");
 const require_date__shared_format = require("../../../date/_shared/format.cjs");
-const require_aws_server_isResponse200 = require("../../server/isResponse200.cjs");
 const require_date__shared_date = require("../../../date/_shared/date.cjs");
 require("../../../date/_shared/index.cjs");
+const require_aws_server_isResponse200 = require("../../server/isResponse200.cjs");
+const require_stream_server_json_read = require("../../../stream/server/json/read.cjs");
+const require_stream_server_json_write = require("../../../stream/server/json/write.cjs");
+require("../../../stream/server/index.cjs");
 const require_string__shared_getFolder = require("../../../string/_shared/getFolder.cjs");
 const require_string__shared_getStringFromStream = require("../../../string/_shared/getStringFromStream.cjs");
 require("../../../string/_shared/index.cjs");
@@ -16,10 +19,11 @@ require("../../../string/server/index.cjs");
 const require_util_server_getBrotliCompressed = require("../../../util/server/getBrotliCompressed.cjs");
 const require_util_server_getGzipCompressed = require("../../../util/server/getGzipCompressed.cjs");
 require("../../../util/server/index.cjs");
-const require_aws_s3_server_awsS3File = require("./awsS3File.cjs");
+const require_aws_s3__shared_awsS3File = require("../_shared/awsS3File.cjs");
 require("./index.cjs");
 let ky = require("ky");
 ky = require_runtime.__toESM(ky);
+let stream = require("stream");
 //#region src/aws/s3/server/AwsS3.ts
 var AwsS3 = class extends require__class__shared_BaseNamespace.BaseNamespace {
 	init = async (config, region) => {
@@ -171,7 +175,7 @@ var AwsS3 = class extends require__class__shared_BaseNamespace.BaseNamespace {
 	readBuffer = async (bucket, key) => {
 		const { GetObjectCommand } = await import("@aws-sdk/client-s3");
 		let response = {
-			...require_aws_s3_server_awsS3File.readFileDefault,
+			...require_aws_s3__shared_awsS3File.readFileDefault,
 			buffer: void 0
 		};
 		const apiResponse = await this.client.send(new GetObjectCommand({
@@ -238,7 +242,7 @@ var AwsS3 = class extends require__class__shared_BaseNamespace.BaseNamespace {
 		return response;
 	};
 	readFile = async (bucket, key, options = {}) => {
-		let response = structuredClone(require_aws_s3_server_awsS3File.readFileDefault);
+		let response = structuredClone(require_aws_s3__shared_awsS3File.readFileDefault);
 		const today = require_date__shared_calculation.getToday();
 		try {
 			response.now = today.toUnixInteger();
@@ -258,6 +262,17 @@ var AwsS3 = class extends require__class__shared_BaseNamespace.BaseNamespace {
 		}
 		return response;
 	};
+	/**
+	* Return the raw object body as a stream, without buffering it into memory.
+	*/
+	readStream = async (bucket, key, options = {}) => {
+		const { GetObjectCommand } = await import("@aws-sdk/client-s3");
+		return (await this.client.send(new GetObjectCommand({
+			Bucket: bucket,
+			Key: key,
+			...options
+		}))).Body;
+	};
 	readJson = async (bucket, key) => {
 		const apiResponse = await this.readFile(bucket, key);
 		apiResponse.body = JSON.parse(apiResponse.body) || null;
@@ -271,6 +286,25 @@ var AwsS3 = class extends require__class__shared_BaseNamespace.BaseNamespace {
 		}
 		return apiResponse;
 	};
+	/**
+	* Read a JSON array object back, parsing it incrementally without buffering the full document.
+	*/
+	readJsonStream = async (bucket, key, options = {}) => {
+		const source = await this.readStream(bucket, key, options.awsS3Options);
+		return require_stream_server_json_read.readJsonStream({
+			source,
+			rowCallback: options.rowCallback,
+			sortCallback: options.sortCallback
+		});
+	};
+	readJsonGzipStream = async (bucket, key, options = {}) => {
+		const source = await this.readStream(bucket, key, options.awsS3Options);
+		return require_stream_server_json_read.readJsonGzipStream({
+			source,
+			rowCallback: options.rowCallback,
+			sortCallback: options.sortCallback
+		});
+	};
 	readGzip = async (bucket, key, gzipOptions = {}, awsS3Options = {}) => {
 		const apiResponse = await this.readFile(bucket, key, awsS3Options);
 		if (void 0 !== apiResponse.body) apiResponse.body = await require_util_server_getGzipDecompressed.getGzipDecompressed(apiResponse.body, gzipOptions);
@@ -300,6 +334,51 @@ var AwsS3 = class extends require__class__shared_BaseNamespace.BaseNamespace {
 		finalData = await require_util_server_getGzipCompressed.getGzipCompressed(finalData, gzipOptions);
 		return await this.writeFile(bucket, key, finalData, awsS3Options);
 	};
+	/**
+	* Write a row source (stream, array, or async iterable) as a JSON array to S3,
+	* without buffering the full payload in memory.
+	*/
+	writeJsonStream = async (bucket, key, source, options = {}) => {
+		const { Upload } = await import("@aws-sdk/lib-storage");
+		const destination = new stream.PassThrough();
+		const upload = new Upload({
+			client: this.client,
+			params: {
+				Bucket: bucket,
+				Key: key,
+				Body: destination,
+				ContentType: "application/json",
+				...options.awsS3Options
+			}
+		});
+		await Promise.all([require_stream_server_json_write.writeJsonStream({
+			source,
+			destination,
+			rowCallback: options.rowCallback,
+			sortCallback: options.sortCallback
+		}), upload.done()]);
+	};
+	writeJsonGzipStream = async (bucket, key, source, options = {}) => {
+		const { Upload } = await import("@aws-sdk/lib-storage");
+		const destination = new stream.PassThrough();
+		const upload = new Upload({
+			client: this.client,
+			params: {
+				Bucket: bucket,
+				Key: key,
+				Body: destination,
+				ContentType: "application/json",
+				ContentEncoding: "gzip",
+				...options.awsS3Options
+			}
+		});
+		await Promise.all([require_stream_server_json_write.writeJsonGzipStream({
+			source,
+			destination,
+			rowCallback: options.rowCallback,
+			sortCallback: options.sortCallback
+		}), upload.done()]);
+	};
 	writeGzip = async (bucket, key, data, gzipOptions = {}, awsS3Options = {}) => {
 		if (await this.isNullOrEmptyData(data)) return null;
 		let finalData = data;

package/dist/aws/s3/server/AwsS3.d.cts

@@ -1,33 +1,11 @@
 import { BaseNamespace } from "../../../_class/_shared/BaseNamespace.cjs";
-import { Modified, ReadFileResponse } from "./awsS3File.cjs";
+import { ReadFileResponse } from "../_shared/awsS3File.cjs";
+import { RowSource } from "../../../stream/server/json/logic.cjs";
+import { FileHeadResponse, JsonStreamOptions, Options, ReadBufferResponse, WritePresignedPostProps } from "../_shared/types.cjs";
 import "./index.cjs";
+import { Readable } from "stream";
 import { S3Client } from "@aws-sdk/client-s3";
 //#region src/aws/s3/server/AwsS3.d.ts
-export type ReadBufferResponse = Modified & {
-  buffer: any;
-};
-export type FileHeadResponse = {
-  exists: boolean;
-  fileType: string | null;
-  size: number;
-  modified: string;
-  etag: string | null;
-  versionId: string | null;
-  encoding: string | null;
-  cacheControl: string | null;
-  meta: Record<string, string>;
-  expires: string | null;
-};
-type Options = {
-  [key: string]: any;
-};
-type WritePresignedPostProps = {
-  bucket: string;
-  fields: Record<string, string>;
-  file: File | Blob;
-  key: string;
-  url: string;
-};
 export declare class AwsS3 extends BaseNamespace {
   client: S3Client;
   config: any;
@@ -65,13 +43,28 @@ export declare class AwsS3 extends BaseNamespace {
   fileExists: (bucket: string, key: string) => Promise<boolean>;
   getFileHead: (bucket: string, key: string) => Promise<FileHeadResponse>;
   readFile: (bucket: string, key: string, options?: Options) => Promise<ReadFileResponse>;
+  /**
+   * Return the raw object body as a stream, without buffering it into memory.
+   */
+  readStream: (bucket: string, key: string, options?: Options) => Promise<Readable>;
   readJson: (bucket: string, key: string) => Promise<ReadFileResponse>;
   readJsonGzip: (bucket: string, key: string, gzipOptions?: object, awsS3Options?: Options) => Promise<ReadFileResponse>;
+  /**
+   * Read a JSON array object back, parsing it incrementally without buffering the full document.
+   */
+  readJsonStream: <T = any>(bucket: string, key: string, options?: JsonStreamOptions<T>) => Promise<T[]>;
+  readJsonGzipStream: <T = any>(bucket: string, key: string, options?: JsonStreamOptions<T>) => Promise<T[]>;
   readGzip: (bucket: string, key: string, gzipOptions?: object, awsS3Options?: Options) => Promise<ReadFileResponse>;
   writeBrotli: (bucket: string, key: string, data: any, brotliOptions?: object, awsS3Options?: Options) => Promise<import("@aws-sdk/client-s3").PutObjectCommandOutput | null>;
   writeFile: (bucket: string, key: string, data: any, options?: Options) => Promise<import("@aws-sdk/client-s3").PutObjectCommandOutput | null>;
   writeJson: (bucket: string, key: string, data: any, options?: Options) => Promise<import("@aws-sdk/client-s3").PutObjectCommandOutput | null>;
   writeJsonGzip: (bucket: string, key: string, data: any, gzipOptions?: object, awsS3Options?: Options) => Promise<import("@aws-sdk/client-s3").PutObjectCommandOutput | null>;
+  /**
+   * Write a row source (stream, array, or async iterable) as a JSON array to S3,
+   * without buffering the full payload in memory.
+   */
+  writeJsonStream: <T = any>(bucket: string, key: string, source: RowSource<T>, options?: JsonStreamOptions<T>) => Promise<void>;
+  writeJsonGzipStream: <T = any>(bucket: string, key: string, source: RowSource<T>, options?: JsonStreamOptions<T>) => Promise<void>;
   writeGzip: (bucket: string, key: string, data: any, gzipOptions?: object, awsS3Options?: Options) => Promise<import("@aws-sdk/client-s3").PutObjectCommandOutput | null>;
   /**
    * Get a presigned post URL so we can upload directly to S3 via frontend.

package/dist/aws/s3/server/AwsS3.d.mts

@@ -1,33 +1,11 @@
 import { BaseNamespace } from "../../../_class/_shared/BaseNamespace.mjs";
-import { Modified, ReadFileResponse } from "./awsS3File.mjs";
+import { ReadFileResponse } from "../_shared/awsS3File.mjs";
+import { RowSource } from "../../../stream/server/json/logic.mjs";
+import { FileHeadResponse, JsonStreamOptions, Options, ReadBufferResponse, WritePresignedPostProps } from "../_shared/types.mjs";
 import "./index.mjs";
+import { Readable } from "stream";
 import { S3Client } from "@aws-sdk/client-s3";
 //#region src/aws/s3/server/AwsS3.d.ts
-export type ReadBufferResponse = Modified & {
-  buffer: any;
-};
-export type FileHeadResponse = {
-  exists: boolean;
-  fileType: string | null;
-  size: number;
-  modified: string;
-  etag: string | null;
-  versionId: string | null;
-  encoding: string | null;
-  cacheControl: string | null;
-  meta: Record<string, string>;
-  expires: string | null;
-};
-type Options = {
-  [key: string]: any;
-};
-type WritePresignedPostProps = {
-  bucket: string;
-  fields: Record<string, string>;
-  file: File | Blob;
-  key: string;
-  url: string;
-};
 export declare class AwsS3 extends BaseNamespace {
   client: S3Client;
   config: any;
@@ -65,13 +43,28 @@ export declare class AwsS3 extends BaseNamespace {
   fileExists: (bucket: string, key: string) => Promise<boolean>;
   getFileHead: (bucket: string, key: string) => Promise<FileHeadResponse>;
   readFile: (bucket: string, key: string, options?: Options) => Promise<ReadFileResponse>;
+  /**
+   * Return the raw object body as a stream, without buffering it into memory.
+   */
+  readStream: (bucket: string, key: string, options?: Options) => Promise<Readable>;
   readJson: (bucket: string, key: string) => Promise<ReadFileResponse>;
   readJsonGzip: (bucket: string, key: string, gzipOptions?: object, awsS3Options?: Options) => Promise<ReadFileResponse>;
+  /**
+   * Read a JSON array object back, parsing it incrementally without buffering the full document.
+   */
+  readJsonStream: <T = any>(bucket: string, key: string, options?: JsonStreamOptions<T>) => Promise<T[]>;
+  readJsonGzipStream: <T = any>(bucket: string, key: string, options?: JsonStreamOptions<T>) => Promise<T[]>;
   readGzip: (bucket: string, key: string, gzipOptions?: object, awsS3Options?: Options) => Promise<ReadFileResponse>;
   writeBrotli: (bucket: string, key: string, data: any, brotliOptions?: object, awsS3Options?: Options) => Promise<import("@aws-sdk/client-s3").PutObjectCommandOutput | null>;
   writeFile: (bucket: string, key: string, data: any, options?: Options) => Promise<import("@aws-sdk/client-s3").PutObjectCommandOutput | null>;
   writeJson: (bucket: string, key: string, data: any, options?: Options) => Promise<import("@aws-sdk/client-s3").PutObjectCommandOutput | null>;
   writeJsonGzip: (bucket: string, key: string, data: any, gzipOptions?: object, awsS3Options?: Options) => Promise<import("@aws-sdk/client-s3").PutObjectCommandOutput | null>;
+  /**
+   * Write a row source (stream, array, or async iterable) as a JSON array to S3,
+   * without buffering the full payload in memory.
+   */
+  writeJsonStream: <T = any>(bucket: string, key: string, source: RowSource<T>, options?: JsonStreamOptions<T>) => Promise<void>;
+  writeJsonGzipStream: <T = any>(bucket: string, key: string, source: RowSource<T>, options?: JsonStreamOptions<T>) => Promise<void>;
   writeGzip: (bucket: string, key: string, data: any, gzipOptions?: object, awsS3Options?: Options) => Promise<import("@aws-sdk/client-s3").PutObjectCommandOutput | null>;
   /**
    * Get a presigned post URL so we can upload directly to S3 via frontend.

package/dist/aws/s3/server/AwsS3.mjs

@@ -1,9 +1,12 @@
 import { BaseNamespace } from "../../../_class/_shared/BaseNamespace.mjs";
 import { getToday } from "../../../date/_shared/calculation.mjs";
 import { getYmdHisString } from "../../../date/_shared/format.mjs";
-import { isResponse200 } from "../../server/isResponse200.mjs";
 import { defaultDateTime } from "../../../date/_shared/date.mjs";
 import "../../../date/_shared/index.mjs";
+import { isResponse200 } from "../../server/isResponse200.mjs";
+import { readJsonGzipStream, readJsonStream } from "../../../stream/server/json/read.mjs";
+import { writeJsonGzipStream, writeJsonStream } from "../../../stream/server/json/write.mjs";
+import "../../../stream/server/index.mjs";
 import { getFolder } from "../../../string/_shared/getFolder.mjs";
 import { getStringFromStream } from "../../../string/_shared/getStringFromStream.mjs";
 import "../../../string/_shared/index.mjs";
@@ -14,9 +17,10 @@ import "../../../string/server/index.mjs";
 import { getBrotliCompressed } from "../../../util/server/getBrotliCompressed.mjs";
 import { getGzipCompressed } from "../../../util/server/getGzipCompressed.mjs";
 import "../../../util/server/index.mjs";
-import { readFileDefault } from "./awsS3File.mjs";
+import { readFileDefault } from "../_shared/awsS3File.mjs";
 import "./index.mjs";
 import ky from "ky";
+import { PassThrough } from "stream";
 //#region src/aws/s3/server/AwsS3.ts
 var AwsS3 = class extends BaseNamespace {
 	init = async (config, region) => {
@@ -255,6 +259,17 @@ var AwsS3 = class extends BaseNamespace {
 		}
 		return response;
 	};
+	/**
+	* Return the raw object body as a stream, without buffering it into memory.
+	*/
+	readStream = async (bucket, key, options = {}) => {
+		const { GetObjectCommand } = await import("@aws-sdk/client-s3");
+		return (await this.client.send(new GetObjectCommand({
+			Bucket: bucket,
+			Key: key,
+			...options
+		}))).Body;
+	};
 	readJson = async (bucket, key) => {
 		const apiResponse = await this.readFile(bucket, key);
 		apiResponse.body = JSON.parse(apiResponse.body) || null;
@@ -268,6 +283,25 @@ var AwsS3 = class extends BaseNamespace {
 		}
 		return apiResponse;
 	};
+	/**
+	* Read a JSON array object back, parsing it incrementally without buffering the full document.
+	*/
+	readJsonStream = async (bucket, key, options = {}) => {
+		const source = await this.readStream(bucket, key, options.awsS3Options);
+		return readJsonStream({
+			source,
+			rowCallback: options.rowCallback,
+			sortCallback: options.sortCallback
+		});
+	};
+	readJsonGzipStream = async (bucket, key, options = {}) => {
+		const source = await this.readStream(bucket, key, options.awsS3Options);
+		return readJsonGzipStream({
+			source,
+			rowCallback: options.rowCallback,
+			sortCallback: options.sortCallback
+		});
+	};
 	readGzip = async (bucket, key, gzipOptions = {}, awsS3Options = {}) => {
 		const apiResponse = await this.readFile(bucket, key, awsS3Options);
 		if (void 0 !== apiResponse.body) apiResponse.body = await getGzipDecompressed(apiResponse.body, gzipOptions);
@@ -297,6 +331,51 @@ var AwsS3 = class extends BaseNamespace {
 		finalData = await getGzipCompressed(finalData, gzipOptions);
 		return await this.writeFile(bucket, key, finalData, awsS3Options);
 	};
+	/**
+	* Write a row source (stream, array, or async iterable) as a JSON array to S3,
+	* without buffering the full payload in memory.
+	*/
+	writeJsonStream = async (bucket, key, source, options = {}) => {
+		const { Upload } = await import("@aws-sdk/lib-storage");
+		const destination = new PassThrough();
+		const upload = new Upload({
+			client: this.client,
+			params: {
+				Bucket: bucket,
+				Key: key,
+				Body: destination,
+				ContentType: "application/json",
+				...options.awsS3Options
+			}
+		});
+		await Promise.all([writeJsonStream({
+			source,
+			destination,
+			rowCallback: options.rowCallback,
+			sortCallback: options.sortCallback
+		}), upload.done()]);
+	};
+	writeJsonGzipStream = async (bucket, key, source, options = {}) => {
+		const { Upload } = await import("@aws-sdk/lib-storage");
+		const destination = new PassThrough();
+		const upload = new Upload({
+			client: this.client,
+			params: {
+				Bucket: bucket,
+				Key: key,
+				Body: destination,
+				ContentType: "application/json",
+				ContentEncoding: "gzip",
+				...options.awsS3Options
+			}
+		});
+		await Promise.all([writeJsonGzipStream({
+			source,
+			destination,
+			rowCallback: options.rowCallback,
+			sortCallback: options.sortCallback
+		}), upload.done()]);
+	};
 	writeGzip = async (bucket, key, data, gzipOptions = {}, awsS3Options = {}) => {
 		if (await this.isNullOrEmptyData(data)) return null;
 		let finalData = data;

package/dist/aws/s3/server/index.cjs

@@ -1,7 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_aws_s3_server_awsS3File = require("./awsS3File.cjs");
+const require_aws_s3__shared_awsS3File = require("../_shared/awsS3File.cjs");
+require("../_shared/index.cjs");
 const require_aws_s3_server_payload = require("./payload.cjs");
 const require_aws_s3_server_AwsS3 = require("./AwsS3.cjs");
 exports.AwsS3 = require_aws_s3_server_AwsS3.AwsS3;
 exports.payloadSchema = require_aws_s3_server_payload.payloadSchema;
-exports.readFileDefault = require_aws_s3_server_awsS3File.readFileDefault;
+exports.readFileDefault = require_aws_s3__shared_awsS3File.readFileDefault;

package/dist/aws/s3/server/index.d.cts

@@ -1,4 +1,5 @@
-import { Modified, ReadFileResponse, readFileDefault } from "./awsS3File.cjs";
+import { Modified, ReadFileResponse, readFileDefault } from "../_shared/awsS3File.cjs";
+import { FileHeadResponse, JsonStreamOptions, Options, ReadBufferResponse, WritePresignedPostProps } from "../_shared/types.cjs";
 import { PayloadSchemaType, payloadSchema } from "./payload.cjs";
-import { AwsS3, FileHeadResponse, ReadBufferResponse } from "./AwsS3.cjs";
-export { AwsS3, FileHeadResponse, Modified, PayloadSchemaType, ReadBufferResponse, ReadFileResponse, payloadSchema, readFileDefault };
+import { AwsS3 } from "./AwsS3.cjs";
+export { AwsS3, FileHeadResponse, JsonStreamOptions, Modified, Options, PayloadSchemaType, ReadBufferResponse, ReadFileResponse, WritePresignedPostProps, payloadSchema, readFileDefault };

package/dist/aws/s3/server/index.d.mts

@@ -1,4 +1,5 @@
-import { Modified, ReadFileResponse, readFileDefault } from "./awsS3File.mjs";
+import { Modified, ReadFileResponse, readFileDefault } from "../_shared/awsS3File.mjs";
+import { FileHeadResponse, JsonStreamOptions, Options, ReadBufferResponse, WritePresignedPostProps } from "../_shared/types.mjs";
 import { PayloadSchemaType, payloadSchema } from "./payload.mjs";
-import { AwsS3, FileHeadResponse, ReadBufferResponse } from "./AwsS3.mjs";
-export { AwsS3, FileHeadResponse, Modified, PayloadSchemaType, ReadBufferResponse, ReadFileResponse, payloadSchema, readFileDefault };
+import { AwsS3 } from "./AwsS3.mjs";
+export { AwsS3, FileHeadResponse, JsonStreamOptions, Modified, Options, PayloadSchemaType, ReadBufferResponse, ReadFileResponse, WritePresignedPostProps, payloadSchema, readFileDefault };

package/dist/aws/s3/server/index.mjs

@@ -1,4 +1,5 @@
-import { readFileDefault } from "./awsS3File.mjs";
+import { readFileDefault } from "../_shared/awsS3File.mjs";
+import "../_shared/index.mjs";
 import { payloadSchema } from "./payload.mjs";
 import { AwsS3 } from "./AwsS3.mjs";
 export { AwsS3, payloadSchema, readFileDefault };

package/dist/file/_shared/dataFileType.cjs

@@ -2,6 +2,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/file/_shared/dataFileType.ts
 const dataFileType = {
 	JSON: "json",
+	JSON_NEWLINE: "jsonl",
+	PARQUET: "parquet",
 	XML: "xml"
 };
 //#endregion

package/dist/file/_shared/dataFileType.d.cts

@@ -1,6 +1,8 @@
 //#region src/file/_shared/dataFileType.d.ts
 export declare const dataFileType: {
   readonly JSON: "json";
+  readonly JSON_NEWLINE: "jsonl";
+  readonly PARQUET: "parquet";
   readonly XML: "xml";
 };
 export type DataFileType = typeof dataFileType[keyof typeof dataFileType];

package/dist/file/_shared/dataFileType.d.mts

@@ -1,6 +1,8 @@
 //#region src/file/_shared/dataFileType.d.ts
 export declare const dataFileType: {
   readonly JSON: "json";
+  readonly JSON_NEWLINE: "jsonl";
+  readonly PARQUET: "parquet";
   readonly XML: "xml";
 };
 export type DataFileType = typeof dataFileType[keyof typeof dataFileType];

package/dist/file/_shared/dataFileType.mjs

@@ -1,6 +1,8 @@
 //#region src/file/_shared/dataFileType.ts
 const dataFileType = {
 	JSON: "json",
+	JSON_NEWLINE: "jsonl",
+	PARQUET: "parquet",
 	XML: "xml"
 };
 //#endregion

package/dist/file/_shared/fileMimeType.cjs

@@ -10,9 +10,11 @@ const fileMimeType = {
 	[require_file__shared_fileType.fileType.JPEG]: "image/jpeg",
 	[require_file__shared_fileType.fileType.JPG]: "image/jpeg",
 	[require_file__shared_fileType.fileType.JSON]: "application/json",
+	[require_file__shared_fileType.fileType.JSON_NEWLINE]: "application/x-ndjson",
 	[require_file__shared_fileType.fileType.MKV]: "video/x-matroska",
 	[require_file__shared_fileType.fileType.MOV]: "video/quicktime",
 	[require_file__shared_fileType.fileType.MP4]: "video/mp4",
+	[require_file__shared_fileType.fileType.PARQUET]: "application/vnd.apache.parquet",
 	[require_file__shared_fileType.fileType.PDF]: "application/pdf",
 	[require_file__shared_fileType.fileType.PNG]: "image/png",
 	[require_file__shared_fileType.fileType.PPT]: "application/vnd.ms-powerpoint",