@byearlybird/starling 0.11.1 → 0.13.0

package/dist/db-DJ_6dO-K.d.ts

@@ -1,199 +0,0 @@
-import { a as AnyObject, s as JsonDocument } from "./index-D7bXWDg6.js";
-
-//#region src/database/standard-schema.d.ts
-/** The Standard Schema interface. */
-interface StandardSchemaV1<Input = unknown, Output = Input> {
-  /** The Standard Schema properties. */
-  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
-}
-declare namespace StandardSchemaV1 {
-  /** The Standard Schema properties interface. */
-  interface Props<Input = unknown, Output = Input> {
-    /** The version number of the standard. */
-    readonly version: 1;
-    /** The vendor name of the schema library. */
-    readonly vendor: string;
-    /** Validates unknown input values. */
-    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
-    /** Inferred types associated with the schema. */
-    readonly types?: Types<Input, Output> | undefined;
-  }
-  /** The result interface of the validate function. */
-  type Result<Output> = SuccessResult<Output> | FailureResult;
-  /** The result interface if validation succeeds. */
-  interface SuccessResult<Output> {
-    /** The typed output value. */
-    readonly value: Output;
-    /** The non-existent issues. */
-    readonly issues?: undefined;
-  }
-  /** The result interface if validation fails. */
-  interface FailureResult {
-    /** The issues of failed validation. */
-    readonly issues: ReadonlyArray<Issue>;
-  }
-  /** The issue interface of the failure output. */
-  interface Issue {
-    /** The error message of the issue. */
-    readonly message: string;
-    /** The path of the issue, if any. */
-    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
-  }
-  /** The path segment interface of the issue. */
-  interface PathSegment {
-    /** The key representing a path segment. */
-    readonly key: PropertyKey;
-  }
-  /** The Standard Schema types interface. */
-  interface Types<Input = unknown, Output = Input> {
-    /** The input type of the schema. */
-    readonly input: Input;
-    /** The output type of the schema. */
-    readonly output: Output;
-  }
-  /** Infers the input type of a Standard Schema. */
-  type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
-  /** Infers the output type of a Standard Schema. */
-  type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
-}
-//#endregion
-//#region src/database/types.d.ts
-type AnyObjectSchema<T extends AnyObject = AnyObject> = StandardSchemaV1<T>;
-type SchemasMap = Record<string, AnyObjectSchema>;
-//#endregion
-//#region src/database/collection.d.ts
-/**
- * Symbols for internal collection methods used by transactions.
- * These are not part of the public Collection type.
- */
-declare const CollectionInternals: {
-  readonly getPendingMutations: symbol;
-  readonly emitMutations: symbol;
-  readonly replaceData: symbol;
-  readonly data: symbol;
-};
-/** Shorthand for extracting the data type from a schema */
-type InferData<T extends AnyObjectSchema> = StandardSchemaV1.InferOutput<T>;
-type MutationBatch<T> = {
-  added: Array<{
-    id: string;
-    item: T;
-  }>;
-  updated: Array<{
-    id: string;
-    before: T;
-    after: T;
-  }>;
-  removed: Array<{
-    id: string;
-    item: T;
-  }>;
-};
-type CollectionMutationEvent<T> = MutationBatch<T>;
-type Collection<T extends AnyObjectSchema> = {
-  get(id: string, opts?: {
-    includeDeleted?: boolean;
-  }): InferData<T> | null;
-  getAll(opts?: {
-    includeDeleted?: boolean;
-  }): InferData<T>[];
-  find<U = InferData<T>>(filter: (item: InferData<T>) => boolean, opts?: {
-    map?: (item: InferData<T>) => U;
-    sort?: (a: U, b: U) => number;
-  }): U[];
-  add(item: StandardSchemaV1.InferInput<T>): InferData<T>;
-  update(id: string, updates: Partial<StandardSchemaV1.InferInput<T>>): void;
-  remove(id: string): void;
-  merge(document: JsonDocument<InferData<T>>): void;
-  toDocument(): JsonDocument<InferData<T>>;
-  on(event: "mutation", handler: (payload: CollectionMutationEvent<InferData<T>>) => void): () => void;
-};
-declare class IdNotFoundError extends Error {
-  constructor(id: string);
-}
-declare class DuplicateIdError extends Error {
-  constructor(id: string);
-}
-//#endregion
-//#region src/database/query.d.ts
-/** Read-only collection handle for queries */
-type QueryCollectionHandle<T extends AnyObjectSchema> = Pick<Collection<T>, "get" | "getAll" | "find">;
-/** Query context with read-only collection handles */
-type QueryContext<Schemas extends SchemasMap> = { [K in keyof Schemas]: QueryCollectionHandle<Schemas[K]> };
-/** Handle returned by db.query() for managing the reactive query */
-type QueryHandle<R> = {
-  /** Current query result */
-  readonly result: R;
-  /** Subscribe to result changes. Returns unsubscribe function. */
-  subscribe(callback: (result: R) => void): () => void;
-  /** Stop tracking and clean up subscriptions */
-  dispose(): void;
-};
-//#endregion
-//#region src/database/transaction.d.ts
-/** Transaction-safe collection handle that excludes event subscription and serialization */
-type TransactionCollectionHandle<T extends AnyObjectSchema> = Omit<Collection<T>, "on" | "toDocument">;
-type TransactionCollectionHandles<Schemas extends SchemasMap> = { [K in keyof Schemas]: TransactionCollectionHandle<Schemas[K]> };
-type TransactionContext<Schemas extends SchemasMap> = TransactionCollectionHandles<Schemas> & {
-  rollback(): void;
-};
-//#endregion
-//#region src/database/db.d.ts
-type Collections<Schemas extends SchemasMap> = { [K in keyof Schemas]: Collection<Schemas[K]> };
-type CollectionConfigMap<Schemas extends SchemasMap> = { [K in keyof Schemas]: CollectionConfig<Schemas[K]> };
-type MutationEnvelope<Schemas extends SchemasMap> = { [K in keyof Schemas]: {
-  collection: K;
-} & MutationBatch<StandardSchemaV1.InferOutput<Schemas[K]>> }[keyof Schemas];
-type DatabaseMutationEvent<Schemas extends SchemasMap> = MutationEnvelope<Schemas>;
-type CollectionConfig<T extends AnyObjectSchema> = {
-  schema: T;
-  getId: (item: StandardSchemaV1.InferOutput<T>) => string;
-};
-type DatabasePlugin<Schemas extends SchemasMap> = {
-  handlers: {
-    init?: (db: Database<Schemas>) => Promise<unknown> | unknown;
-    dispose?: (db: Database<Schemas>) => Promise<unknown> | unknown;
-  };
-};
-type DbConfig<Schemas extends SchemasMap> = {
-  name: string;
-  schema: CollectionConfigMap<Schemas>;
-  version?: number;
-};
-type Database<Schemas extends SchemasMap> = Collections<Schemas> & {
-  name: string;
-  version: number;
-  begin<R>(callback: (tx: TransactionContext<Schemas>) => R): R;
-  query<R>(callback: (ctx: QueryContext<Schemas>) => R): QueryHandle<R>;
-  toDocuments(): { [K in keyof Schemas]: JsonDocument<StandardSchemaV1.InferOutput<Schemas[K]>> };
-  on(event: "mutation", handler: (payload: DatabaseMutationEvent<Schemas>) => unknown): () => void;
-  use(plugin: DatabasePlugin<Schemas>): Database<Schemas>;
-  init(): Promise<Database<Schemas>>;
-  dispose(): Promise<void>;
-  collectionKeys(): (keyof Schemas)[];
-};
-/**
- * Create a typed database instance with collection access.
- * @param config - Database configuration
- * @param config.name - Database name used for persistence and routing
- * @param config.schema - Collection schema definitions
- * @param config.version - Optional database version, defaults to 1
- * @returns A database instance with typed collection properties
- *
- * @example
- * ```typescript
- * const db = await createDatabase({
- *   name: "my-app",
- *   schema: {
- *     tasks: { schema: taskSchema, getId: (task) => task.id },
- *   },
- * })
- *   .use(idbPlugin())
- *   .init();
- *
- * const task = db.tasks.add({ title: 'Learn Starling' });
- * ```
- */
-declare function createDatabase<Schemas extends SchemasMap>(config: DbConfig<Schemas>): Database<Schemas>;
-//#endregion
-export { StandardSchemaV1 as _, createDatabase as a, QueryCollectionHandle as c, Collection as d, CollectionInternals as f, SchemasMap as g, AnyObjectSchema as h, DbConfig as i, QueryContext as l, IdNotFoundError as m, Database as n, TransactionCollectionHandle as o, DuplicateIdError as p, DatabasePlugin as r, TransactionContext as s, CollectionConfig as t, QueryHandle as u };

package/dist/index-D7bXWDg6.d.ts

@@ -1,270 +0,0 @@
-//#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/plugin-http.d.ts

@@ -1,139 +0,0 @@
-import { a as AnyObject, s as JsonDocument } from "./index-D7bXWDg6.js";
-import { g as SchemasMap, r as DatabasePlugin } from "./db-DJ_6dO-K.js";
-
-//#region src/plugins/http/index.d.ts
-
-/**
- * Context provided to the onRequest hook
- */
-type RequestContext<T extends AnyObject = AnyObject> = {
-  collection: string;
-  operation: "GET" | "PATCH";
-  url: string;
-  document?: JsonDocument<T>;
-};
-/**
- * Result returned by the onRequest hook
- */
-type RequestHookResult<T extends AnyObject = AnyObject> = {
-  skip: true;
-} | {
-  headers?: Record<string, string>;
-  document?: JsonDocument<T>;
-} | undefined;
-/**
- * Result returned by the onResponse hook
- */
-type ResponseHookResult<T extends AnyObject = AnyObject> = {
-  document: JsonDocument<T>;
-} | {
-  skip: true;
-} | undefined;
-/**
- * Configuration for the HTTP plugin
- */
-type HttpPluginConfig<_Schemas extends SchemasMap> = {
-  /**
-   * Base URL for the HTTP server (e.g., "https://api.example.com")
-   */
-  baseUrl: string;
-  /**
-   * Interval in milliseconds to poll for server updates
-   * @default 5000
-   */
-  pollingInterval?: number;
-  /**
-   * Delay in milliseconds to debounce local mutations before pushing
-   * @default 1000
-   */
-  debounceDelay?: number;
-  /**
-   * Hook called before each HTTP request
-   * Return { skip: true } to abort the request
-   * Return { headers } to add custom headers
-   * Return { document } to transform the document (PATCH only)
-   */
-  onRequest?: <T extends AnyObject>(context: RequestContext<T>) => RequestHookResult<T>;
-  /**
-   * Hook called after each successful HTTP response
-   * Return { skip: true } to skip merging the response
-   * Return { document } to transform the document before merging
-   */
-  onResponse?: <T extends AnyObject>(context: {
-    collection: string;
-    document: JsonDocument<T>;
-  }) => ResponseHookResult<T>;
-  /**
-   * Retry configuration for failed requests
-   */
-  retry?: {
-    /**
-     * Maximum number of retry attempts
-     * @default 3
-     */
-    maxAttempts?: number;
-    /**
-     * Initial delay in milliseconds before first retry
-     * @default 1000
-     */
-    initialDelay?: number;
-    /**
-     * Maximum delay in milliseconds between retries
-     * @default 30000
-     */
-    maxDelay?: number;
-  };
-};
-/**
- * Create an HTTP sync plugin for Starling databases.
- *
- * The plugin:
- * - Fetches all collections from the server on init (single attempt)
- * - Polls the server at regular intervals to fetch updates (with retry)
- * - Debounces local mutations and pushes them to the server (with retry)
- * - Supports request/response hooks for authentication, encryption, etc.
- *
- * @param config - HTTP plugin configuration
- * @returns A DatabasePlugin instance
- *
- * @example
- * ```typescript
- * const db = await createDatabase({
- *   name: "my-app",
- *   schema: {
- *     tasks: { schema: taskSchema, getId: (task) => task.id },
- *   },
- * })
- *   .use(httpPlugin({
- *     baseUrl: "https://api.example.com",
- *     onRequest: () => ({
- *       headers: { Authorization: `Bearer ${token}` }
- *     })
- *   }))
- *   .init();
- * ```
- *
- * @example With encryption
- * ```typescript
- * const db = await createDatabase({
- *   name: "my-app",
- *   schema: {
- *     tasks: { schema: taskSchema, getId: (task) => task.id },
- *   },
- * })
- *   .use(httpPlugin({
- *     baseUrl: "https://api.example.com",
- *     onRequest: ({ document }) => ({
- *       headers: { Authorization: `Bearer ${token}` },
- *       document: document ? encrypt(document) : undefined
- *     }),
- *     onResponse: ({ document }) => ({
- *       document: decrypt(document)
- *     })
- *   }))
- *   .init();
- * ```
- */
-declare function httpPlugin<Schemas extends SchemasMap>(config: HttpPluginConfig<Schemas>): DatabasePlugin<Schemas>;
-//#endregion
-export { HttpPluginConfig, RequestContext, RequestHookResult, ResponseHookResult, httpPlugin };