@vibe-agent-toolkit/resources 0.1.0 → 0.1.1

package/README.md

@@ -8,7 +8,9 @@ Markdown resource parsing, validation, and link integrity checking for AI agent
 - **Validate link integrity** - Check local file links, anchor links, and detect broken references
 - **Track resource collections** - Manage multiple markdown files with automatic ID generation
 - **Resolve cross-references** - Link resources together and track dependencies
-- **Query capabilities** - Find resources by path, ID, or glob patterns
+- **Query capabilities** - Find resources by path, ID, or glob patterns with lazy evaluation
+- **Duplicate detection** - Identify duplicate content using SHA-256 checksums
+- **Collection operations** - Filter, transform, and materialize resource collections efficiently
 - **GitHub Flavored Markdown** - Full support for GFM including tables, task lists, and autolinks
 
 ## Installation
@@ -239,6 +241,226 @@ registry.clear();
 console.log(registry.getAllResources().length); // 0
 ```
 
+##### size(): number
+
+Get the number of resources in the registry.
+
+```typescript
+console.log(`Registry has ${registry.size()} resources`);
+```
+
+##### isEmpty(): boolean
+
+Check if the registry is empty.
+
+```typescript
+if (registry.isEmpty()) {
+  console.log('No resources yet');
+}
+```
+
+##### getDuplicates(): ResourceMetadata[][]
+
+Get groups of duplicate resources based on content checksum.
+
+Returns an array where each element is an array of resources that have identical content. Only groups with 2+ resources are included.
+
+```typescript
+const duplicates = registry.getDuplicates();
+for (const group of duplicates) {
+  console.log(`Found ${group.length} duplicates:`);
+  for (const resource of group) {
+    console.log(`  - ${resource.filePath}`);
+  }
+}
+```
+
+##### getUniqueByChecksum(): ResourceMetadata[]
+
+Get one representative resource for each unique checksum.
+
+When multiple resources have identical content, only the first one encountered is included.
+
+```typescript
+const unique = registry.getUniqueByChecksum();
+console.log(`${unique.length} unique resources by content`);
+```
+
+##### getResourcesByName(name: string): ResourceMetadata[]
+
+Get resources by filename (basename).
+
+Returns all resources with the given filename, regardless of directory. Useful for finding duplicate filenames across the project.
+
+```typescript
+const readmeFiles = registry.getResourcesByName('README.md');
+console.log(`Found ${readmeFiles.length} README.md files`);
+```
+
+##### getResourcesByChecksum(checksum: SHA256): ResourceMetadata[]
+
+Get resources by SHA-256 checksum.
+
+Returns all resources with the given content checksum (i.e., identical content).
+
+```typescript
+const resource = registry.getResourceById('readme');
+if (resource) {
+  const sameContent = registry.getResourcesByChecksum(resource.checksum);
+  console.log(`Found ${sameContent.length} files with identical content`);
+}
+```
+
+### ResourceQuery
+
+Lazy query builder for filtering and transforming resource collections.
+
+Operations are stored and only executed when `execute()` or `toCollection()` is called, allowing for efficient chaining and optimization.
+
+#### Creating Queries
+
+```typescript
+import { ResourceQuery } from '@vibe-agent-toolkit/resources';
+
+const query = ResourceQuery.from(registry.getAllResources());
+```
+
+#### Methods
+
+##### filter(predicate: (resource: ResourceMetadata) => boolean): this
+
+Filter resources by a predicate function.
+
+```typescript
+const query = ResourceQuery.from(resources)
+  .filter(r => r.links.length > 0)
+  .filter(r => r.sizeBytes < 10000);
+```
+
+##### map(transformer: (resource: ResourceMetadata) => ResourceMetadata): this
+
+Transform resources with a mapping function.
+
+```typescript
+const query = ResourceQuery.from(resources)
+  .map(r => ({ ...r, id: r.id.toUpperCase() }));
+```
+
+##### matchesPattern(pattern: string): this
+
+Filter resources by glob pattern matching their file paths.
+
+```typescript
+const query = ResourceQuery.from(resources)
+  .matchesPattern('docs/**/*.md')
+  .matchesPattern('*.ts');
+```
+
+##### execute(): ResourceMetadata[]
+
+Execute the query and return the results as an array.
+
+```typescript
+const results = query.execute();
+console.log(`Found ${results.length} resources`);
+```
+
+##### toCollection(): ResourceCollection
+
+Execute the query and return a ResourceCollection.
+
+```typescript
+const collection = query.toCollection();
+const duplicates = collection.getDuplicates();
+```
+
+#### Example Workflows
+
+**Find all docs with links:**
+
+```typescript
+const docsWithLinks = ResourceQuery.from(registry.getAllResources())
+  .matchesPattern('docs/**/*.md')
+  .filter(r => r.links.length > 0)
+  .execute();
+```
+
+**Get unique API docs:**
+
+```typescript
+const uniqueApiDocs = ResourceQuery.from(registry.getAllResources())
+  .matchesPattern('**/api/**')
+  .toCollection()
+  .getUniqueByChecksum();
+```
+
+### ResourceCollection
+
+Immutable collection of resources with lazy duplicate detection.
+
+ResourceCollection wraps an array of resources and provides efficient duplicate detection. Duplicate detection is performed lazily - checksum indexes are only built when `getDuplicates()` or `getUniqueByChecksum()` is first called.
+
+#### Creating Collections
+
+```typescript
+import { ResourceCollection } from '@vibe-agent-toolkit/resources';
+
+const collection = new ResourceCollection([resource1, resource2, resource3]);
+
+// Or from a query
+const collection = ResourceQuery.from(registry.getAllResources())
+  .filter(r => r.sizeBytes > 1000)
+  .toCollection();
+```
+
+#### Methods
+
+##### size(): number
+
+Get the number of resources in the collection.
+
+```typescript
+console.log(`Collection has ${collection.size()} resources`);
+```
+
+##### isEmpty(): boolean
+
+Check if the collection is empty.
+
+```typescript
+if (collection.isEmpty()) {
+  console.log('Empty collection');
+}
+```
+
+##### getAllResources(): ResourceMetadata[]
+
+Get all resources in the collection.
+
+```typescript
+const all = collection.getAllResources();
+```
+
+##### getDuplicates(): ResourceMetadata[][]
+
+Get groups of duplicate resources based on checksum.
+
+```typescript
+const duplicates = collection.getDuplicates();
+for (const group of duplicates) {
+  console.log(`${group.length} files with identical content`);
+}
+```
+
+##### getUniqueByChecksum(): ResourceMetadata[]
+
+Get one representative resource for each unique checksum.
+
+```typescript
+const unique = collection.getUniqueByChecksum();
+console.log(`${unique.length} unique resources`);
+```
+
 ## Type Definitions
 
 ### ResourceMetadata

package/dist/checksum.d.ts

@@ -0,0 +1,9 @@
+import type { SHA256 } from './schemas/checksum.js';
+/**
+ * Calculate SHA-256 checksum of a file
+ * @param filePath Absolute path to file
+ * @returns SHA-256 checksum as lowercase hex string
+ * @throws Error if file cannot be read
+ */
+export declare function calculateChecksum(filePath: string): Promise<SHA256>;
+//# sourceMappingURL=checksum.d.ts.map

package/dist/checksum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.d.ts","sourceRoot":"","sources":["../src/checksum.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGpD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKzE"}

package/dist/checksum.js

@@ -0,0 +1,16 @@
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { SHA256Schema } from './schemas/checksum.js';
+/**
+ * Calculate SHA-256 checksum of a file
+ * @param filePath Absolute path to file
+ * @returns SHA-256 checksum as lowercase hex string
+ * @throws Error if file cannot be read
+ */
+export async function calculateChecksum(filePath) {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    const content = await fs.readFile(filePath, 'utf-8');
+    const hash = createHash('sha256').update(content, 'utf-8').digest('hex');
+    return SHA256Schema.parse(hash);
+}
+//# sourceMappingURL=checksum.js.map

package/dist/checksum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.js","sourceRoot":"","sources":["../src/checksum.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AAGzC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,QAAgB;IACtD,mEAAmE;IACnE,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACzE,OAAO,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}

package/dist/index.d.ts

@@ -26,6 +26,9 @@
  * ```
  */
 export { ResourceRegistry, type CrawlOptions, type ResourceRegistryOptions, type RegistryStats, } from './resource-registry.js';
+export { ResourceQuery } from './resource-query.js';
+export { ResourceCollection } from './resource-collection.js';
+export type { ResourceCollectionInterface } from './resource-collection-interface.js';
 export type { LinkType, HeadingNode, ResourceLink, ResourceMetadata, ValidationSeverity, ValidationIssue, ValidationResult, } from './types.js';
 export { LinkTypeSchema, HeadingNodeSchema, ResourceLinkSchema, ResourceMetadataSchema, } from './schemas/resource-metadata.js';
 export { ValidationSeveritySchema, ValidationIssueSchema, ValidationResultSchema, } from './schemas/validation-result.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EACL,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAC5B,KAAK,aAAa,GACnB,MAAM,wBAAwB,CAAC;AAGhC,YAAY,EACV,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EACL,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAC5B,KAAK,aAAa,GACnB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAG9D,YAAY,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AAGtF,YAAY,EACV,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -27,6 +27,10 @@
  */
 // Export main ResourceRegistry class
 export { ResourceRegistry, } from './resource-registry.js';
+// Export ResourceQuery for lazy evaluation and filtering
+export { ResourceQuery } from './resource-query.js';
+// Export ResourceCollection for immutable collections with lazy duplicate detection
+export { ResourceCollection } from './resource-collection.js';
 // Export schemas for external use (e.g., JSON Schema generation, runtime validation)
 export { LinkTypeSchema, HeadingNodeSchema, ResourceLinkSchema, ResourceMetadataSchema, } from './schemas/resource-metadata.js';
 export { ValidationSeveritySchema, ValidationIssueSchema, ValidationResultSchema, } from './schemas/validation-result.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qCAAqC;AACrC,OAAO,EACL,gBAAgB,GAIjB,MAAM,wBAAwB,CAAC;AAahC,qFAAqF;AACrF,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAExC,iDAAiD;AACjD,OAAO,EAAE,aAAa,EAAoB,MAAM,kBAAkB,CAAC;AAEnE,kEAAkE;AAClE,0EAA0E"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qCAAqC;AACrC,OAAO,EACL,gBAAgB,GAIjB,MAAM,wBAAwB,CAAC;AAEhC,yDAAyD;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,oFAAoF;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAgB9D,qFAAqF;AACrF,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAExC,iDAAiD;AACjD,OAAO,EAAE,aAAa,EAAoB,MAAM,kBAAkB,CAAC;AAEnE,kEAAkE;AAClE,0EAA0E"}

package/dist/resource-collection-interface.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Interface for resource collections that support duplicate detection and filtering.
+ *
+ * This interface is implemented by ResourceRegistry and ResourceCollection
+ * to provide a consistent API for working with collections of resources.
+ *
+ * @example
+ * ```typescript
+ * const collection: ResourceCollectionInterface = new ResourceRegistry();
+ * console.log(collection.size());
+ * console.log(collection.isEmpty());
+ * const duplicates = collection.getDuplicates();
+ * ```
+ */
+import type { ResourceMetadata } from './schemas/resource-metadata.js';
+/**
+ * Interface for collections of resources with duplicate detection.
+ */
+export interface ResourceCollectionInterface {
+    /**
+     * Get the number of resources in the collection.
+     *
+     * @returns Number of resources
+     */
+    size(): number;
+    /**
+     * Check if the collection is empty.
+     *
+     * @returns True if the collection has no resources
+     */
+    isEmpty(): boolean;
+    /**
+     * Get all resources in the collection.
+     *
+     * @returns Array of all resources
+     */
+    getAllResources(): ResourceMetadata[];
+    /**
+     * Get groups of duplicate resources based on checksum.
+     *
+     * Returns an array where each element is an array of resources
+     * that have the same checksum (i.e., identical content).
+     * Only groups with 2+ resources are included.
+     *
+     * @returns Array of duplicate groups
+     *
+     * @example
+     * ```typescript
+     * const duplicates = collection.getDuplicates();
+     * // [[resource1, resource2], [resource3, resource4, resource5]]
+     * ```
+     */
+    getDuplicates(): ResourceMetadata[][];
+    /**
+     * Get one representative resource for each unique checksum.
+     *
+     * When multiple resources have the same checksum, only the first
+     * one encountered is included in the result.
+     *
+     * @returns Array of unique resources (one per checksum)
+     *
+     * @example
+     * ```typescript
+     * const unique = collection.getUniqueByChecksum();
+     * // All resources have different checksums
+     * ```
+     */
+    getUniqueByChecksum(): ResourceMetadata[];
+}
+//# sourceMappingURL=resource-collection-interface.d.ts.map

package/dist/resource-collection-interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-collection-interface.d.ts","sourceRoot":"","sources":["../src/resource-collection-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,IAAI,IAAI,MAAM,CAAC;IAEf;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC;IAEnB;;;;OAIG;IACH,eAAe,IAAI,gBAAgB,EAAE,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,aAAa,IAAI,gBAAgB,EAAE,EAAE,CAAC;IAEtC;;;;;;;;;;;;;OAaG;IACH,mBAAmB,IAAI,gBAAgB,EAAE,CAAC;CAC3C"}

package/dist/resource-collection-interface.js

@@ -0,0 +1,16 @@
+/**
+ * Interface for resource collections that support duplicate detection and filtering.
+ *
+ * This interface is implemented by ResourceRegistry and ResourceCollection
+ * to provide a consistent API for working with collections of resources.
+ *
+ * @example
+ * ```typescript
+ * const collection: ResourceCollectionInterface = new ResourceRegistry();
+ * console.log(collection.size());
+ * console.log(collection.isEmpty());
+ * const duplicates = collection.getDuplicates();
+ * ```
+ */
+export {};
+//# sourceMappingURL=resource-collection-interface.js.map

package/dist/resource-collection-interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-collection-interface.js","sourceRoot":"","sources":["../src/resource-collection-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/resource-collection.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Immutable collection of resources with lazy duplicate detection.
+ *
+ * ResourceCollection wraps an array of resources and provides efficient
+ * duplicate detection and filtering operations. Duplicate detection is
+ * performed lazily - the collection builds checksum indexes only when
+ * getDuplicates() or getUniqueByChecksum() is first called.
+ *
+ * @example
+ * ```typescript
+ * const collection = new ResourceCollection([resource1, resource2, resource3]);
+ *
+ * console.log(collection.size());
+ * const duplicates = collection.getDuplicates();
+ * const unique = collection.getUniqueByChecksum();
+ * ```
+ */
+import type { ResourceCollectionInterface } from './resource-collection-interface.js';
+import type { ResourceMetadata } from './schemas/resource-metadata.js';
+/**
+ * Immutable collection of resources with lazy duplicate detection.
+ *
+ * This class implements the ResourceCollectionInterface and provides
+ * efficient operations for working with collections of resources.
+ * Duplicate detection is lazy - checksum indexes are only built when needed.
+ */
+export declare class ResourceCollection implements ResourceCollectionInterface {
+    private readonly resources;
+    private checksumIndex;
+    /**
+     * Create a new ResourceCollection from an array of resources.
+     *
+     * @param resources - Array of resources to wrap
+     *
+     * @example
+     * ```typescript
+     * const collection = new ResourceCollection([resource1, resource2]);
+     * ```
+     */
+    constructor(resources: ResourceMetadata[]);
+    /**
+     * Get the number of resources in the collection.
+     *
+     * @returns Number of resources
+     */
+    size(): number;
+    /**
+     * Check if the collection is empty.
+     *
+     * @returns True if the collection has no resources
+     */
+    isEmpty(): boolean;
+    /**
+     * Get all resources in the collection.
+     *
+     * @returns Array of all resources
+     */
+    getAllResources(): ResourceMetadata[];
+    /**
+     * Get groups of duplicate resources based on checksum.
+     *
+     * Lazily builds a checksum index on first call. Returns an array where
+     * each element is an array of resources that have the same checksum
+     * (i.e., identical content). Only groups with 2+ resources are included.
+     *
+     * @returns Array of duplicate groups
+     */
+    getDuplicates(): ResourceMetadata[][];
+    /**
+     * Get one representative resource for each unique checksum.
+     *
+     * Lazily builds a checksum index on first call. When multiple resources
+     * have the same checksum, only the first one encountered is included
+     * in the result.
+     *
+     * @returns Array of unique resources (one per checksum)
+     */
+    getUniqueByChecksum(): ResourceMetadata[];
+    /**
+     * Ensure the checksum index is built.
+     *
+     * Builds the index on first call, subsequent calls do nothing.
+     * This provides lazy evaluation for duplicate detection.
+     */
+    private ensureChecksumIndex;
+}
+//# sourceMappingURL=resource-collection.d.ts.map

package/dist/resource-collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-collection.d.ts","sourceRoot":"","sources":["../src/resource-collection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AAEtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAEvE;;;;;;GAMG;AACH,qBAAa,kBAAmB,YAAW,2BAA2B;IACpE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,aAAa,CAAgD;IAErE;;;;;;;;;OASG;gBACS,SAAS,EAAE,gBAAgB,EAAE;IAIzC;;;;OAIG;IACH,IAAI,IAAI,MAAM;IAId;;;;OAIG;IACH,OAAO,IAAI,OAAO;IAIlB;;;;OAIG;IACH,eAAe,IAAI,gBAAgB,EAAE;IAIrC;;;;;;;;OAQG;IACH,aAAa,IAAI,gBAAgB,EAAE,EAAE;IAcrC;;;;;;;;OAQG;IACH,mBAAmB,IAAI,gBAAgB,EAAE;IAczC;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;CAe5B"}

package/dist/resource-collection.js

@@ -0,0 +1,131 @@
+/**
+ * Immutable collection of resources with lazy duplicate detection.
+ *
+ * ResourceCollection wraps an array of resources and provides efficient
+ * duplicate detection and filtering operations. Duplicate detection is
+ * performed lazily - the collection builds checksum indexes only when
+ * getDuplicates() or getUniqueByChecksum() is first called.
+ *
+ * @example
+ * ```typescript
+ * const collection = new ResourceCollection([resource1, resource2, resource3]);
+ *
+ * console.log(collection.size());
+ * const duplicates = collection.getDuplicates();
+ * const unique = collection.getUniqueByChecksum();
+ * ```
+ */
+/**
+ * Immutable collection of resources with lazy duplicate detection.
+ *
+ * This class implements the ResourceCollectionInterface and provides
+ * efficient operations for working with collections of resources.
+ * Duplicate detection is lazy - checksum indexes are only built when needed.
+ */
+export class ResourceCollection {
+    resources;
+    checksumIndex = null;
+    /**
+     * Create a new ResourceCollection from an array of resources.
+     *
+     * @param resources - Array of resources to wrap
+     *
+     * @example
+     * ```typescript
+     * const collection = new ResourceCollection([resource1, resource2]);
+     * ```
+     */
+    constructor(resources) {
+        this.resources = resources;
+    }
+    /**
+     * Get the number of resources in the collection.
+     *
+     * @returns Number of resources
+     */
+    size() {
+        return this.resources.length;
+    }
+    /**
+     * Check if the collection is empty.
+     *
+     * @returns True if the collection has no resources
+     */
+    isEmpty() {
+        return this.resources.length === 0;
+    }
+    /**
+     * Get all resources in the collection.
+     *
+     * @returns Array of all resources
+     */
+    getAllResources() {
+        return this.resources;
+    }
+    /**
+     * Get groups of duplicate resources based on checksum.
+     *
+     * Lazily builds a checksum index on first call. Returns an array where
+     * each element is an array of resources that have the same checksum
+     * (i.e., identical content). Only groups with 2+ resources are included.
+     *
+     * @returns Array of duplicate groups
+     */
+    getDuplicates() {
+        this.ensureChecksumIndex();
+        if (!this.checksumIndex) {
+            return [];
+        }
+        const duplicateGroups = [];
+        for (const group of this.checksumIndex.values()) {
+            if (group.length >= 2) {
+                duplicateGroups.push(group);
+            }
+        }
+        return duplicateGroups;
+    }
+    /**
+     * Get one representative resource for each unique checksum.
+     *
+     * Lazily builds a checksum index on first call. When multiple resources
+     * have the same checksum, only the first one encountered is included
+     * in the result.
+     *
+     * @returns Array of unique resources (one per checksum)
+     */
+    getUniqueByChecksum() {
+        this.ensureChecksumIndex();
+        if (!this.checksumIndex) {
+            return [];
+        }
+        const unique = [];
+        for (const group of this.checksumIndex.values()) {
+            if (group[0]) {
+                unique.push(group[0]);
+            }
+        }
+        return unique;
+    }
+    /**
+     * Ensure the checksum index is built.
+     *
+     * Builds the index on first call, subsequent calls do nothing.
+     * This provides lazy evaluation for duplicate detection.
+     */
+    ensureChecksumIndex() {
+        if (this.checksumIndex !== null) {
+            return;
+        }
+        this.checksumIndex = new Map();
+        for (const resource of this.resources) {
+            const group = this.checksumIndex.get(resource.checksum);
+            if (group) {
+                group.push(resource);
+            }
+            else {
+                this.checksumIndex.set(resource.checksum, [resource]);
+            }
+        }
+    }
+}
+//# sourceMappingURL=resource-collection.js.map

package/dist/resource-collection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-collection.js","sourceRoot":"","sources":["../src/resource-collection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH;;;;;;GAMG;AACH,MAAM,OAAO,kBAAkB;IACZ,SAAS,CAAqB;IACvC,aAAa,GAA2C,IAAI,CAAC;IAErE;;;;;;;;;OASG;IACH,YAAY,SAA6B;QACvC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,IAAI;QACF,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACH,OAAO;QACL,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACH,eAAe;QACb,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;;;;;;;OAQG;IACH,aAAa;QACX,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,eAAe,GAAyB,EAAE,CAAC;QACjD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC;YAChD,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;gBACtB,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;QACD,OAAO,eAAe,CAAC;IACzB,CAAC;IAED;;;;;;;;OAQG;IACH,mBAAmB;QACjB,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,MAAM,GAAuB,EAAE,CAAC;QACtC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC;YAChD,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;gBACb,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACK,mBAAmB;QACzB,IAAI,IAAI,CAAC,aAAa,KAAK,IAAI,EAAE,CAAC;YAChC,OAAO;QACT,CAAC;QAED,IAAI,CAAC,aAAa,GAAG,IAAI,GAAG,EAAE,CAAC;QAC/B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACxD,IAAI,KAAK,EAAE,CAAC;gBACV,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACvB,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;IACH,CAAC;CACF"}