{"_id":"@arc-lang/arc-import-export","name":"@arc-lang/arc-import-export","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@arc-lang/arc-import-export","version":"0.1.0","description":"One-line import/export for every arc-cms admin table — CSV, JSON, XLSX with preview, history, and upsert. Zero per-page code.","main":"index.js","type":"commonjs","keywords":["arc","arc-cms","arc-language","cms","import","export","csv","xlsx","json","admin","data-import","data-export","django-import-export","bun","admin-panel","headless-cms"],"author":{"name":"KCuppens"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/arc-language/arc-import-export.git"},"homepage":"https://github.com/arc-language/arc-import-export#readme","bugs":{"url":"https://github.com/arc-language/arc-import-export/issues"},"scripts":{"size":"SIZE=$(wc -c < src/server/bar.js); if [ \"$SIZE\" -gt 24576 ]; then echo \"bar.js too large: ${SIZE}B (limit: 24576B)\"; exit 1; fi; echo \"bar.js: ${SIZE}B OK\"","lint":"bun run size && bun -e \"const ie = require('.'); if (!ie.version) { console.error('version missing'); process.exit(1); } console.log('exports OK, version:', ie.version)\""},"engines":{"bun":">=1.0.0"},"dependencies":{"xlsx":"0.18.5"},"peerDependencies":{"@arc-lang/arc-cms":">=0.1.0"},"peerDependenciesMeta":{"@arc-lang/arc-cms":{"optional":true}},"publishConfig":{"access":"public"},"gitHead":"62a53f9784b682a04cef40efa55565ecfeced9f0","_id":"@arc-lang/arc-import-export@0.1.0","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-SU+Ip4kgzGZ7/zF5fIeaGPsMXNXMOkvnzJp7oZYuVwk5cA+kj/hx8aZ36dLA9vPtgeOGOyLl2ZkBwp1sPuX3hg==","shasum":"526d0533c94b79a3c95d69975299672dfcf44327","tarball":"https://registry.npmjs.org/@arc-lang/arc-import-export/-/arc-import-export-0.1.0.tgz","fileCount":15,"unpackedSize":77921,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCcQtGUq5etB23BpmGrXhojFk9SgRqVpCoGxZYgdKD3NQIgRgmjVpOrAkWcm4vpEtoioeHDeyMZw1+/kQzjD2ZP0mw="}]},"_npmUser":{"name":"kobecuppens","email":"kobecuppens@hotmail.com"},"directories":{},"maintainers":[{"name":"kobecuppens","email":"kobecuppens@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/arc-import-export_0.1.0_1780407176640_0.47394928215447774"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-02T13:32:56.527Z","0.1.0":"2026-06-02T13:32:56.778Z","modified":"2026-06-02T13:32:56.977Z"},"maintainers":[{"name":"kobecuppens","email":"kobecuppens@hotmail.com"}],"description":"One-line import/export for every arc-cms admin table — CSV, JSON, XLSX with preview, history, and upsert. Zero per-page code.","homepage":"https://github.com/arc-language/arc-import-export#readme","keywords":["arc","arc-cms","arc-language","cms","import","export","csv","xlsx","json","admin","data-import","data-export","django-import-export","bun","admin-panel","headless-cms"],"repository":{"type":"git","url":"git+https://github.com/arc-language/arc-import-export.git"},"author":{"name":"KCuppens"},"bugs":{"url":"https://github.com/arc-language/arc-import-export/issues"},"license":"MIT","readme":"# arc-import-export\n\n[![npm](https://img.shields.io/npm/v/@arc-language/arc-import-export?style=flat-square&color=7b2fff)](https://www.npmjs.com/package/@arc-language/arc-import-export)\n[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)\n[![bun](https://img.shields.io/badge/runtime-bun-F9F1E1?style=flat-square&logo=bun)](https://bun.sh)\n\n**One-line import/export for every [arc-cms](https://github.com/arc-language/arc) admin table.**\n\nDrop one `<script>` tag into your CmsLayout and every admin page with a table instantly gets CSV, JSON, and XLSX import/export — with a 3-step preview wizard, upsert support, and a full audit history. Zero per-page code required.\n\nInspired by [django-import-export](https://github.com/django-import-export/django-import-export).\n\n---\n\n## Features\n\n- **Auto-activates** on every `<table>` in the admin — no widget imports, no per-page code\n- **↓ Export** to CSV, JSON, or XLSX in one click\n- **↑ Import** with a 3-step wizard: Upload → Preview (dry-run with error highlighting) → Confirm\n- **Upsert support** — update existing records by a unique field, create new ones\n- **Batched commits** — 500-row batches keep memory flat on large datasets\n- **Full history** at `/admin/import-export` — every import and export logged with row counts and errors\n- **Lazy XLSX** — SheetJS only loads when an XLSX request is actually made; CSV/JSON have zero runtime deps\n- **Dark mode native** — uses your site's `--ui-*` CSS variables automatically\n- **Override-friendly** — works on customized/overridden admin pages too\n\n---\n\n## Install\n\n```bash\nbun add @arc-language/arc-import-export\n```\n\n---\n\n## Setup (3 steps)\n\n### 1. Register the package in your Arc project\n\nIn `arc.config.json`, add the server routes and schema:\n\n```json\n{\n  \"serverRoutes\": [\n    \"node_modules/@arc-language/arc-import-export/src/server/import-export.arc\"\n  ],\n  \"schemas\": [\n    \"node_modules/@arc-language/arc-import-export/src/server/schemas/import-log.arc\"\n  ]\n}\n```\n\n### 2. Add the script tag to CmsLayout\n\nIn `site/cms/CmsLayout.arc`, add one line after your existing scripts:\n\n```arc\n@raw '<script src=\"/arc-ie/bar.js\" defer></script>'\n```\n\n> If you installed arc-cms via `arc cms init`, this line is already there.\n\n### 3. Create a config file\n\nIn your project root, create `arc-import-export.config.js`:\n\n```js\nexport default {\n  resources: {\n    users:  { fields: ['name', 'email', 'role'],           uniqueBy: 'email' },\n    pages:  { fields: ['title', 'slug', 'published'],      uniqueBy: 'slug'  },\n    groups: { fields: ['name', 'slug', 'description'],     uniqueBy: 'slug'  },\n  }\n}\n```\n\nThat's it. Open `/admin/users` — the Import/Export toolbar appears above the table.\n\n---\n\n## How it works\n\n```\n/admin/users\n  ┌─────────────────────────────────────────────────────┐\n  │ users              ↓ Export   ↑ Import   History ↗  │  ← auto-injected toolbar\n  └─────────────────────────────────────────────────────┘\n  ┌──────────────────────────────────────────────────────┐\n  │ Name        Email              Role      Joined      │\n  │ ...         ...                ...       ...         │  ← your existing table\n  └──────────────────────────────────────────────────────┘\n```\n\n### Import wizard\n\n```\nStep 1 Upload    →    Step 2 Preview           →    Step 3 Confirm\n────────────────      ─────────────────────────     ────────────────\nDrop file here        ✓ 138 valid · ✗ 4 errors      Import 138 records\nCSV / JSON / XLSX     [table of first 20 rows]       Cancel\n                      [error rows highlighted red]\n```\n\n### Resource auto-detection\n\nThe toolbar infers the resource from the URL path:\n\n| URL | Resource |\n|-----|---------|\n| `/admin/users` | `users` |\n| `/admin/my-orders` | `my-orders` |\n| `/admin/products` | `products` |\n\nTo override (e.g. on a page with a custom URL), add a `data-ie-resource` attribute anywhere on the page:\n\n```arc\n@raw '<div data-ie-resource=\"products\" data-ie-fields=\"name,sku,price\"></div>'\n```\n\nOr use the optional widget:\n\n```arc\nimport ImportExportBar from \"@arc-language/arc-import-export/src/widgets/ImportExportBar.arc\"\n\nImportExportBar resource=\"products\" fields=\"name,sku,price\" uniqueBy=\"sku\"\n```\n\n---\n\n## Config reference\n\n```js\n// arc-import-export.config.js\nexport default {\n  resources: {\n    [resourceName]: {\n      fields:   string[],  // fields allowed in import (required for import to be enabled)\n      uniqueBy: string,    // optional: upsert key — update if exists, create if not\n    }\n  }\n}\n```\n\n| Option | Type | Required | Description |\n|--------|------|----------|-------------|\n| `fields` | `string[]` | Yes (for import) | Column names that can be imported. Export uses all columns by default. |\n| `uniqueBy` | `string` | No | Field used for upsert on import. If omitted, always creates new records. |\n\nIf a resource is not in the config, **Export still works** (shows all columns) but the Import button is hidden.\n\n---\n\n## API routes\n\nAll routes are mounted automatically when you add the server route to `arc.config.json`.\n\n| Method | Path | Auth | Description |\n|--------|------|------|-------------|\n| `GET` | `/arc-ie/bar.js` | Public | The auto-detect script (~3 KB gzip) |\n| `GET` | `/admin/api/ie/config` | editor+ | Field config for a resource |\n| `POST` | `/admin/api/ie/preview` | editor+ | Parse file, return preview (no DB write) |\n| `POST` | `/admin/api/ie/commit` | editor+ | Commit import to database |\n| `GET` | `/admin/api/ie/export` | editor+ | Stream export file download |\n| `GET` | `/admin/api/ie/logs` | editor+ | List import/export history |\n| `GET` | `/admin/api/ie/logs/:id` | editor+ | Single log detail with errors |\n\n---\n\n## Supported formats\n\n| Format | Import | Export | Notes |\n|--------|--------|--------|-------|\n| CSV | ✓ | ✓ | RFC 4180, handles quoted fields and escaped commas |\n| JSON | ✓ | ✓ | Array of objects; `rows`/`data` wrapper accepted on import |\n| XLSX | ✓ | ✓ | SheetJS (lazy-loaded — zero cost if unused) |\n\n---\n\n## History page\n\nEvery import and export is logged at `/admin/import-export`:\n\n- Filter by action (import / export), status (success / partial / failed), or resource name\n- Click any row to see full details including per-row error messages\n- Counts: total rows, imported, skipped, errors\n\n---\n\n## Performance\n\n| Operation | Complexity | Notes |\n|-----------|------------|-------|\n| Preview parse | O(n) time, O(20) space | Only first 20 rows buffered for preview |\n| Import commit | O(n) time, O(500) space | 500-row batch loop |\n| Export (CSV/JSON) | O(n) time, O(1) space | Streaming response |\n| Export (XLSX) | O(n) time, O(n) space | SheetJS buffer — unavoidable |\n| Config fetch | O(1) | Cached 60 s per browser tab |\n\n---\n\n## Contributing\n\nContributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n```bash\n# Clone\ngit clone https://github.com/arc-language/arc-import-export.git\ncd arc-import-export\n\n# Install\nbun install\n\n# Run against an arc-cms project (set ARC_PROJECT_DIR)\nARC_PROJECT_DIR=../my-arc-project bun run dev\n```\n\n---\n\n## License\n\n[MIT](LICENSE) © KCuppens\n","readmeFilename":"README.md","_rev":"1-f33ec20c4539cf030fa2a25d21e4e25f"}