@design-edito/tools 0.4.4 → 0.4.6

package/node/cloud-storage/operations/remove-file/index.js

@@ -1,35 +1,30 @@
-import {
-  remove as remove4
-} from "../../../../chunks/chunk-MO4TRYNI.js";
-import {
-  remove as remove3
-} from "../../../../chunks/chunk-AP3VYSVF.js";
-import {
-  remove as remove2
-} from "../../../../chunks/chunk-SYH5LYQC.js";
-import {
-  remove
-} from "../../../../chunks/chunk-5WVGUZL5.js";
-import {
-  isFtpClient,
-  isGcsBucket,
-  isS3ClientWithBucket,
-  isSftpClient
-} from "../../../../chunks/chunk-ISJONMNA.js";
-import {
-  makeFailure
-} from "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/node/cloud-storage/operations/remove-file/index.ts
-async function removeFile(client, path, options) {
-  if (isGcsBucket(client)) return await remove4(client, path, options);
-  if (isS3ClientWithBucket(client)) return await remove3(client.client, path, client.bucketName, options);
-  if (isFtpClient(client)) return await remove(client, path, options);
-  if (isSftpClient(client)) return await remove2(client, path, options);
-  return makeFailure("Invalid client type");
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+import { isFtpClient, isGcsBucket, isS3ClientWithBucket, isSftpClient } from '../../clients/index.js';
+import { remove as ftpRemove } from '../../../ftps/file/remove/index.js';
+import { remove as sftpRemove } from '../../../sftp/file/remove/index.js';
+import { remove as s3Remove } from '../../../@aws-s3/storage/file/remove/index.js';
+import { remove as gcsRemove } from '../../../@google-cloud/storage/file/remove/index.js';
+/**
+ * Removes a file from cloud storage.
+ *
+ * The function automatically dispatches to the appropriate implementation based on
+ * the client type (Google Cloud Storage, S3, FTP, or SFTP).
+ *
+ * @param {AnyClient} client               - The cloud storage client instance.
+ * @param {string}   path                 - The file path to remove.
+ * @param {GcsRemoveOptions | S3RemoveOptions | FtpRemoveOptions | SftpRemoveOptions} [options] - Optional remove configuration.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - On success:  `Outcome.makeSuccess(true)`.
+ * - On failure:  `Outcome.makeFailure(errStr)`.
+ */
+export async function removeFile(client, path, options) {
+    if (isGcsBucket(client))
+        return await gcsRemove(client, path, options);
+    if (isS3ClientWithBucket(client))
+        return await s3Remove(client.client, path, client.bucketName, options);
+    if (isFtpClient(client))
+        return await ftpRemove(client, path, options);
+    if (isSftpClient(client))
+        return await sftpRemove(client, path, options);
+    return Outcome.makeFailure('Invalid client type');
 }
-export {
-  removeFile
-};

package/node/cloud-storage/operations/stat-file/index.js

@@ -1,35 +1,30 @@
-import {
-  stat as stat4
-} from "../../../../chunks/chunk-77SWZUHV.js";
-import {
-  stat as stat3
-} from "../../../../chunks/chunk-IRKZUMWZ.js";
-import {
-  stat as stat2
-} from "../../../../chunks/chunk-S2UZ3HZR.js";
-import {
-  stat
-} from "../../../../chunks/chunk-IPRWXI27.js";
-import {
-  isFtpClient,
-  isGcsBucket,
-  isS3ClientWithBucket,
-  isSftpClient
-} from "../../../../chunks/chunk-ISJONMNA.js";
-import {
-  makeFailure
-} from "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/node/cloud-storage/operations/stat-file/index.ts
-async function statFile(client, path, options) {
-  if (isGcsBucket(client)) return await stat4(client, path, options);
-  if (isS3ClientWithBucket(client)) return await stat3(client.client, path, client.bucketName, options);
-  if (isFtpClient(client)) return await stat(client, path);
-  if (isSftpClient(client)) return await stat2(client, path);
-  return makeFailure("Invalid client type");
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+import { isFtpClient, isGcsBucket, isS3ClientWithBucket, isSftpClient } from '../../clients/index.js';
+import { stat as ftpStat } from '../../../ftps/file/stat/index.js';
+import { stat as sftpStat } from '../../../sftp/file/stat/index.js';
+import { stat as s3Stat } from '../../../@aws-s3/storage/file/stat/index.js';
+import { stat as gcsStat } from '../../../@google-cloud/storage/file/stat/index.js';
+/**
+ * Retrieves metadata for a file in cloud storage.
+ *
+ * The function automatically dispatches to the appropriate implementation based on
+ * the client type (Google Cloud Storage, S3, FTP, or SFTP).
+ *
+ * @param {AnyClient} client              - The cloud storage client instance.
+ * @param {string}   path                 - The file path to stat.
+ * @param {GcsStatOptions | S3StatOptions} [options] - Optional stat configuration.
+ * @returns {Promise<Outcome.Either<GcsStat | S3Stat | FtpStat | SftpStat, string>>}
+ * - On success:  `Outcome.makeSuccess(stat)` containing file metadata.
+ * - On failure:  `Outcome.makeFailure(errStr)`.
+ */
+export async function statFile(client, path, options) {
+    if (isGcsBucket(client))
+        return await gcsStat(client, path, options);
+    if (isS3ClientWithBucket(client))
+        return await s3Stat(client.client, path, client.bucketName, options);
+    if (isFtpClient(client))
+        return await ftpStat(client, path);
+    if (isSftpClient(client))
+        return await sftpStat(client, path);
+    return Outcome.makeFailure('Invalid client type');
 }
-export {
-  statFile
-};

package/node/cloud-storage/operations/upload-file/index.js

@@ -1,35 +1,31 @@
-import {
-  upload as upload4
-} from "../../../../chunks/chunk-EX2QKFY5.js";
-import {
-  upload as upload3
-} from "../../../../chunks/chunk-WIFHP4X7.js";
-import {
-  upload as upload2
-} from "../../../../chunks/chunk-H3HRQ52T.js";
-import {
-  upload
-} from "../../../../chunks/chunk-5TM235Z3.js";
-import {
-  isFtpClient,
-  isGcsBucket,
-  isS3ClientWithBucket,
-  isSftpClient
-} from "../../../../chunks/chunk-ISJONMNA.js";
-import {
-  makeFailure
-} from "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/node/cloud-storage/operations/upload-file/index.ts
-async function uploadFile(fileStream, path, client, options) {
-  if (isGcsBucket(client)) return await upload4(client, path, fileStream, options);
-  if (isS3ClientWithBucket(client)) return await upload3(client.client, client.bucketName, path, fileStream, options);
-  if (isFtpClient(client)) return await upload(client, path, fileStream, options);
-  if (isSftpClient(client)) return await upload2(client, path, fileStream, options);
-  return makeFailure("Invalid client type");
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+import { isFtpClient, isGcsBucket, isS3ClientWithBucket, isSftpClient } from '../../clients/index.js';
+import { upload as ftpUpload } from '../../../ftps/file/upload/index.js';
+import { upload as sftpUpload } from '../../../sftp/file/upload/index.js';
+import { upload as s3Upload } from '../../../@aws-s3/storage/file/upload/index.js';
+import { upload as gcsUpload } from '../../../@google-cloud/storage/file/upload/index.js';
+/**
+ * Uploads a file stream to cloud storage.
+ *
+ * The function automatically dispatches to the appropriate implementation based on
+ * the client type (Google Cloud Storage, S3, FTP, or SFTP).
+ *
+ * @param {Readable} fileStream           - The file content as a stream.
+ * @param {string}   path                 - The path to upload the file to.
+ * @param {AnyClient} client              - The cloud storage client instance.
+ * @param {GcsUploadOptions | S3UploadOptions | FtpUploadOptions | SftpUploadOptions} [options] - Optional upload configuration.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - On success:  `Outcome.makeSuccess(true)`.
+ * - On failure:  `Outcome.makeFailure(errStr)`.
+ */
+export async function uploadFile(fileStream, path, client, options) {
+    if (isGcsBucket(client))
+        return await gcsUpload(client, path, fileStream, options);
+    if (isS3ClientWithBucket(client))
+        return await s3Upload(client.client, client.bucketName, path, fileStream, options);
+    if (isFtpClient(client))
+        return await ftpUpload(client, path, fileStream, options);
+    if (isSftpClient(client))
+        return await sftpUpload(client, path, fileStream, options);
+    return Outcome.makeFailure('Invalid client type');
 }
-export {
-  uploadFile
-};

package/node/encryption/@aes-256-gcm/buffer/index.js

@@ -1,28 +1,33 @@
-import {
-  decryptUint8Array,
-  encryptUint8Array
-} from "../../../../chunks/chunk-RKX6KLPQ.js";
-import {
-  makeSuccess
-} from "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/node/encryption/@aes-256-gcm/buffer/index.ts
-import { Buffer } from "node:buffer";
-function encrypt(inputBuffer, encryptionKey) {
-  const fileArray = new Uint8Array(inputBuffer);
-  const encryptionOutcome = encryptUint8Array(fileArray, encryptionKey);
-  if (!encryptionOutcome.success) return encryptionOutcome;
-  return makeSuccess(Buffer.from(encryptionOutcome.payload));
+import { Buffer } from 'node:buffer';
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+import { encryptUint8Array, decryptUint8Array } from '../uint8-array/index.js';
+/**
+ * Encrypts a `Buffer` by converting it to a `Uint8Array`, performing encryption, and then returning the result as a `Buffer`.
+ *
+ * @param {Buffer} inputBuffer - The input data to encrypt.
+ * @param {string} encryptionKey - The encryption key to use.
+ *
+ * @returns {Outcome.Either<Buffer, string>} The result of the encryption. Success returns the encrypted data as a `Buffer` (with IV prepended), or failure returns an error message.
+ */
+export function encrypt(inputBuffer, encryptionKey) {
+    const fileArray = new Uint8Array(inputBuffer);
+    const encryptionOutcome = encryptUint8Array(fileArray, encryptionKey);
+    if (!encryptionOutcome.success)
+        return encryptionOutcome;
+    return Outcome.makeSuccess(Buffer.from(encryptionOutcome.payload));
 }
-function decrypt(encryptedBuffer, encryptionKey) {
-  const encryptedArray = new Uint8Array(encryptedBuffer);
-  const decryptionOutcome = decryptUint8Array(encryptedArray, encryptionKey);
-  if (!decryptionOutcome.success) return decryptionOutcome;
-  return makeSuccess(Buffer.from(decryptionOutcome.payload));
+/**
+ * Decrypts an encrypted `Buffer` by converting it to a `Uint8Array`, performing decryption, and then returning the result as a `Buffer`.
+ *
+ * @param {Buffer} encryptedBuffer - The encrypted data to decrypt.
+ * @param {string} encryptionKey - The encryption key to use.
+ *
+ * @returns {Outcome.Either<Buffer, string>} The result of the decryption. Success returns the decrypted data as a `Buffer`, or failure returns an error message.
+ */
+export function decrypt(encryptedBuffer, encryptionKey) {
+    const encryptedArray = new Uint8Array(encryptedBuffer);
+    const decryptionOutcome = decryptUint8Array(encryptedArray, encryptionKey);
+    if (!decryptionOutcome.success)
+        return decryptionOutcome;
+    return Outcome.makeSuccess(Buffer.from(decryptionOutcome.payload));
 }
-export {
-  decrypt,
-  encrypt
-};

package/node/encryption/@aes-256-gcm/index.d.ts

@@ -1,2 +1,2 @@
-export * as uint8Array from './uint8-array/index.js'
 export * as buffer from './buffer/index.js'
+export * as uint8Array from './uint8-array/index.js'

package/node/encryption/@aes-256-gcm/index.js

@@ -1,2 +1,2 @@
-export * as uint8Array from './uint8-array/index.js'
 export * as buffer from './buffer/index.js'
+export * as uint8Array from './uint8-array/index.js'

package/node/encryption/@aes-256-gcm/uint8-array/index.js

@@ -1,11 +1,57 @@
-import {
-  decryptUint8Array,
-  encryptUint8Array
-} from "../../../../chunks/chunk-RKX6KLPQ.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  decryptUint8Array,
-  encryptUint8Array
-};
+import { Buffer } from 'node:buffer';
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+/**
+ * Encrypts a `Uint8Array` using AES-256-GCM encryption and the specified encryption key.
+ *
+ * @param {Uint8Array} fileArray - The input data to encrypt.
+ * @param {string} encryptionKey - The encryption key to use.
+ * @param {number} [options.ivLength=16] - The length of the initialization vector (IV). Defaults to 16 bytes.
+ *
+ * @returns {Outcome.Either<Uint8Array, string>} The result of the encryption. Success returns the encrypted data as a `Uint8Array` (with IV prepended), or failure returns an error message.
+ */
+export function encryptUint8Array(fileArray, encryptionKey) {
+    const ivLength = 12;
+    const keyBuffer = Buffer.from(encryptionKey, 'utf-8');
+    if (keyBuffer.length !== 32)
+        return Outcome.makeFailure('Encryption key must be 32 bytes for AES-256-GCM.');
+    try {
+        const iv = randomBytes(ivLength);
+        const cipher = createCipheriv('aes-256-gcm', keyBuffer, iv);
+        let encrypted = cipher.update(fileArray);
+        encrypted = Buffer.concat([encrypted, cipher.final()]);
+        return Outcome.makeSuccess(new Uint8Array(Buffer.concat([iv, encrypted])));
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
+    }
+}
+/**
+ * Decrypts an encrypted `Uint8Array` using AES-256-GCM encryption and the specified encryption key.
+ *
+ * @param {Uint8Array} encryptedFile - The encrypted data to decrypt.
+ * @param {string} encryptionKey - The encryption key to use.
+ * @param {number} [options.ivLength=16] - The length of the initialization vector (IV). Defaults to 16 bytes.
+ *
+ * @returns {Outcome.Either<Uint8Array, string>} The result of the decryption. Success returns the decrypted data as a `Uint8Array`, or failure returns an error message.
+ */
+export function decryptUint8Array(encryptedFile, encryptionKey) {
+    const ivLength = 12;
+    const iv = encryptedFile.subarray(0, ivLength);
+    const keyBuffer = Buffer.from(encryptionKey, 'utf-8');
+    if (keyBuffer.length !== 32)
+        return Outcome.makeFailure('Encryption key must be 32 bytes for AES-256-GCM.');
+    try {
+        const encryptedData = encryptedFile.subarray(ivLength);
+        const decipher = createDecipheriv('aes-256-gcm', keyBuffer, iv);
+        let decrypted = decipher.update(encryptedData);
+        decrypted = Buffer.concat([decrypted, decipher.final()]);
+        return Outcome.makeSuccess(new Uint8Array(decrypted));
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
+    }
+}

package/node/encryption/key/index.js

@@ -1,15 +1,20 @@
-import "../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/node/encryption/key/index.ts
-import { pbkdf2Sync, randomBytes } from "node:crypto";
-function generate(passphrase, outputByteLength, options) {
-  const { saltLength = 16, iterations = 1e5 } = options ?? {};
-  const salt = randomBytes(saltLength);
-  const key = pbkdf2Sync(passphrase, salt, iterations, outputByteLength, "sha256");
-  const saltString = salt.toString("hex");
-  const keyString = key.toString("hex");
-  return `${saltString}:${keyString}`;
+import { pbkdf2Sync, randomBytes } from 'node:crypto';
+/**
+ * Generates an encryption key from a passphrase using PBKDF2.
+ *
+ * @param {string} passphrase - The passphrase to derive the key from.
+ * @param {number} outputByteLength - The length of the output encryption key in bytes.
+ * @param {GenerateOptions} [options] - Optional options.
+ * @param {number} [options.saltLength=16] - The length of the salt in bytes. Defaults to 16 bytes.
+ * @param {number} [options.iterations=100000] - The number of PBKDF2 iterations. Defaults to 100,000 iterations.
+ *
+ * @returns {string} The derived encryption key and salt, concatenated as a string in the format `salt:encryptionKey`.
+ */
+export function generate(passphrase, outputByteLength, options) {
+    const { saltLength = 16, iterations = 100000 } = options ?? {};
+    const salt = randomBytes(saltLength);
+    const key = pbkdf2Sync(passphrase, salt, iterations, outputByteLength, 'sha256');
+    const saltString = salt.toString('hex');
+    const keyString = key.toString('hex');
+    return `${saltString}:${keyString}`;
 }
-export {
-  generate
-};

package/node/files/is-in-directory/index.js

@@ -1,11 +1,12 @@
-import "../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/node/files/is-in-directory/index.ts
-import path from "node:path";
-function isInDirectory(childPath, parentPath) {
-  const rel = path.relative(parentPath, childPath);
-  return rel !== "" && !rel.startsWith("..");
+import path from 'node:path';
+/**
+ * Checks whether a child path is contained within a parent directory.
+ *
+ * @param childPath  - The path to check if it's within the parent.
+ * @param parentPath - The parent directory path.
+ * @returns `true` if `childPath` is within `parentPath`, `false` otherwise.
+ */
+export function isInDirectory(childPath, parentPath) {
+    const rel = path.relative(parentPath, childPath);
+    return rel !== '' && !rel.startsWith('..');
 }
-export {
-  isInDirectory
-};

package/node/files/read-write/index.js

@@ -1,18 +1,12 @@
-import "../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/node/files/read-write/index.ts
-import { promises as fs } from "node:fs";
-async function readWrite(path, editor, opts = {}) {
-  const readData = await fs.readFile(path, opts.readOptions);
-  const edited = typeof editor === "function" ? editor(readData) : Object.entries(editor).reduce(
-    (acc, [from, to]) => acc.replaceAll(from, to),
-    readData.toString()
-  );
-  const actualWriteOptions = opts.writeOptions ?? opts.readOptions;
-  const targetOutput = opts.output ?? path;
-  if (opts.dryRun !== true) await fs.writeFile(targetOutput, edited, actualWriteOptions);
-  return edited;
+import { promises as fs } from 'node:fs';
+export async function readWrite(path, editor, opts = {}) {
+    const readData = await fs.readFile(path, opts.readOptions);
+    const edited = typeof editor === 'function'
+        ? editor(readData)
+        : Object.entries(editor).reduce((acc, [from, to]) => acc.replaceAll(from, to), readData.toString());
+    const actualWriteOptions = opts.writeOptions ?? opts.readOptions;
+    const targetOutput = opts.output ?? path;
+    if (opts.dryRun !== true)
+        await fs.writeFile(targetOutput, edited, actualWriteOptions);
+    return edited;
 }
-export {
-  readWrite
-};