@nshiab/simple-data-analysis 5.19.8

package/script/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/helpers/logToSheet.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = logToSheet;
+const node_process_1 = __importDefault(require("node:process"));
+const node_fs_1 = require("node:fs");
+const google_auth_library_1 = require("google-auth-library");
+const google_spreadsheet_1 = require("google-spreadsheet");
+/**
+ * Authenticates with Google Sheets and returns a worksheet object.
+ * @param sheetUrl The URL of the Google Sheet.
+ * @param options Optional authentication options.
+ * @returns A GoogleSpreadsheetWorksheet object.
+ */
+async function logToSheet(sheetUrl, options = {}) {
+    const urlItems = sheetUrl.split("/");
+    const spreadsheetId = urlItems[5];
+    const sheetId = urlItems[6].split("=")[1];
+    const emailVar = options.apiEmail ?? "GOOGLE_SERVICE_ACCOUNT_EMAIL";
+    const keyVar = options.apiKey ?? "GOOGLE_PRIVATE_KEY";
+    let email = node_process_1.default.env[emailVar];
+    let key = node_process_1.default.env[keyVar];
+    // Support GOOGLE_APPLICATION_CREDENTIALS
+    if (node_process_1.default.env.GOOGLE_APPLICATION_CREDENTIALS !== undefined &&
+        node_process_1.default.env.GOOGLE_APPLICATION_CREDENTIALS !== "" &&
+        (0, node_fs_1.existsSync)(node_process_1.default.env.GOOGLE_APPLICATION_CREDENTIALS)) {
+        const creds = JSON.parse((0, node_fs_1.readFileSync)(node_process_1.default.env.GOOGLE_APPLICATION_CREDENTIALS, "utf-8"));
+        email = creds.client_email;
+        key = creds.private_key;
+    }
+    if (email === undefined || email === "") {
+        throw new Error(`process.env.${emailVar} is undefined or ''.`);
+    }
+    if (key === undefined || key === "") {
+        throw new Error(`process.env.${keyVar} is undefined or ''.`);
+    }
+    const jwt = new google_auth_library_1.JWT({
+        email,
+        key,
+        scopes: ["https://www.googleapis.com/auth/spreadsheets"],
+    });
+    const spreadsheet = new google_spreadsheet_1.GoogleSpreadsheet(spreadsheetId, jwt);
+    await spreadsheet.loadInfo();
+    // @ts-expect-error sheetId is a string, but indexes are number?
+    const sheet = spreadsheet.sheetsById[sheetId];
+    if (sheet === undefined) {
+        throw new Error(`Sheet with ID ${sheetId} not found. Make sure the sheet URL ends with just one gid=ID.`);
+    }
+    return sheet;
+}

package/script/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/inBucket.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Checks if a specified file exists within a Google Cloud Storage (GCS) bucket. This function provides a straightforward way to verify the presence of a file in your GCS infrastructure, which is useful for conditional operations, data validation, or status checks.
+ *
+ * Authentication and bucket identification can be configured either through environment variables (`BUCKET_PROJECT` for the Google Cloud Project ID and `BUCKET_NAME` for the bucket name) or by passing them directly as options to the function. Options provided directly will take precedence over environment variables.
+ *
+ * @param destination - The full path to the file within the bucket (e.g., 'my-folder/my-file.txt').
+ * @param options - Optional settings for configuring the GCS client.
+ *   @param options.project - Your Google Cloud Project ID. If not provided, it defaults to the `BUCKET_PROJECT` environment variable.
+ *   @param options.bucket - The name of the Google Cloud Storage bucket. If not provided, it defaults to the `BUCKET_NAME` environment variable.
+ * @returns A Promise that resolves to `true` if the file exists in the bucket, and `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * // Check if a file exists in the default Google Cloud Storage bucket (configured via environment variables).
+ * const exists = await inBucket("remote/file.txt");
+ * if (exists) {
+ *   console.log("File exists in the bucket.");
+ * } else {
+ *   console.log("File does not exist in the bucket.");
+ * }
+ * ```
+ * @example
+ * ```ts
+ * // Check for a file's existence in a specified project and bucket, overriding environment variables.
+ * const existsInSpecificBucket = await inBucket("remote/file.txt", {
+ *  project: "my-gcp-project",
+ *  bucket: "my-bucket-name"
+ * });
+ * if (existsInSpecificBucket) {
+ *   console.log("File exists in the specified bucket.");
+ * } else {
+ *   console.log("File does not exist in the specified bucket.");
+ * }
+ * ```
+ * @category Google
+ */
+export default function inBucket(destination: string, options?: {
+    project?: string;
+    bucket?: string;
+}): Promise<boolean>;
+//# sourceMappingURL=inBucket.d.ts.map

package/script/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/inBucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inBucket.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/inBucket.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAA8B,QAAQ,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACZ,GACL,OAAO,CAAC,OAAO,CAAC,CAelB"}

package/script/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/inBucket.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = inBucket;
+const storage_1 = require("@google-cloud/storage");
+const node_process_1 = __importDefault(require("node:process"));
+/**
+ * Checks if a specified file exists within a Google Cloud Storage (GCS) bucket. This function provides a straightforward way to verify the presence of a file in your GCS infrastructure, which is useful for conditional operations, data validation, or status checks.
+ *
+ * Authentication and bucket identification can be configured either through environment variables (`BUCKET_PROJECT` for the Google Cloud Project ID and `BUCKET_NAME` for the bucket name) or by passing them directly as options to the function. Options provided directly will take precedence over environment variables.
+ *
+ * @param destination - The full path to the file within the bucket (e.g., 'my-folder/my-file.txt').
+ * @param options - Optional settings for configuring the GCS client.
+ *   @param options.project - Your Google Cloud Project ID. If not provided, it defaults to the `BUCKET_PROJECT` environment variable.
+ *   @param options.bucket - The name of the Google Cloud Storage bucket. If not provided, it defaults to the `BUCKET_NAME` environment variable.
+ * @returns A Promise that resolves to `true` if the file exists in the bucket, and `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * // Check if a file exists in the default Google Cloud Storage bucket (configured via environment variables).
+ * const exists = await inBucket("remote/file.txt");
+ * if (exists) {
+ *   console.log("File exists in the bucket.");
+ * } else {
+ *   console.log("File does not exist in the bucket.");
+ * }
+ * ```
+ * @example
+ * ```ts
+ * // Check for a file's existence in a specified project and bucket, overriding environment variables.
+ * const existsInSpecificBucket = await inBucket("remote/file.txt", {
+ *  project: "my-gcp-project",
+ *  bucket: "my-bucket-name"
+ * });
+ * if (existsInSpecificBucket) {
+ *   console.log("File exists in the specified bucket.");
+ * } else {
+ *   console.log("File does not exist in the specified bucket.");
+ * }
+ * ```
+ * @category Google
+ */
+async function inBucket(destination, options = {}) {
+    const projectId = options.project ?? node_process_1.default.env.BUCKET_PROJECT;
+    const bucketName = options.bucket ?? node_process_1.default.env.BUCKET_NAME;
+    if (!projectId || !bucketName) {
+        throw new Error("Project ID and bucket name must be provided. Make sure to set BUCKET_PROJECT and BUCKET_NAME environment variables or pass them in options.");
+    }
+    const s = new storage_1.Storage({ projectId });
+    const b = s.bucket(bucketName);
+    const file = b.file(destination);
+    const [exists] = await file.exists();
+    return exists;
+}

package/script/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/overwriteSheetData.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Clears the content of a Google Sheet and then populates it with new data. This function is useful for regularly updating datasets in Google Sheets, ensuring that the sheet always reflects the latest information without manual intervention.
+ *
+ * The function automatically infers column headers from the keys of the first object in your `data` array. It supports various options for customizing the update process, including adding a timestamp of the last update, prepending custom text, and controlling how Google Sheets interprets the data types.
+ *
+ * By default, authentication is handled via environment variables (`GOOGLE_PRIVATE_KEY` and `GOOGLE_SERVICE_ACCOUNT_EMAIL`). Alternatively, you can use `GOOGLE_APPLICATION_CREDENTIALS` pointing to a service account JSON file. For detailed setup instructions, refer to the `node-google-spreadsheet` authentication guide: [https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication](https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication).
+ *
+ * @param data - An array of objects to be written to the Google Sheet. The keys of the first object in this array will be used as column headers.
+ * @param sheetUrl - The URL of the Google Sheet to be updated. This URL should point to a specific sheet (e.g., ending with `#gid=0`).
+ * @param options - An optional object with configuration options:
+ *   @param options.prepend - A string to be added as a new row at the very top of the sheet, before any data or `lastUpdate` information. Useful for adding notes or disclaimers.
+ *   @param options.lastUpdate - If `true`, a row indicating the date and time of the update will be added before the data. Defaults to `false`.
+ *   @param options.timeZone - If `lastUpdate` is `true`, this option allows you to specify a time zone for the timestamp (e.g., `"Canada/Eastern"`). If omitted, the date will be formatted in UTC.
+ *   @param options.raw - If `true`, data will be written as raw values, preventing Google Sheets from automatically guessing data types or applying formatting. This can be useful for preserving exact string representations. Defaults to `false`.
+ *   @param options.apiEmail - Optional. Your Google Service Account email. If provided, this will override the `GOOGLE_SERVICE_ACCOUNT_EMAIL` environment variable.
+ *   @param options.apiKey - Optional. Your Google Service Account private key. If provided, this will override the `GOOGLE_PRIVATE_KEY` environment variable.
+ * @returns A Promise that resolves when the sheet has been successfully cleared and populated with new data.
+ *
+ * @example
+ * ```ts
+ * // The data needs to be an array of objects. The keys of the first object will be used to create the header row.
+ * const data = [
+ *   { first: "Nael", last: "Shiab" },
+ *   { first: "Andrew", last: "Ryan" }
+ * ];
+ * // Fake URL used as an example.
+ * const sheetUrl = "https://docs.google.com/spreadsheets/d/nrqo3oP4KMWYbELScQa8W1nHZPfIrA7LIz9UmcRE4GyJN/edit#gid=0";
+ *
+ * // Clearing the sheet and then populating it.
+ * await overwriteSheetData(data, sheetUrl);
+ * console.log("Sheet updated successfully with data.");
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Write data as raw values to prevent Google Sheets from interpreting them.
+ * const rawData = [
+ *   { id: '001', value: '05' }, // '05' might be interpreted as 5 without raw: true
+ *   { id: '002', value: '10' }
+ * ];
+ * await overwriteSheetData(rawData, sheetUrl, { raw: true });
+ * console.log("Sheet updated successfully with raw data.");
+ * ```
+ * @example
+ * ```ts
+ * // Add a timestamp of the update in UTC.
+ * await overwriteSheetData(data, sheetUrl, { lastUpdate: true });
+ * console.log("Sheet updated with UTC timestamp.");
+ *
+ * // Add a timestamp formatted to a specific time zone.
+ * await overwriteSheetData(data, sheetUrl, { lastUpdate: true, timeZone: "Canada/Eastern" });
+ * console.log("Sheet updated with Eastern Time timestamp.");
+ * ```
+ * @example
+ * ```ts
+ * // Add a custom message at the top of the sheet.
+ * await overwriteSheetData(data, sheetUrl, { prepend: "For inquiries, contact data.team@example.com" });
+ * console.log("Sheet updated with prepended text.");
+ *
+ * // Combine prepend with last update and time zone.
+ * await overwriteSheetData(data, sheetUrl, {
+ *   prepend: "For inquiries, contact data.team@example.com",
+ *   lastUpdate: true,
+ *   timeZone: "Canada/Eastern"
+ * });
+ * console.log("Sheet updated with prepended text and timestamp.");
+ * ```
+ * @example
+ * ```ts
+ * // Use explicitly provided API credentials instead of environment variables.
+ * await overwriteSheetData(data, sheetUrl, {
+ *   apiEmail: "your-service-account@project-id.iam.gserviceaccount.com",
+ *   apiKey: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
+ * });
+ * console.log("Sheet updated using custom API credentials.");
+ * ```
+ * @category Google
+ */
+export default function overwriteSheetData(data: {
+    [key: string]: string | number | boolean | Date | null;
+}[], sheetUrl: string, options?: {
+    prepend?: string;
+    lastUpdate?: boolean;
+    timeZone?: "Canada/Atlantic" | "Canada/Central" | "Canada/Eastern" | "Canada/Mountain" | "Canada/Newfoundland" | "Canada/Pacific" | "Canada/Saskatchewan" | "Canada/Yukon";
+    raw?: boolean;
+    apiEmail?: string;
+    apiKey?: string;
+}): Promise<void>;
+//# sourceMappingURL=overwriteSheetData.d.ts.map

package/script/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/overwriteSheetData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overwriteSheetData.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/overwriteSheetData.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AAEH,wBAA8B,kBAAkB,CAC9C,IAAI,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,CAAA;CAAE,EAAE,EAClE,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EACL,iBAAiB,GACjB,gBAAgB,GAChB,gBAAgB,GAChB,iBAAiB,GACjB,qBAAqB,GACrB,gBAAgB,GAChB,qBAAqB,GACrB,cAAc,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACZ,GACL,OAAO,CAAC,IAAI,CAAC,CAsCf"}

package/script/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/overwriteSheetData.js

@@ -0,0 +1,122 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = overwriteSheetData;
+const index_js_1 = require("../../../../journalism-format/1.1.5/src/index.js");
+const cleanData_js_1 = __importDefault(require("./helpers/cleanData.js"));
+const logToSheet_js_1 = __importDefault(require("./helpers/logToSheet.js"));
+/**
+ * Clears the content of a Google Sheet and then populates it with new data. This function is useful for regularly updating datasets in Google Sheets, ensuring that the sheet always reflects the latest information without manual intervention.
+ *
+ * The function automatically infers column headers from the keys of the first object in your `data` array. It supports various options for customizing the update process, including adding a timestamp of the last update, prepending custom text, and controlling how Google Sheets interprets the data types.
+ *
+ * By default, authentication is handled via environment variables (`GOOGLE_PRIVATE_KEY` and `GOOGLE_SERVICE_ACCOUNT_EMAIL`). Alternatively, you can use `GOOGLE_APPLICATION_CREDENTIALS` pointing to a service account JSON file. For detailed setup instructions, refer to the `node-google-spreadsheet` authentication guide: [https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication](https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication).
+ *
+ * @param data - An array of objects to be written to the Google Sheet. The keys of the first object in this array will be used as column headers.
+ * @param sheetUrl - The URL of the Google Sheet to be updated. This URL should point to a specific sheet (e.g., ending with `#gid=0`).
+ * @param options - An optional object with configuration options:
+ *   @param options.prepend - A string to be added as a new row at the very top of the sheet, before any data or `lastUpdate` information. Useful for adding notes or disclaimers.
+ *   @param options.lastUpdate - If `true`, a row indicating the date and time of the update will be added before the data. Defaults to `false`.
+ *   @param options.timeZone - If `lastUpdate` is `true`, this option allows you to specify a time zone for the timestamp (e.g., `"Canada/Eastern"`). If omitted, the date will be formatted in UTC.
+ *   @param options.raw - If `true`, data will be written as raw values, preventing Google Sheets from automatically guessing data types or applying formatting. This can be useful for preserving exact string representations. Defaults to `false`.
+ *   @param options.apiEmail - Optional. Your Google Service Account email. If provided, this will override the `GOOGLE_SERVICE_ACCOUNT_EMAIL` environment variable.
+ *   @param options.apiKey - Optional. Your Google Service Account private key. If provided, this will override the `GOOGLE_PRIVATE_KEY` environment variable.
+ * @returns A Promise that resolves when the sheet has been successfully cleared and populated with new data.
+ *
+ * @example
+ * ```ts
+ * // The data needs to be an array of objects. The keys of the first object will be used to create the header row.
+ * const data = [
+ *   { first: "Nael", last: "Shiab" },
+ *   { first: "Andrew", last: "Ryan" }
+ * ];
+ * // Fake URL used as an example.
+ * const sheetUrl = "https://docs.google.com/spreadsheets/d/nrqo3oP4KMWYbELScQa8W1nHZPfIrA7LIz9UmcRE4GyJN/edit#gid=0";
+ *
+ * // Clearing the sheet and then populating it.
+ * await overwriteSheetData(data, sheetUrl);
+ * console.log("Sheet updated successfully with data.");
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Write data as raw values to prevent Google Sheets from interpreting them.
+ * const rawData = [
+ *   { id: '001', value: '05' }, // '05' might be interpreted as 5 without raw: true
+ *   { id: '002', value: '10' }
+ * ];
+ * await overwriteSheetData(rawData, sheetUrl, { raw: true });
+ * console.log("Sheet updated successfully with raw data.");
+ * ```
+ * @example
+ * ```ts
+ * // Add a timestamp of the update in UTC.
+ * await overwriteSheetData(data, sheetUrl, { lastUpdate: true });
+ * console.log("Sheet updated with UTC timestamp.");
+ *
+ * // Add a timestamp formatted to a specific time zone.
+ * await overwriteSheetData(data, sheetUrl, { lastUpdate: true, timeZone: "Canada/Eastern" });
+ * console.log("Sheet updated with Eastern Time timestamp.");
+ * ```
+ * @example
+ * ```ts
+ * // Add a custom message at the top of the sheet.
+ * await overwriteSheetData(data, sheetUrl, { prepend: "For inquiries, contact data.team@example.com" });
+ * console.log("Sheet updated with prepended text.");
+ *
+ * // Combine prepend with last update and time zone.
+ * await overwriteSheetData(data, sheetUrl, {
+ *   prepend: "For inquiries, contact data.team@example.com",
+ *   lastUpdate: true,
+ *   timeZone: "Canada/Eastern"
+ * });
+ * console.log("Sheet updated with prepended text and timestamp.");
+ * ```
+ * @example
+ * ```ts
+ * // Use explicitly provided API credentials instead of environment variables.
+ * await overwriteSheetData(data, sheetUrl, {
+ *   apiEmail: "your-service-account@project-id.iam.gserviceaccount.com",
+ *   apiKey: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
+ * });
+ * console.log("Sheet updated using custom API credentials.");
+ * ```
+ * @category Google
+ */
+async function overwriteSheetData(data, sheetUrl, options = {}) {
+    const sheet = await (0, logToSheet_js_1.default)(sheetUrl, options);
+    await sheet.clear();
+    let startIndex = 1;
+    if (typeof options.prepend === "string" || options.lastUpdate) {
+        await sheet.loadCells("A1:B2");
+    }
+    if (typeof options.prepend === "string") {
+        const cellPrepend = sheet.getCellByA1(`A${startIndex}`);
+        cellPrepend.value = options.prepend;
+        startIndex += 1;
+    }
+    if (options.lastUpdate) {
+        const cellLastUpdate = sheet.getCellByA1(`A${startIndex}`);
+        cellLastUpdate.value = "Last update:";
+        const cellDate = sheet.getCellByA1(`B${startIndex}`);
+        if (typeof options.timeZone === "string") {
+            cellDate.value = (0, index_js_1.formatDate)(new Date(), "YYYY-MM-DD HH:MM:SS TZ", {
+                timeZone: options.timeZone,
+            });
+        }
+        else {
+            cellDate.value = (0, index_js_1.formatDate)(new Date(), "YYYY-MM-DD HH:MM:SS TZ", {
+                utc: true,
+            });
+        }
+        startIndex += 1;
+    }
+    if (typeof options.prepend === "string" || options.lastUpdate) {
+        await sheet.saveUpdatedCells();
+    }
+    const headerRow = Object.keys(data[0]);
+    await sheet.setHeaderRow(headerRow, startIndex);
+    await sheet.addRows((0, cleanData_js_1.default)(data), { raw: options.raw });
+}

package/script/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/toBucket.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Uploads a local file to a Google Cloud Storage (GCS) bucket and returns the URI of the uploaded file. This function provides robust control over the upload process, including options for skipping uploads if the file already exists, overwriting existing files, and setting custom metadata.
+ *
+ * By default, if a file with the same destination path already exists in the bucket, an error will be thrown to prevent accidental overwrites. You can modify this behavior using the `skip` or `overwrite` options.
+ *
+ * Authentication and bucket identification can be configured either through environment variables (`BUCKET_PROJECT` for the Google Cloud Project ID and `BUCKET_NAME` for the bucket name) or by passing them directly as options to the function. Options provided directly will take precedence over environment variables.
+ *
+ * @param file - The absolute or relative path to the local file that you want to upload.
+ * @param destination - The desired path and filename for the file within the GCS bucket (e.g., `"my-folder/my-uploaded-file.txt"`).
+ * @param options - Optional settings to customize the upload behavior.
+ *   @param options.project - Your Google Cloud Project ID. If not provided, it defaults to the `BUCKET_PROJECT` environment variable.
+ *   @param options.bucket - The name of the Google Cloud Storage bucket. If not provided, it defaults to the `BUCKET_NAME` environment variable.
+ *   @param options.metadata - An object containing custom metadata to be associated with the uploaded file (e.g., `contentType`, `cacheControl`). This is passed directly to the GCS upload options.
+ *   @param options.overwrite - If `true`, an existing file at the `destination` path in the bucket will be overwritten. Cannot be used with `skip: true`. Defaults to `false`.
+ *   @param options.skip - If `true`, the upload will be skipped if a file with the same `destination` path already exists in the bucket. If the local file does not exist but the remote file does, the URI of the remote file will be returned without an error. Cannot be used with `overwrite: true`. Defaults to `false`.
+ * @returns A Promise that resolves to the Google Cloud Storage URI of the uploaded file (e.g., `"gs://your-bucket-name/your-file-path.txt"`).
+ *
+ * @example
+ * ```ts
+ * // Upload a file using environment variables for project and bucket.
+ * // Assuming `BUCKET_PROJECT` and `BUCKET_NAME` are set in your environment.
+ * const uri = await toBucket("./local/file.txt", "remote/file.txt");
+ * console.log(uri); // "gs://my-bucket/remote/file.txt"
+ * ```
+ * @example
+ * ```ts
+ * // Skip upload if the file already exists in the bucket.
+ * const uriSkip = await toBucket("./local/file.txt", "remote/file.txt", {
+ *   skip: true
+ * });
+ * console.log(uriSkip); // Returns URI whether file was uploaded or already existed
+ * ```
+ * @example
+ * ```ts
+ * // If the local file doesn't exist but the remote file does, the URI is returned without error.
+ * // (Assuming "./non-existent.txt" does not exist locally, but "remote/file.txt" exists in the bucket)
+ * const uriNonExistentLocal = await toBucket("./non-existent.txt", "remote/file.txt", {
+ *   skip: true
+ * });
+ * console.log(uriNonExistentLocal); // "gs://my-bucket/remote/file.txt"
+ * ```
+ * @example
+ * ```ts
+ * // Overwrite an existing file in the bucket.
+ * const uriOverwrite = await toBucket("./local/file.txt", "remote/file.txt", {
+ *   overwrite: true
+ * });
+ * console.log(uriOverwrite); // "gs://my-bucket/remote/file.txt"
+ * ```
+ * @example
+ * ```ts
+ * // Upload a file with specified project, bucket, and custom metadata.
+ * const uriExplicit = await toBucket("./local/file.txt", "remote/file.txt", {
+ *   project: "my-gcp-project",
+ *   bucket: "my-bucket-name",
+ *   metadata: {
+ *     contentType: "text/plain",
+ *     cacheControl: "public, max-age=3600"
+ *   }
+ * });
+ * console.log(uriExplicit);
+ * ```
+ * @category Google
+ */
+export default function toBucket(file: string, destination: string, options?: {
+    project?: string;
+    bucket?: string;
+    metadata?: any;
+    overwrite?: boolean;
+    skip?: boolean;
+}): Promise<string>;
+//# sourceMappingURL=toBucket.d.ts.map

package/script/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/toBucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toBucket.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/toBucket.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAA8B,QAAQ,CACpC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,QAAQ,CAAC,EAAE,GAAG,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,OAAO,CAAC;CACX,GACL,OAAO,CAAC,MAAM,CAAC,CAqDjB"}

package/script/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/toBucket.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = toBucket;
+const storage_1 = require("@google-cloud/storage");
+const node_process_1 = __importDefault(require("node:process"));
+const node_fs_1 = require("node:fs");
+/**
+ * Uploads a local file to a Google Cloud Storage (GCS) bucket and returns the URI of the uploaded file. This function provides robust control over the upload process, including options for skipping uploads if the file already exists, overwriting existing files, and setting custom metadata.
+ *
+ * By default, if a file with the same destination path already exists in the bucket, an error will be thrown to prevent accidental overwrites. You can modify this behavior using the `skip` or `overwrite` options.
+ *
+ * Authentication and bucket identification can be configured either through environment variables (`BUCKET_PROJECT` for the Google Cloud Project ID and `BUCKET_NAME` for the bucket name) or by passing them directly as options to the function. Options provided directly will take precedence over environment variables.
+ *
+ * @param file - The absolute or relative path to the local file that you want to upload.
+ * @param destination - The desired path and filename for the file within the GCS bucket (e.g., `"my-folder/my-uploaded-file.txt"`).
+ * @param options - Optional settings to customize the upload behavior.
+ *   @param options.project - Your Google Cloud Project ID. If not provided, it defaults to the `BUCKET_PROJECT` environment variable.
+ *   @param options.bucket - The name of the Google Cloud Storage bucket. If not provided, it defaults to the `BUCKET_NAME` environment variable.
+ *   @param options.metadata - An object containing custom metadata to be associated with the uploaded file (e.g., `contentType`, `cacheControl`). This is passed directly to the GCS upload options.
+ *   @param options.overwrite - If `true`, an existing file at the `destination` path in the bucket will be overwritten. Cannot be used with `skip: true`. Defaults to `false`.
+ *   @param options.skip - If `true`, the upload will be skipped if a file with the same `destination` path already exists in the bucket. If the local file does not exist but the remote file does, the URI of the remote file will be returned without an error. Cannot be used with `overwrite: true`. Defaults to `false`.
+ * @returns A Promise that resolves to the Google Cloud Storage URI of the uploaded file (e.g., `"gs://your-bucket-name/your-file-path.txt"`).
+ *
+ * @example
+ * ```ts
+ * // Upload a file using environment variables for project and bucket.
+ * // Assuming `BUCKET_PROJECT` and `BUCKET_NAME` are set in your environment.
+ * const uri = await toBucket("./local/file.txt", "remote/file.txt");
+ * console.log(uri); // "gs://my-bucket/remote/file.txt"
+ * ```
+ * @example
+ * ```ts
+ * // Skip upload if the file already exists in the bucket.
+ * const uriSkip = await toBucket("./local/file.txt", "remote/file.txt", {
+ *   skip: true
+ * });
+ * console.log(uriSkip); // Returns URI whether file was uploaded or already existed
+ * ```
+ * @example
+ * ```ts
+ * // If the local file doesn't exist but the remote file does, the URI is returned without error.
+ * // (Assuming "./non-existent.txt" does not exist locally, but "remote/file.txt" exists in the bucket)
+ * const uriNonExistentLocal = await toBucket("./non-existent.txt", "remote/file.txt", {
+ *   skip: true
+ * });
+ * console.log(uriNonExistentLocal); // "gs://my-bucket/remote/file.txt"
+ * ```
+ * @example
+ * ```ts
+ * // Overwrite an existing file in the bucket.
+ * const uriOverwrite = await toBucket("./local/file.txt", "remote/file.txt", {
+ *   overwrite: true
+ * });
+ * console.log(uriOverwrite); // "gs://my-bucket/remote/file.txt"
+ * ```
+ * @example
+ * ```ts
+ * // Upload a file with specified project, bucket, and custom metadata.
+ * const uriExplicit = await toBucket("./local/file.txt", "remote/file.txt", {
+ *   project: "my-gcp-project",
+ *   bucket: "my-bucket-name",
+ *   metadata: {
+ *     contentType: "text/plain",
+ *     cacheControl: "public, max-age=3600"
+ *   }
+ * });
+ * console.log(uriExplicit);
+ * ```
+ * @category Google
+ */
+async function toBucket(file, destination, options = {}) {
+    const projectId = options.project ?? node_process_1.default.env.BUCKET_PROJECT;
+    const bucketName = options.bucket ?? node_process_1.default.env.BUCKET_NAME;
+    if (options.skip && options.overwrite) {
+        throw new Error("Cannot use both 'skip' and 'overwrite' options at the same time. Choose one: set 'skip: true' to skip existing files or 'overwrite: true' to replace them.");
+    }
+    if (!projectId || !bucketName) {
+        throw new Error("Project ID and bucket name must be provided. Make sure to set BUCKET_PROJECT and BUCKET_NAME environment variables or pass them in options.");
+    }
+    const s = new storage_1.Storage({
+        projectId: projectId,
+    });
+    const b = s.bucket(bucketName);
+    const fileRef = b.file(destination);
+    const [exists] = await fileRef.exists();
+    if (options.skip) {
+        const localFileExists = (0, node_fs_1.existsSync)(file);
+        if (!localFileExists && exists) {
+            // Local file doesn't exist but remote file does, return URI
+            return `gs://${bucketName}/${destination}`;
+        }
+        if (!localFileExists && !exists) {
+            // Neither local nor remote file exists, throw error
+            throw new Error(`Local file '${file}' does not exist. Cannot upload to bucket.`);
+        }
+        if (exists) {
+            // Local file exists and remote file exists, skip upload
+            return `gs://${bucketName}/${destination}`;
+        }
+        // Local file exists but remote file doesn't, proceed with upload
+    }
+    else if (exists && !options.overwrite) {
+        throw new Error(`File '${destination}' already exists in bucket '${bucketName}'. Set overwrite: true to replace it or skip: true to skip upload.`);
+    }
+    await b.upload(file, {
+        destination,
+        metadata: options.metadata,
+    });
+    return `gs://${bucketName}/${destination}`;
+}

package/script/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/index.d.ts

@@ -0,0 +1,10 @@
+import addSheetRows from "./google/addSheetRows.js";
+import overwriteSheetData from "./google/overwriteSheetData.js";
+import getSheetData from "./google/getSheetData.js";
+import toBucket from "./google/toBucket.js";
+import deleteFromBucket from "./google/deleteFromBucket.js";
+import inBucket from "./google/inBucket.js";
+import downloadFromBucket from "./google/downloadFromBucket.js";
+import filesInBucket from "./google/filesInBucket.js";
+export { addSheetRows, deleteFromBucket, downloadFromBucket, filesInBucket, getSheetData, inBucket, overwriteSheetData, toBucket, };
+//# sourceMappingURL=index.d.ts.map

package/script/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../src/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,0BAA0B,CAAC;AACpD,OAAO,kBAAkB,MAAM,gCAAgC,CAAC;AAChE,OAAO,YAAY,MAAM,0BAA0B,CAAC;AACpD,OAAO,QAAQ,MAAM,sBAAsB,CAAC;AAC5C,OAAO,gBAAgB,MAAM,8BAA8B,CAAC;AAC5D,OAAO,QAAQ,MAAM,sBAAsB,CAAC;AAC5C,OAAO,kBAAkB,MAAM,gCAAgC,CAAC;AAChE,OAAO,aAAa,MAAM,2BAA2B,CAAC;AAEtD,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,kBAAkB,EAClB,QAAQ,GACT,CAAC"}

package/script/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBucket = exports.overwriteSheetData = exports.inBucket = exports.getSheetData = exports.filesInBucket = exports.downloadFromBucket = exports.deleteFromBucket = exports.addSheetRows = void 0;
+const addSheetRows_js_1 = __importDefault(require("./google/addSheetRows.js"));
+exports.addSheetRows = addSheetRows_js_1.default;
+const overwriteSheetData_js_1 = __importDefault(require("./google/overwriteSheetData.js"));
+exports.overwriteSheetData = overwriteSheetData_js_1.default;
+const getSheetData_js_1 = __importDefault(require("./google/getSheetData.js"));
+exports.getSheetData = getSheetData_js_1.default;
+const toBucket_js_1 = __importDefault(require("./google/toBucket.js"));
+exports.toBucket = toBucket_js_1.default;
+const deleteFromBucket_js_1 = __importDefault(require("./google/deleteFromBucket.js"));
+exports.deleteFromBucket = deleteFromBucket_js_1.default;
+const inBucket_js_1 = __importDefault(require("./google/inBucket.js"));
+exports.inBucket = inBucket_js_1.default;
+const downloadFromBucket_js_1 = __importDefault(require("./google/downloadFromBucket.js"));
+exports.downloadFromBucket = downloadFromBucket_js_1.default;
+const filesInBucket_js_1 = __importDefault(require("./google/filesInBucket.js"));
+exports.filesInBucket = filesInBucket_js_1.default;