{"id":35071188,"url":"https://github.com/nikoheikkila/maps","last_synced_at":"2026-04-20T21:32:32.309Z","repository":{"id":319876461,"uuid":"1079893194","full_name":"nikoheikkila/maps","owner":"nikoheikkila","description":"A TypeScript collection of specialized map implementations","archived":false,"fork":false,"pushed_at":"2025-10-20T16:06:34.000Z","size":41,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-20T18:09:13.563Z","etag":null,"topics":["data","javascript","maps","typescript"],"latest_commit_sha":null,"homepage":null,"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/nikoheikkila.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-20T14:47:14.000Z","updated_at":"2025-10-20T16:06:38.000Z","dependencies_parsed_at":"2025-10-20T18:09:21.694Z","dependency_job_id":"40d49fbb-07eb-4073-a2d5-5359fa1d3bb8","html_url":"https://github.com/nikoheikkila/maps","commit_stats":null,"previous_names":["nikoheikkila/maps"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/nikoheikkila/maps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikoheikkila%2Fmaps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikoheikkila%2Fmaps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikoheikkila%2Fmaps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikoheikkila%2Fmaps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nikoheikkila","download_url":"https://codeload.github.com/nikoheikkila/maps/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikoheikkila%2Fmaps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32067370,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T21:26:33.338Z","status":"ssl_error","status_checked_at":"2026-04-20T21:26:22.081Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["data","javascript","maps","typescript"],"created_at":"2025-12-27T11:56:26.889Z","updated_at":"2026-04-20T21:32:32.303Z","avatar_url":"https://github.com/nikoheikkila.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @nikoheikkila/maps\n\n[![CI](https://github.com/nikoheikkila/maps/actions/workflows/ci.yml/badge.svg)](https://github.com/nikoheikkila/maps/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\nA TypeScript collection of specialized map implementations for time-series data and other use cases.\n\n## Features\n\n- **TimeSeriesMap**: A specialized Map extension for time-based data storage and retrieval\n- **Type-safe**: Full TypeScript support with comprehensive type definitions\n- **Lightweight**: Zero dependencies, minimal footprint\n- **Modern**: Built with ES modules and supports both CommonJS and ESM\n- **Well-tested**: Comprehensive test coverage with Bun's test runner\n\n## Installation\n\n### GitHub Packages\n\nThis package is published to GitHub Packages. To install it, you need to configure your `.npmrc` file:\n\n```bash\n# Create or update .npmrc in your project root\necho \"@nikoheikkila:registry=https://npm.pkg.github.com\" \u003e\u003e .npmrc\n```\n\nYou'll also need to authenticate with GitHub Packages using a personal access token:\n\n```bash\n# Set your GitHub personal access token\nexport GITHUB_TOKEN=\"your_personal_access_token_here\"\nnpm config set //npm.pkg.github.com/:_authToken ${GITHUB_TOKEN}\n```\n\nThen install the package:\n\n```bash\n# Using npm\nnpm install @nikoheikkila/maps\n\n# Using yarn\nyarn add @nikoheikkila/maps\n\n# Using bun\nbun add @nikoheikkila/maps\n```\n\n### Authentication Setup\n\nTo use packages from GitHub Packages, you need a GitHub personal access token with `read:packages` permission:\n\n1. Go to GitHub → Settings → Developer settings → Personal access tokens\n2. Create a new token with `read:packages` scope\n3. Configure your environment as shown above\n\n## Usage\n\n### TimeSeriesMap\n\nA specialized Map that extends JavaScript's native Map with time-series specific functionality:\n\n```typescript\nimport { TimeSeriesMap } from '@nikoheikkila/maps';\n\n// Create a new time series map\nconst tsMap = new TimeSeriesMap\u003cstring\u003e();\n\n// Add data (keys are automatically generated using timestamps)\nconst key1 = tsMap.add('first value');\nconst key2 = tsMap.add('second value');\nconst key3 = tsMap.add('third value');\n\n// Retrieve the latest entry\nconst latest = tsMap.latest(); // 'third value'\n\n// Retrieve the earliest entry\nconst earliest = tsMap.earliest(); // 'first value'\n\n// Get all values as an array\nconst allValues = tsMap.all(); // ['first value', 'second value', 'third value']\n\n// Use with custom key generation function\nlet counter = 0;\nconst customTsMap = new TimeSeriesMap\u003cnumber\u003e(() =\u003e ++counter);\n\ncustomTsMap.add(100); // key: 1\ncustomTsMap.add(200); // key: 2\ncustomTsMap.add(300); // key: 3\n```\n\n### Custom Key Functions\n\nBy default, `TimeSeriesMap` uses `Date.now()` for key generation, but you can provide your own:\n\n```typescript\n// Using a custom incrementing counter\nlet id = 0;\nconst counterMap = new TimeSeriesMap\u003cstring\u003e(() =\u003e ++id);\n\n// Using high-resolution time\nconst hrMap = new TimeSeriesMap\u003cstring\u003e(() =\u003e \n  performance.now()\n);\n\n// Using random numbers (not recommended for production)\nconst randomMap = new TimeSeriesMap\u003cstring\u003e(() =\u003e \n  Math.floor(Math.random() * 1000000)\n);\n```\n\n### Error Handling\n\n`TimeSeriesMap` throws errors when trying to access data from an empty map:\n\n```typescript\nconst emptyMap = new TimeSeriesMap\u003cstring\u003e();\n\ntry {\n  const latest = emptyMap.latest();\n} catch (error) {\n  console.error(error.message); // \"map has no records\"\n}\n\ntry {\n  const earliest = emptyMap.earliest();\n} catch (error) {\n  console.error(error.message); // \"map has no records\"\n}\n```\n\n## API Reference\n\n### TimeSeriesMap\u003cT\u003e\n\nExtends `Map\u003cnumber, T\u003e` with additional time-series methods.\n\n#### Constructor\n\n- `new TimeSeriesMap\u003cT\u003e(keyFn?: () =\u003e number)`\n  - `keyFn`: Optional key generation function (defaults to `Date.now`)\n\n#### Methods\n\n- `add(data: T): number` - Adds data to the map and returns the generated key\n- `latest(): T` - Returns the value with the highest key (throws if empty)\n- `earliest(): T` - Returns the value with the lowest key (throws if empty)\n- `all(): T[]` - Returns all values as an array in insertion order\n\n#### Inherited Methods\n\nAll standard `Map` methods are available:\n- `get(key: number): T | undefined`\n- `set(key: number, value: T): this`\n- `has(key: number): boolean`\n- `delete(key: number): boolean`\n- `clear(): void`\n- `size: number`\n- And all other Map methods...\n\n## Development\n\n### Prerequisites\n\n- [Bun](https://bun.com) v1.0.0 or higher\n- Node.js 18+ (for compatibility testing)\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/nikoheikkila/maps.git\ncd maps\n\n# Install dependencies\nbun install\n```\n\n### Available Scripts\n\n```bash\n# Build the package\nbun run build\n\n# Run tests\nbun test\n\n# Run tests with coverage\nbun run test:coverage\n\n# Lint and format code\nbun run lint\nbun run format\n\n# Clean build artifacts\nbun run clean\n```\n\n### Building\n\nThe build process creates multiple output formats:\n\n- `dist/index.js` - CommonJS bundle\n- `dist/index.mjs` - ES module bundle\n- `dist/index.d.ts` - TypeScript definitions\n- Source maps for debugging\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n\n## Author\n\n**Niko Heikkilä** - [nikoheikkila](https://github.com/nikoheikkila)\n\n---\n\n*Built with [Bun](https://bun.com) 🥟*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikoheikkila%2Fmaps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikoheikkila%2Fmaps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikoheikkila%2Fmaps/lists"}