Skip to content

IIdGenerator

Every plugin instance, every media item, and every internal resource the player creates needs a unique identifier. The core calls idGenerator.next() to get one, and by default that means crypto.randomUUID().

This is almost entirely invisible to you during normal use. The one time you care is in tests: random UUIDs make snapshot assertions and deterministic test output painful. Swapping in a sequential counter makes generated IDs predictable and assertion-friendly.

There is no setup() key for this adapter. It is a construction-time concern, not a runtime configuration.

TypeScript
import { defaultIdGenerator } from '@nomercy-entertainment/nomercy-player-core/adapters/id-generator';
import type { IIdGenerator } from '@nomercy-entertainment/nomercy-player-core/adapters/id-generator';

Built-in adapter

defaultIdGenerator

A plain object that delegates to crypto.randomUUID(). In environments where crypto.randomUUID is absent (some older workers, non-secure contexts), it falls back to a Date.now().toString(36) + Math.random() suffix, which is collision-resistant enough for non-cryptographic IDs.

The adapter is a plain object rather than a class because no state is needed: next() is a pure call with no side effects.

Interface

TypeScript
interface IIdGenerator {
  next(): string;
}

That is the entire contract. One method, one return value, no configuration.

When you’d replace it

In production: never. The default is fine and you should not think about it.

In tests: swap in a counter so your assertions are not fighting random UUIDs.

TypeScript
import type { IIdGenerator } from '@nomercy-entertainment/nomercy-player-core/adapters/id-generator';

function sequentialIdGenerator(prefix = 'id'): IIdGenerator {
  let counter = 0;

  return {
    next(): string {
      counter += 1;
      return `${prefix}-${counter}`;
    },
  };
}

// In your test setup:
const testIdGenerator = sequentialIdGenerator('test');
// Pass to the player or stub at the construction site.

The counter resets when you create a new generator instance, so each test suite starts from id-1 if you create a fresh one in beforeEach.

See also