h56-github-scrapper 1.0.6 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "h56-github-scrapper",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "GitHub user scraper",
   "type": "module",
   "main": "main-scrapping.js",

package/readme.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/h56-github-scrapper.svg)](https://www.npmjs.com/package/h56-github-scrapper)
 [![Downloads/month](https://img.shields.io/npm/dm/h56-github-scrapper.svg)](https://www.npmjs.com/package/h56-github-scrapper)
 [![Node](https://img.shields.io/badge/node-%3E%3D16-brightgreen.svg?logo=node.js)](https://nodejs.org/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?logo=github)](./LICENSE)
 [![TypeScript friendly](https://img.shields.io/badge/types-TypeScript-blue.svg?logo=typescript)](https://www.typescriptlang.org/)
 [![Translator: optional](https://img.shields.io/badge/translator-h56--translator-lightgrey.svg?logo=googletranslate)](https://www.npmjs.com/package/h56-translator)
 
@@ -309,4 +309,195 @@ Kontribusi disambut. Silakan:
 - Ikuti style guide dan sertakan deskripsi perubahan pada PR.
 
 Changelog singkat (ringkasan):
-- v1.0.0 — Core scraper + optional translator support (h56-translator) + CLI translate flags.
+- v1.0.0 — Core scraper + optional translator support (h56-translator) + CLI translate flags.
+
+---
+
+## Contoh Implementasi ESM Node.js — Detail lengkap (Tambahan dokumentasi)
+
+Bagian ini memberikan panduan langkah demi langkah dan contoh kode ESM (Node.js) yang lebih komprehensif untuk mengimpor paket, mengkonfigurasi scraper, menangani opsi terjemahan (opsional), dan menyimpan hasil full data akun GitHub ke file JSON. Semua contoh menggunakan ESM (".mjs" atau package.json "type": "module") dan Node.js >= 16.
+
+Catatan singkat:
+- Jika Anda menginstall paket via npm dan menggunakan ESM, Anda dapat memakai dynamic import atau static import (tergantung cara publish). Contoh di bawah menggunakan dynamic import agar langsung kompatibel dengan berbagai skenario.
+- Contoh juga menunjukkan opsi untuk menangani kasus ketika `h56-translator` tidak tersedia.
+
+1) Contoh file: scrape-full-esm.mjs
+- Perintah menjalankan: node scrape-full-esm.mjs <github-username> [--lang=<lang>] [--output=<path>] [--no-spinner]
+- Fungsi: scrape full data (profile, repos, stats), coba terjemahkan bila diminta, simpan ke file JSON atau cetak ke stdout.
+
+```js
+// scrape-full-esm.mjs
+// Usage: node scrape-full-esm.mjs <username> [--lang=en] [--output=./result.json] [--no-spinner]
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import process from "process";
+
+const argv = process.argv.slice(2);
+
+// Minimal CLI parsing (boleh ganti dengan yargs jika ingin)
+function parseArgs(args) {
+  const out = { _: [] };
+  for (const a of args) {
+    if (a.startsWith("--lang=")) out.lang = a.split("=")[1];
+    else if (a.startsWith("--output=")) out.output = a.split("=")[1];
+    else if (a === "--no-spinner") out.noSpinner = true;
+    else out._.push(a);
+  }
+  return out;
+}
+
+const parsed = parseArgs(argv);
+const username = parsed._[0];
+
+if (!username) {
+  console.error("Usage: node scrape-full-esm.mjs <username> [--lang=en] [--output=./res.json] [--no-spinner]");
+  process.exit(2);
+}
+
+(async () => {
+  try {
+    // dynamic import library (ESM)
+    const pkg = await import("h56-github-scrapper");
+    // package exports: scrapeUser, scrapeProfile, scrapeRepos, GithubScraper, h56translate, printResult
+    const {
+      scrapeUser,
+      GithubScraper,
+      h56translate,
+      printResult,
+    } = pkg;
+
+    // Example: use defaultScraper via scrapeUser (simple)
+    const translateOpt = parsed.lang
+      ? {
+          lang: parsed.lang,
+          fields: ["bio", "repo_descriptions"], // default fields
+          perRepoDelay: 120,
+          failOnMissing: false, // don't fail if translator missing
+        }
+      : undefined;
+
+    console.log("Scraping user:", username);
+    const result = await scrapeUser(username, {
+      spinner: !parsed.noSpinner,
+      translate: translateOpt,
+    });
+
+    // Pretty-print to console using built-in helper (optional)
+    if (!parsed.output) {
+      // readable print
+      printResult(result.profile, result.stats, result.repos);
+      // also output JSON to stdout if desired
+      console.log("JSON output:");
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      const outPath = path.resolve(parsed.output);
+      fs.writeFileSync(outPath, JSON.stringify(result, null, 2) + "\n", "utf8");
+      console.log("Saved JSON to", outPath);
+    }
+  } catch (err) {
+    console.error("Error scraping:", err && err.message ? err.message : String(err));
+    if (err && err.cause && err.cause.message) {
+      console.error("Cause:", err.cause.message);
+    }
+    process.exit(1);
+  }
+})();
+```
+
+2) Contoh: menggunakan class GithubScraper untuk konfigurasi lanjutan
+- Anda mungkin ingin mengubah timeout, user-agent, atau delay. Gunakan `new GithubScraper({ ... })`.
+
+```js
+// scrape-custom-esm.mjs
+import fs from "fs";
+import path from "path";
+const { GithubScraper } = await import("h56-github-scrapper");
+
+const scraper = new GithubScraper({
+  REQUEST_TIMEOUT: 30000,
+  SCRAPE_DELAY: 600,
+  MAX_RETRY: 4,
+  USER_AGENT: "MyBot/1.0 (+https://example.com/mybot)",
+});
+
+async function run(username, outFile) {
+  try {
+    const result = await scraper.scrapeUser(username, {
+      spinner: true,
+      translate: { lang: "en", fields: ["bio"], perRepoDelay: 120, failOnMissing: false },
+    });
+    fs.writeFileSync(path.resolve(outFile), JSON.stringify(result, null, 2) + "\n", "utf8");
+    console.log("Saved:", outFile);
+  } catch (e) {
+    console.error("Failed:", e.message || e);
+  }
+}
+
+await run("HASYIM56", "./hasyim56-full.json");
+```
+
+3) Contoh: memanggil helper terjemahan langsung (h56translate) — menangani ketiadaan translator
+- Helper `h56translate` akan melempar error bila translator tidak tersedia. Tangani dengan try/catch.
+
+```js
+// translate-direct.mjs
+const { h56translate } = await import("h56-github-scrapper");
+
+async function example() {
+  try {
+    const r = await h56translate("Halo dunia, ini contoh bio", "en");
+    console.log("Translated:", r.translatedText);
+  } catch (err) {
+    console.warn("Translator helper unavailable:", err.message);
+    // fallback: continue tanpa terjemahan
+  }
+}
+
+await example();
+```
+
+4) Praktik terbaik & tips pada implementasi ESM:
+- Pastikan project Anda menggunakan "type": "module" di package.json atau gunakan ekstensi .mjs untuk file ESM.
+- Jika Anda menjalankan pada lingkungan CI, disable spinner (`spinner: false` atau `--no-spinner`) untuk hasil yang bersih.
+- Kelola `SCRAPE_DELAY` dan `perRepoDelay` untuk menghindari rate-limiting dari layanan penerjemah atau beban berlebih ke GitHub.
+- Untuk penggunaan skala besar, simpan hasil terjemahan ke cache (file/db) agar tidak melakukan permintaan ulang terjemahan.
+- Tangani error network dan kasus "Username not found" (kode error: `NOT_FOUND`) saat memanggil `scrapeUser` atau `scrapeProfile`.
+
+5) Contoh alur end-to-end (script yang menerima daftar username dan menyimpan masing-masing ke file)
+```js
+// batch-scrape.mjs
+import fs from "fs";
+import path from "path";
+
+const { scrapeUser } = await import("h56-github-scrapper");
+
+// contoh daftar
+const users = ["octocat", "HASYIM56", "someuser"];
+
+for (const u of users) {
+  try {
+    console.log("Scraping", u);
+    const res = await scrapeUser(u, { spinner: false, translate: undefined });
+    const out = path.resolve(`./output-${u}.json`);
+    fs.writeFileSync(out, JSON.stringify(res, null, 2) + "\n", "utf8");
+    console.log("Saved", out);
+  } catch (e) {
+    console.error("Failed to scrape", u, e.message || e);
+  }
+  // disarankan memberi delay antar akun untuk sopan-santun
+  await new Promise((r) => setTimeout(r, 500));
+}
+```
+
+Ringkasan tambahan:
+- Gunakan contoh `scrape-full-esm.mjs` untuk kebutuhan satu akun sederhana.
+- Gunakan `GithubScraper` jika perlu konfigurasi param runtime (timeout, user-agent, delay).
+- Gunakan `h56translate` atau opsi `translate` di `scrapeUser` bila memerlukan terjemahan, dan selalu tangani kemungkinan ketiadaan paket `h56-translator`.
+
+---
+
+## License
+
+MIT