@byearlybird/starling 0.10.0 → 0.11.0

package/dist/index-D7bXWDg6.d.ts

@@ -0,0 +1,270 @@
+//#region src/core/clock/clock.d.ts
+/**
+ * A Hybrid Logical Clock that generates monotonically increasing eventstamps.
+ * Combines wall-clock time with a counter for handling clock stalls and a
+ * random nonce for tie-breaking.
+ *
+ * The clock automatically increments the counter when the wall clock doesn't
+ * advance, ensuring eventstamps are always unique and monotonic.
+ *
+ * @example
+ * ```typescript
+ * const clock = createClock();
+ * const stamp1 = clock.now();
+ * const stamp2 = clock.now();
+ * ```
+ */
+type Clock = ReturnType<typeof createClock>;
+/**
+ * Create a new Clock instance.
+ * @param initialState - Optional initial state for the clock
+ */
+declare function createClock(initialState?: {
+  counter: number;
+  lastMs: number;
+  lastNonce: string;
+}): {
+  now: () => string;
+  latest: () => string;
+  forward: (eventstamp: string) => void;
+};
+/**
+ * Create a Clock from an eventstamp string.
+ * @param eventstamp - Eventstamp string to decode and initialize clock from
+ * @throws Error if eventstamp is invalid
+ */
+declare function createClockFromEventstamp(eventstamp: string): Clock;
+//#endregion
+//#region src/core/clock/errors.d.ts
+declare class InvalidEventstampError extends Error {
+  constructor(eventstamp: string);
+}
+//#endregion
+//#region src/core/clock/eventstamp.d.ts
+/**
+ * Validates whether a string is a properly formatted eventstamp.
+ * Expected format: YYYY-MM-DDTHH:mm:ss.SSSZ|HHHH+|HHHH
+ * where HHHH+ represents 4 or more hex characters for the counter,
+ * and HHHH represents exactly 4 hex characters for the nonce.
+ */
+declare function isValidEventstamp(stamp: string): boolean;
+declare const MIN_EVENTSTAMP: string;
+/**
+ * Find the maximum eventstamp from an array of eventstamps.
+ * Returns MIN_EVENTSTAMP if the array is empty.
+ * @param eventstamps - Array of eventstamp strings
+ * @returns The maximum eventstamp
+ */
+declare function maxEventstamp(eventstamps: string[]): string;
+//#endregion
+//#region src/core/document/resource.d.ts
+/**
+ * Resource object structure representing a single stored entity.
+ * Resources are the primary unit of storage and synchronization in Starling.
+ *
+ * Each resource has a type, unique identifier, attributes containing the data,
+ * and metadata for tracking deletion state and eventstamps.
+ */
+type ResourceObject<T extends AnyObject> = {
+  /** Resource type identifier */
+  type: string;
+  /** Unique identifier for this resource */
+  id: string;
+  /** The resource's data as a nested object structure */
+  attributes: T;
+  /** Metadata for tracking deletion and eventstamps */
+  meta: {
+    /** Flat map of dot-separated paths to eventstamps (e.g., "user.address.street": "2025-11-18...") */
+    eventstamps: Record<string, string>;
+    /** The greatest eventstamp in this resource (including deletedAt if applicable) */
+    latest: string;
+    /** Eventstamp when this resource was soft-deleted, or null if not deleted */
+    deletedAt: string | null;
+  };
+};
+declare function makeResource<T extends AnyObject>(type: string, id: string, obj: T, eventstamp: string, deletedAt?: string | null): ResourceObject<T>;
+declare function mergeResources<T extends AnyObject>(into: ResourceObject<T>, from: ResourceObject<T>): ResourceObject<T>;
+declare function deleteResource<T extends AnyObject>(resource: ResourceObject<T>, eventstamp: string): ResourceObject<T>;
+//#endregion
+//#region src/core/document/document.d.ts
+/**
+ * Base constraint for all document data in Starling.
+ * Documents must be plain JavaScript objects with string keys.
+ */
+type AnyObject = Record<string, unknown>;
+/**
+ * A JSON:API document represents the complete state of a store:
+ * - API version information
+ * - Metadata including the highest eventstamp observed across all operations
+ * - A set of resource objects (including soft-deleted ones)
+ *
+ * Documents are the unit of synchronization between store replicas.
+ */
+type JsonDocument<T extends AnyObject> = {
+  /** API version information */
+  jsonapi: {
+    version: "1.1";
+  };
+  /** Document-level metadata */
+  meta: {
+    /** Latest eventstamp observed by this document for clock synchronization */
+    latest: string;
+  };
+  /** Array of resource objects with eventstamps and metadata */
+  data: ResourceObject<T>[];
+};
+/**
+ * Change tracking information returned by mergeDocuments.
+ * Categorizes resources by mutation type for hook notifications.
+ */
+type DocumentChanges<T extends AnyObject> = {
+  /** Resources that were newly added (didn't exist before or were previously deleted) */
+  added: Map<string, ResourceObject<T>>;
+  /** Resources that were modified (existed before and changed) */
+  updated: Map<string, ResourceObject<T>>;
+  /** Resources that were deleted (newly marked with deletedAt) */
+  deleted: Set<string>;
+};
+/**
+ * Result of merging two JSON:API documents.
+ */
+type MergeDocumentsResult<T extends AnyObject> = {
+  /** The merged document with updated resources and forwarded clock */
+  document: JsonDocument<T>;
+  /** Change tracking for plugin hook notifications */
+  changes: DocumentChanges<T>;
+};
+/**
+ * Merges two JSON:API documents using field-level Last-Write-Wins semantics.
+ *
+ * The merge operation:
+ * 1. Forwards the clock to the newest eventstamp from either document
+ * 2. Merges each resource pair using field-level LWW (via mergeResources)
+ * 3. Tracks what changed for hook notifications (added/updated/deleted)
+ *
+ * Deletion is final: once a resource is deleted, updates to it are merged into
+ * the resource's attributes but don't restore visibility. Only new resources or
+ * transitions into the deleted state are tracked.
+ *
+ * @param into - The base document to merge into
+ * @param from - The source document to merge from
+ * @returns Merged document and categorized changes
+ *
+ * @example
+ * ```typescript
+ * const into = {
+ *   jsonapi: { version: "1.1" },
+ *   meta: { latest: "2025-01-01T00:00:00.000Z|0001|a1b2" },
+ *   data: [{ type: "items", id: "doc1", attributes: {...}, meta: { deletedAt: null, latest: "..." } }]
+ * };
+ *
+ * const from = {
+ *   jsonapi: { version: "1.1" },
+ *   meta: { latest: "2025-01-01T00:05:00.000Z|0001|c3d4" },
+ *   data: [
+ *     { type: "items", id: "doc1", attributes: {...}, meta: { deletedAt: null, latest: "..." } }, // updated
+ *     { type: "items", id: "doc2", attributes: {...}, meta: { deletedAt: null, latest: "..." } }  // new
+ *   ]
+ * };
+ *
+ * const result = mergeDocuments(into, from);
+ * // result.document.meta.latest === "2025-01-01T00:05:00.000Z|0001|c3d4"
+ * // result.changes.added has "doc2"
+ * // result.changes.updated has "doc1"
+ * ```
+ */
+declare function mergeDocuments<T extends AnyObject>(into: JsonDocument<T>, from: JsonDocument<T>): MergeDocumentsResult<T>;
+/**
+ * Creates an empty JSON:API document with the given eventstamp.
+ * Useful for initializing new stores or testing.
+ *
+ * @param eventstamp - Initial clock value for this document
+ * @returns Empty document
+ *
+ * @example
+ * ```typescript
+ * const empty = makeDocument("2025-01-01T00:00:00.000Z|0000|0000");
+ * ```
+ */
+declare function makeDocument<T extends AnyObject>(eventstamp: string): JsonDocument<T>;
+//#endregion
+//#region src/core/document/utils.d.ts
+/**
+ * Convert a JsonDocument's data array into a Map keyed by resource ID.
+ * @param document - JsonDocument containing resource data
+ * @returns Map of resource ID to ResourceObject
+ */
+declare function documentToMap<T extends AnyObject>(document: JsonDocument<T>): Map<string, ResourceObject<T>>;
+/**
+ * Convert a Map of resources into a JsonDocument.
+ * @param resources - Map of resource ID to ResourceObject
+ * @param fallbackEventstamp - Eventstamp to include when computing the max (optional)
+ * @returns JsonDocument representation of the resources
+ */
+declare function mapToDocument<T extends AnyObject>(resources: Map<string, ResourceObject<T>>, fallbackEventstamp?: string): JsonDocument<T>;
+//#endregion
+//#region src/core/resource-map/resource-map.d.ts
+/**
+ * A ResourceMap container for storing and managing ResourceObjects.
+ *
+ * This factory function creates a ResourceMap with state-based replication
+ * and automatic convergence via Last-Write-Wins conflict resolution.
+ * It stores complete resource snapshots with encoded metadata, including deletion markers.
+ *
+ * ResourceMap does NOT filter based on deletion status—it stores and returns
+ * all ResourceObjects including deleted ones. The Store class is responsible
+ * for filtering what's visible to users.
+ *
+ * @example
+ * ```typescript
+ * const resourceMap = createMap("todos");
+ * resourceMap.set("id1", { name: "Alice" });
+ * const resource = resourceMap.get("id1"); // ResourceObject with metadata
+ * ```
+ */
+declare function createMap<T extends AnyObject>(resourceType: string, initialMap?: Map<string, ResourceObject<T>>, eventstamp?: string): {
+  /**
+   * Check if a resource exists by ID (regardless of deletion status).
+   * @param id - Resource ID
+   */
+  has(id: string): boolean;
+  /**
+   * Get a resource by ID (regardless of deletion status).
+   * @returns The raw resource with metadata (including deletedAt flag), or undefined if not found
+   */
+  get(id: string): ResourceObject<T> | undefined;
+  /**
+   * Iterate over all resources (including deleted) as [id, resource] tuples.
+   */
+  entries(): IterableIterator<readonly [string, ResourceObject<T>]>;
+  /**
+   * Set a resource using field-level Last-Write-Wins merge.
+   * Creates a new resource if it doesn't exist, or merges with existing resource.
+   * @param id - Resource ID (provided by caller, not generated)
+   * @param object - Data to set (partial fields are merged, full objects replace)
+   */
+  set(id: string, object: Partial<T>): void;
+  delete(id: string): void;
+  /**
+   * Clone the internal map of encoded resources.
+   */
+  cloneMap(): Map<string, ResourceObject<T>>;
+  /**
+   * Export the current state as a JsonDocument snapshot.
+   */
+  toDocument(): JsonDocument<T>;
+  /**
+   * Merge another document into this ResourceMap using field-level Last-Write-Wins.
+   * @returns The merge result containing the merged document and tracked changes
+   * @param document - JsonDocument from another replica or storage
+   */
+  merge(document: JsonDocument<T>): MergeDocumentsResult<T>;
+};
+/**
+ * Create a ResourceMap from a JsonDocument snapshot.
+ * @param type - Resource type identifier (defaults to "default")
+ * @param document - JsonDocument containing resource data
+ */
+declare function createMapFromDocument<U extends AnyObject>(type: string, document: JsonDocument<U>): ReturnType<typeof createMap<U>>;
+//#endregion
+export { maxEventstamp as _, AnyObject as a, createClock as b, MergeDocumentsResult as c, ResourceObject as d, deleteResource as f, isValidEventstamp as g, MIN_EVENTSTAMP as h, mapToDocument as i, makeDocument as l, mergeResources as m, createMapFromDocument as n, DocumentChanges as o, makeResource as p, documentToMap as r, JsonDocument as s, createMap as t, mergeDocuments as u, InvalidEventstampError as v, createClockFromEventstamp as x, Clock as y };

package/dist/index.d.ts

@@ -1,270 +1,3 @@
-//#region src/clock/clock.d.ts
-/**
- * A Hybrid Logical Clock that generates monotonically increasing eventstamps.
- * Combines wall-clock time with a counter for handling clock stalls and a
- * random nonce for tie-breaking.
- *
- * The clock automatically increments the counter when the wall clock doesn't
- * advance, ensuring eventstamps are always unique and monotonic.
- *
- * @example
- * ```typescript
- * const clock = createClock();
- * const stamp1 = clock.now();
- * const stamp2 = clock.now();
- * ```
- */
-type Clock = ReturnType<typeof createClock>;
-/**
- * Create a new Clock instance.
- * @param initialState - Optional initial state for the clock
- */
-declare function createClock(initialState?: {
-  counter: number;
-  lastMs: number;
-  lastNonce: string;
-}): {
-  now: () => string;
-  latest: () => string;
-  forward: (eventstamp: string) => void;
-};
-/**
- * Create a Clock from an eventstamp string.
- * @param eventstamp - Eventstamp string to decode and initialize clock from
- * @throws Error if eventstamp is invalid
- */
-declare function createClockFromEventstamp(eventstamp: string): Clock;
-//#endregion
-//#region src/clock/errors.d.ts
-declare class InvalidEventstampError extends Error {
-  constructor(eventstamp: string);
-}
-//#endregion
-//#region src/clock/eventstamp.d.ts
-/**
- * Validates whether a string is a properly formatted eventstamp.
- * Expected format: YYYY-MM-DDTHH:mm:ss.SSSZ|HHHH+|HHHH
- * where HHHH+ represents 4 or more hex characters for the counter,
- * and HHHH represents exactly 4 hex characters for the nonce.
- */
-declare function isValidEventstamp(stamp: string): boolean;
-declare const MIN_EVENTSTAMP: string;
-/**
- * Find the maximum eventstamp from an array of eventstamps.
- * Returns MIN_EVENTSTAMP if the array is empty.
- * @param eventstamps - Array of eventstamp strings
- * @returns The maximum eventstamp
- */
-declare function maxEventstamp(eventstamps: string[]): string;
-//#endregion
-//#region src/document/resource.d.ts
-/**
- * Resource object structure representing a single stored entity.
- * Resources are the primary unit of storage and synchronization in Starling.
- *
- * Each resource has a type, unique identifier, attributes containing the data,
- * and metadata for tracking deletion state and eventstamps.
- */
-type ResourceObject<T extends AnyObject> = {
-  /** Resource type identifier */
-  type: string;
-  /** Unique identifier for this resource */
-  id: string;
-  /** The resource's data as a nested object structure */
-  attributes: T;
-  /** Metadata for tracking deletion and eventstamps */
-  meta: {
-    /** Flat map of dot-separated paths to eventstamps (e.g., "user.address.street": "2025-11-18...") */
-    eventstamps: Record<string, string>;
-    /** The greatest eventstamp in this resource (including deletedAt if applicable) */
-    latest: string;
-    /** Eventstamp when this resource was soft-deleted, or null if not deleted */
-    deletedAt: string | null;
-  };
-};
-declare function makeResource<T extends AnyObject>(type: string, id: string, obj: T, eventstamp: string, deletedAt?: string | null): ResourceObject<T>;
-declare function mergeResources<T extends AnyObject>(into: ResourceObject<T>, from: ResourceObject<T>): ResourceObject<T>;
-declare function deleteResource<T extends AnyObject>(resource: ResourceObject<T>, eventstamp: string): ResourceObject<T>;
-//#endregion
-//#region src/document/document.d.ts
-/**
- * Base constraint for all document data in Starling.
- * Documents must be plain JavaScript objects with string keys.
- */
-type AnyObject = Record<string, unknown>;
-/**
- * A JSON:API document represents the complete state of a store:
- * - API version information
- * - Metadata including the highest eventstamp observed across all operations
- * - A set of resource objects (including soft-deleted ones)
- *
- * Documents are the unit of synchronization between store replicas.
- */
-type JsonDocument<T extends AnyObject> = {
-  /** API version information */
-  jsonapi: {
-    version: "1.1";
-  };
-  /** Document-level metadata */
-  meta: {
-    /** Latest eventstamp observed by this document for clock synchronization */
-    latest: string;
-  };
-  /** Array of resource objects with eventstamps and metadata */
-  data: ResourceObject<T>[];
-};
-/**
- * Change tracking information returned by mergeDocuments.
- * Categorizes resources by mutation type for hook notifications.
- */
-type DocumentChanges<T extends AnyObject> = {
-  /** Resources that were newly added (didn't exist before or were previously deleted) */
-  added: Map<string, ResourceObject<T>>;
-  /** Resources that were modified (existed before and changed) */
-  updated: Map<string, ResourceObject<T>>;
-  /** Resources that were deleted (newly marked with deletedAt) */
-  deleted: Set<string>;
-};
-/**
- * Result of merging two JSON:API documents.
- */
-type MergeDocumentsResult<T extends AnyObject> = {
-  /** The merged document with updated resources and forwarded clock */
-  document: JsonDocument<T>;
-  /** Change tracking for plugin hook notifications */
-  changes: DocumentChanges<T>;
-};
-/**
- * Merges two JSON:API documents using field-level Last-Write-Wins semantics.
- *
- * The merge operation:
- * 1. Forwards the clock to the newest eventstamp from either document
- * 2. Merges each resource pair using field-level LWW (via mergeResources)
- * 3. Tracks what changed for hook notifications (added/updated/deleted)
- *
- * Deletion is final: once a resource is deleted, updates to it are merged into
- * the resource's attributes but don't restore visibility. Only new resources or
- * transitions into the deleted state are tracked.
- *
- * @param into - The base document to merge into
- * @param from - The source document to merge from
- * @returns Merged document and categorized changes
- *
- * @example
- * ```typescript
- * const into = {
- *   jsonapi: { version: "1.1" },
- *   meta: { latest: "2025-01-01T00:00:00.000Z|0001|a1b2" },
- *   data: [{ type: "items", id: "doc1", attributes: {...}, meta: { deletedAt: null, latest: "..." } }]
- * };
- *
- * const from = {
- *   jsonapi: { version: "1.1" },
- *   meta: { latest: "2025-01-01T00:05:00.000Z|0001|c3d4" },
- *   data: [
- *     { type: "items", id: "doc1", attributes: {...}, meta: { deletedAt: null, latest: "..." } }, // updated
- *     { type: "items", id: "doc2", attributes: {...}, meta: { deletedAt: null, latest: "..." } }  // new
- *   ]
- * };
- *
- * const result = mergeDocuments(into, from);
- * // result.document.meta.latest === "2025-01-01T00:05:00.000Z|0001|c3d4"
- * // result.changes.added has "doc2"
- * // result.changes.updated has "doc1"
- * ```
- */
-declare function mergeDocuments<T extends AnyObject>(into: JsonDocument<T>, from: JsonDocument<T>): MergeDocumentsResult<T>;
-/**
- * Creates an empty JSON:API document with the given eventstamp.
- * Useful for initializing new stores or testing.
- *
- * @param eventstamp - Initial clock value for this document
- * @returns Empty document
- *
- * @example
- * ```typescript
- * const empty = makeDocument("2025-01-01T00:00:00.000Z|0000|0000");
- * ```
- */
-declare function makeDocument<T extends AnyObject>(eventstamp: string): JsonDocument<T>;
-//#endregion
-//#region src/document/utils.d.ts
-/**
- * Convert a JsonDocument's data array into a Map keyed by resource ID.
- * @param document - JsonDocument containing resource data
- * @returns Map of resource ID to ResourceObject
- */
-declare function documentToMap<T extends AnyObject>(document: JsonDocument<T>): Map<string, ResourceObject<T>>;
-/**
- * Convert a Map of resources into a JsonDocument.
- * @param resources - Map of resource ID to ResourceObject
- * @param fallbackEventstamp - Eventstamp to include when computing the max (optional)
- * @returns JsonDocument representation of the resources
- */
-declare function mapToDocument<T extends AnyObject>(resources: Map<string, ResourceObject<T>>, fallbackEventstamp?: string): JsonDocument<T>;
-//#endregion
-//#region src/resource-map/resource-map.d.ts
-/**
- * A ResourceMap container for storing and managing ResourceObjects.
- *
- * This factory function creates a ResourceMap with state-based replication
- * and automatic convergence via Last-Write-Wins conflict resolution.
- * It stores complete resource snapshots with encoded metadata, including deletion markers.
- *
- * ResourceMap does NOT filter based on deletion status—it stores and returns
- * all ResourceObjects including deleted ones. The Store class is responsible
- * for filtering what's visible to users.
- *
- * @example
- * ```typescript
- * const resourceMap = createMap("todos");
- * resourceMap.set("id1", { name: "Alice" });
- * const resource = resourceMap.get("id1"); // ResourceObject with metadata
- * ```
- */
-declare function createMap<T extends AnyObject>(resourceType: string, initialMap?: Map<string, ResourceObject<T>>, eventstamp?: string): {
-  /**
-   * Check if a resource exists by ID (regardless of deletion status).
-   * @param id - Resource ID
-   */
-  has(id: string): boolean;
-  /**
-   * Get a resource by ID (regardless of deletion status).
-   * @returns The raw resource with metadata (including deletedAt flag), or undefined if not found
-   */
-  get(id: string): ResourceObject<T> | undefined;
-  /**
-   * Iterate over all resources (including deleted) as [id, resource] tuples.
-   */
-  entries(): IterableIterator<readonly [string, ResourceObject<T>]>;
-  /**
-   * Set a resource using field-level Last-Write-Wins merge.
-   * Creates a new resource if it doesn't exist, or merges with existing resource.
-   * @param id - Resource ID (provided by caller, not generated)
-   * @param object - Data to set (partial fields are merged, full objects replace)
-   */
-  set(id: string, object: Partial<T>): void;
-  delete(id: string): void;
-  /**
-   * Clone the internal map of encoded resources.
-   */
-  cloneMap(): Map<string, ResourceObject<T>>;
-  /**
-   * Export the current state as a JsonDocument snapshot.
-   */
-  toDocument(): JsonDocument<T>;
-  /**
-   * Merge another document into this ResourceMap using field-level Last-Write-Wins.
-   * @returns The merge result containing the merged document and tracked changes
-   * @param document - JsonDocument from another replica or storage
-   */
-  merge(document: JsonDocument<T>): MergeDocumentsResult<T>;
-};
-/**
- * Create a ResourceMap from a JsonDocument snapshot.
- * @param type - Resource type identifier (defaults to "default")
- * @param document - JsonDocument containing resource data
- */
-declare function createMapFromDocument<U extends AnyObject>(type: string, document: JsonDocument<U>): ReturnType<typeof createMap<U>>;
-//#endregion
-export { AnyObject, Clock, DocumentChanges, InvalidEventstampError, JsonDocument, MIN_EVENTSTAMP, MergeDocumentsResult, ResourceObject, createClock, createClockFromEventstamp, createMap, createMapFromDocument, deleteResource, documentToMap, isValidEventstamp, makeDocument, makeResource, mapToDocument, maxEventstamp, mergeDocuments, mergeResources };
+import { a as AnyObject, s as JsonDocument } from "./index-D7bXWDg6.js";
+import { a as createDatabase, c as QueryCollectionHandle, d as Collection, f as CollectionInternals, g as StandardSchemaV1, i as DbConfig, l as QueryContext, m as IdNotFoundError, n as Database, o as TransactionCollectionHandle, p as DuplicateIdError, r as DatabasePlugin, s as TransactionContext, t as CollectionConfig, u as QueryHandle } from "./db-qQgPYE41.js";
+export { type AnyObject, type Collection, type CollectionConfig, CollectionInternals, type Database, type DatabasePlugin, type DbConfig, DuplicateIdError, IdNotFoundError, type JsonDocument, type QueryCollectionHandle, type QueryContext, type QueryHandle, type StandardSchemaV1, type TransactionCollectionHandle, type TransactionContext, createDatabase };