{"id":29966494,"url":"https://github.com/lambdalisue/deno-import-map-importer","last_synced_at":"2025-08-04T03:03:04.362Z","repository":{"id":303672516,"uuid":"1016300909","full_name":"lambdalisue/deno-import-map-importer","owner":"lambdalisue","description":"🦕 A high-performance import map processor that transforms and caches JavaScript/TypeScript modules for Deno.","archived":false,"fork":false,"pushed_at":"2025-08-02T10:56:32.000Z","size":103,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-02T11:39:06.456Z","etag":null,"topics":["deno","import-map"],"latest_commit_sha":null,"homepage":"https://jsr.io/@lambdalisue/import-map-importer","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lambdalisue.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"lambdalisue"}},"created_at":"2025-07-08T19:50:14.000Z","updated_at":"2025-08-02T10:56:16.000Z","dependencies_parsed_at":"2025-08-02T11:09:00.338Z","dependency_job_id":"05e023db-7775-4f1a-b8c8-4e5b2330439d","html_url":"https://github.com/lambdalisue/deno-import-map-importer","commit_stats":null,"previous_names":["lambdalisue/deno-import-map-importer"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/lambdalisue/deno-import-map-importer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdalisue%2Fdeno-import-map-importer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdalisue%2Fdeno-import-map-importer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdalisue%2Fdeno-import-map-importer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdalisue%2Fdeno-import-map-importer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lambdalisue","download_url":"https://codeload.github.com/lambdalisue/deno-import-map-importer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdalisue%2Fdeno-import-map-importer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268643728,"owners_count":24283316,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-04T02:00:09.867Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deno","import-map"],"created_at":"2025-08-04T03:00:59.594Z","updated_at":"2025-08-04T03:03:00.774Z","avatar_url":"https://github.com/lambdalisue.png","language":"TypeScript","funding_links":["https://github.com/sponsors/lambdalisue"],"categories":[],"sub_categories":[],"readme":"# import-map-importer\n\n[![JSR](https://jsr.io/badges/@lambdalisue/import-map-importer)](https://jsr.io/@lambdalisue/import-map-importer)\n[![Test workflow](https://github.com/lambdalisue/deno-import-map-importer/actions/workflows/test.yml/badge.svg)](https://github.com/lambdalisue/deno-import-map-importer/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/lambdalisue/deno-import-map-importer/graph/badge.svg?token=bBTnWn6fJI)](https://codecov.io/gh/lambdalisue/deno-import-map-importer)\n\nA high-performance import map processor for Deno that dynamically transforms and\ncaches JavaScript/TypeScript modules. This tool enables you to use import maps\nin environments where they're not natively supported, with intelligent caching\nfor optimal performance.\n\n## Features\n\n- 🚀 **High Performance** - Multi-level caching (memory + disk) with parallel\n  dependency processing\n- 🔄 **Import Map Support** - Full support for imports and scopes as defined in\n  the [Import Maps specification](https://github.com/WICG/import-maps)\n- 📦 **Smart Caching** - Content-based cache invalidation ensures updates are\n  reflected immediately\n- 🔍 **Comprehensive Import Detection** - Catches all import/export patterns\n  including those missed by standard parsers\n- 🛡️ **Type Safety** - Full TypeScript support with exported types\n- 🎯 **Zero Dependencies** - Only uses Deno standard library and essential tools\n\n## Installation\n\n```bash\ndeno add @lambdalisue/import-map-importer\n```\n\n## Quick Start\n\n```typescript ignore\nimport { ImportMapImporter } from \"@lambdalisue/import-map-importer\";\n\n// Define your import map\nconst importMap = {\n  imports: {\n    // Map package names to URLs\n    \"lodash\": \"https://cdn.skypack.dev/lodash\",\n    \"react\": \"https://esm.sh/react@18\",\n\n    // Map path prefixes\n    \"@utils/\": \"./src/utils/\",\n    \"@components/\": \"./src/components/\",\n  },\n};\n\n// Create an importer instance\nconst importer = new ImportMapImporter(importMap);\n\n// Import modules with automatic transformation\n// This is an example - replace with your actual module path\nconst myModule = await importer.import\u003c{ greet: (name: string) =\u003e void }\u003e(\n  \"./src/main.ts\",\n);\nmyModule.greet(\"World\"); // Uses transformed imports!\n```\n\n## Advanced Usage\n\n### Custom Cache Directory\n\n```typescript\nimport { ImportMapImporter } from \"@lambdalisue/import-map-importer\";\n\nconst importMap = {\n  imports: {\n    \"lodash\": \"https://cdn.skypack.dev/lodash\",\n  },\n};\n\nconst importer = new ImportMapImporter(importMap, {\n  // Use a custom cache directory\n  cacheDir: \"./.cache/imports\",\n});\n```\n\n### Scoped Imports\n\n```typescript\nconst importMap = {\n  imports: {\n    \"lodash\": \"https://cdn.skypack.dev/lodash@4.17.21\",\n  },\n  scopes: {\n    \"/legacy/\": {\n      // Use older version in legacy code\n      \"lodash\": \"https://cdn.skypack.dev/lodash@3.10.1\",\n    },\n  },\n};\n```\n\n### Clear Deno Cache\n\nFor modules that have their own `deno.json` configurations:\n\n```typescript\nimport { ImportMapImporter } from \"@lambdalisue/import-map-importer\";\n\nconst importMap = {\n  imports: {\n    \"lodash\": \"https://cdn.skypack.dev/lodash\",\n  },\n};\n\nconst importer = new ImportMapImporter(importMap, {\n  // Clear Deno's module cache before importing\n  clearDenoCache: true,\n});\n```\n\n### Type-Safe Imports\n\n```typescript\nimport { ImportMapImporter } from \"@lambdalisue/import-map-importer\";\n\n// Define your module interface\ninterface MyUtils {\n  formatDate: (date: Date) =\u003e string;\n  parseJSON: \u003cT\u003e(json: string) =\u003e T;\n}\n\nconst importMap = {\n  imports: {\n    \"@utils/\": \"./src/utils/\",\n  },\n};\n\nconst importer = new ImportMapImporter(importMap);\n\n// Import with type safety\n// This is an example - replace with your actual module path\n// const utils = await importer.import\u003cMyUtils\u003e(\"@utils/helpers.ts\");\n// const formatted = utils.formatDate(new Date()); // Fully typed!\n```\n\n## How It Works\n\n1. **Parse** - When you import a module, the importer parses its source code to\n   find all import statements\n2. **Transform** - Import specifiers are transformed according to your import\n   map rules\n3. **Cache** - Transformed modules are cached both in memory and on disk for\n   fast subsequent loads\n4. **Recurse** - Dependencies are processed recursively and in parallel for\n   optimal performance\n\n### Caching Strategy\n\nThe caching system uses a content-based approach:\n\n- **Cache Key**: SHA-256 hash of (module URL + source code + import map)\n- **Cache Location**: Configurable directory with hierarchical structure\n- **Cache Invalidation**: Automatic when source code or import map changes\n\n## API Reference\n\n### `ImportMapImporter`\n\nThe main class for import map processing.\n\n```typescript\ninterface ImportMap {\n  imports: Record\u003cstring, string\u003e;\n  scopes?: Record\u003cstring, Record\u003cstring, string\u003e\u003e;\n}\n\ninterface ImportMapImporterOptions {\n  cacheDir?: string;\n  clearDenoCache?: boolean;\n}\n\n// Class signature (implementation details omitted)\n// class ImportMapImporter {\n//   constructor(\n//     importMap: ImportMap,\n//     options?: ImportMapImporterOptions,\n//   );\n//\n//   import\u003cT\u003e(specifier: string): Promise\u003cT\u003e;\n// }\n```\n\n### `ImportMap`\n\nThe import map configuration type.\n\n```typescript\ninterface ImportMap {\n  imports: Record\u003cstring, string\u003e;\n  scopes?: Record\u003cstring, Record\u003cstring, string\u003e\u003e;\n}\n```\n\n### `ImportMapImporterOptions`\n\nConfiguration options for the importer.\n\n```typescript\ninterface ImportMapImporterOptions {\n  // Custom cache directory (absolute or relative path)\n  cacheDir?: string;\n\n  // Clear Deno's module cache before importing\n  clearDenoCache?: boolean;\n}\n```\n\n### Type Guards\n\nThe module also exports type guards for runtime validation:\n\n```typescript\nimport {\n  ImportMapImporter,\n  isImportMap,\n  isImports,\n  isScopes,\n} from \"@lambdalisue/import-map-importer\";\n\n// Validate import map structure\nconst data: unknown = {\n  imports: { \"lodash\": \"https://cdn.skypack.dev/lodash\" },\n};\nif (isImportMap(data)) {\n  const importer = new ImportMapImporter(data);\n}\n```\n\n### `loadImportMap`\n\nA utility function to load import maps from JSON files with automatic path\nresolution.\n\n```typescript ignore\nimport {\n  ImportMapImporter,\n  loadImportMap,\n} from \"@lambdalisue/import-map-importer\";\n\n// Load from a relative path\nconst importMap = await loadImportMap(\"./config/import_map.json\");\n\n// Load from an absolute path\nconst importMap2 = await loadImportMap(\"/path/to/import_map.json\");\n\n// Use with ImportMapImporter\nconst importer = new ImportMapImporter(importMap);\n```\n\nThis function automatically resolves relative paths in your import map file:\n\n- **Relative paths** (starting with `./` or `../`) are resolved relative to the\n  import map file's location\n- **Absolute paths** are converted to file URLs\n- **URLs** (http://, https://, file://) are preserved as-is\n\nExample: If your `config/import_map.json` contains:\n\n```json\n{\n  \"imports\": {\n    \"@utils/\": \"./src/utils/\",\n    \"lodash\": \"https://cdn.skypack.dev/lodash\"\n  }\n}\n```\n\nThe resolved result will have the relative path converted to an absolute file\nURL:\n\n```json\n{\n  \"imports\": {\n    \"@utils/\": \"file:///absolute/path/to/config/src/utils/\",\n    \"lodash\": \"https://cdn.skypack.dev/lodash\"\n  }\n}\n```\n\n## Performance Tips\n\n1. **Reuse Importer Instances** - Create one importer and reuse it for multiple\n   imports\n2. **Use Absolute URLs** - Prefer absolute URLs in import maps for better\n   caching\n3. **Batch Imports** - Import multiple modules in parallel when possible\n\n```typescript ignore\nimport { ImportMapImporter } from \"@lambdalisue/import-map-importer\";\n\nconst importMap = {\n  imports: {\n    \"lodash\": \"https://cdn.skypack.dev/lodash\",\n  },\n};\n\nconst importer = new ImportMapImporter(importMap);\n\n// Good - parallel imports\nconst [moduleA, moduleB] = await Promise.all([\n  importer.import(\"./a.ts\"),\n  importer.import(\"./b.ts\"),\n]);\n\n// Less optimal - sequential imports\nconst moduleA2 = await importer.import(\"./a.ts\");\nconst moduleB2 = await importer.import(\"./b.ts\");\n```\n\n## Limitations\n\n- Only processes static imports (not dynamic `import()` expressions in the\n  initial transformation)\n- Remote modules must be accessible via fetch\n- Import maps must be known at initialization time\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major\nchanges, please open an issue first to discuss what you would like to change.\n\n### Development\n\n```bash\n# Run tests\ndeno test -A\n\n# Run linter\ndeno lint\n\n# Run formatter\ndeno fmt\n\n# Run type checking\ndeno check **/*.ts\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE)\nfile for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambdalisue%2Fdeno-import-map-importer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flambdalisue%2Fdeno-import-map-importer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambdalisue%2Fdeno-import-map-importer/lists"}