@keepkit/core 0.1.0 → 0.2.0

package/dist/chunk-THZ3ACR2.js

@@ -0,0 +1,41 @@
+// src/schema.ts
+var KeepSchemaValidationError = class extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "KeepSchemaValidationError";
+    this.cause = options.cause;
+    this.itemId = options.itemId;
+  }
+};
+async function parseKeepMeta(schema, value) {
+  try {
+    if ("parse" in schema) return await schema.parse(value);
+    if ("safeParse" in schema) {
+      const result2 = await schema.safeParse(value);
+      if (result2.success) return result2.data;
+      throw new KeepSchemaValidationError("KeepKit metadata did not match the configured schema.", {
+        cause: result2.error
+      });
+    }
+    const result = await schema["~standard"].validate(value);
+    if (!result.issues && "value" in result) return result.value;
+    throw new KeepSchemaValidationError("KeepKit metadata did not match the configured schema.", {
+      cause: result.issues
+    });
+  } catch (cause) {
+    if (cause instanceof KeepSchemaValidationError) throw cause;
+    throw new KeepSchemaValidationError("KeepKit metadata did not match the configured schema.", {
+      cause
+    });
+  }
+}
+async function validateKeepItem(item, schema) {
+  return { ...item, meta: await parseKeepMeta(schema, item.meta) };
+}
+
+export {
+  KeepSchemaValidationError,
+  parseKeepMeta,
+  validateKeepItem
+};
+//# sourceMappingURL=chunk-THZ3ACR2.js.map

package/dist/chunk-THZ3ACR2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts"],"sourcesContent":["import type { KeepItem, KeepSchema } from \"./types\";\n\nexport class KeepSchemaValidationError extends Error {\n  readonly cause?: unknown;\n  readonly itemId?: string;\n\n  constructor(message: string, options: { cause?: unknown; itemId?: string } = {}) {\n    super(message);\n    this.name = \"KeepSchemaValidationError\";\n    this.cause = options.cause;\n    this.itemId = options.itemId;\n  }\n}\n\n/** Parse metadata with a Zod-like, safeParse-like, or Standard Schema parser. */\nexport async function parseKeepMeta<T>(schema: KeepSchema<T>, value: unknown): Promise<T> {\n  try {\n    if (\"parse\" in schema) return await schema.parse(value);\n\n    if (\"safeParse\" in schema) {\n      const result = await schema.safeParse(value);\n      if (result.success) return result.data;\n      throw new KeepSchemaValidationError(\"KeepKit metadata did not match the configured schema.\", {\n        cause: result.error,\n      });\n    }\n\n    const result = await schema[\"~standard\"].validate(value);\n    if (!result.issues && \"value\" in result) return result.value as T;\n    throw new KeepSchemaValidationError(\"KeepKit metadata did not match the configured schema.\", {\n      cause: result.issues,\n    });\n  } catch (cause) {\n    if (cause instanceof KeepSchemaValidationError) throw cause;\n    throw new KeepSchemaValidationError(\"KeepKit metadata did not match the configured schema.\", {\n      cause,\n    });\n  }\n}\n\nexport async function validateKeepItem<TMeta>(\n  item: KeepItem<unknown>,\n  schema: KeepSchema<TMeta>,\n): Promise<KeepItem<TMeta>> {\n  return { ...item, meta: await parseKeepMeta(schema, item.meta) };\n}\n"],"mappings":";AAEO,IAAM,4BAAN,cAAwC,MAAM;AAAA,EAInD,YAAY,SAAiB,UAAgD,CAAC,GAAG;AAC/E,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,QAAQ,QAAQ;AACrB,SAAK,SAAS,QAAQ;AAAA,EACxB;AACF;AAGA,eAAsB,cAAiB,QAAuB,OAA4B;AACxF,MAAI;AACF,QAAI,WAAW,OAAQ,QAAO,MAAM,OAAO,MAAM,KAAK;AAEtD,QAAI,eAAe,QAAQ;AACzB,YAAMA,UAAS,MAAM,OAAO,UAAU,KAAK;AAC3C,UAAIA,QAAO,QAAS,QAAOA,QAAO;AAClC,YAAM,IAAI,0BAA0B,yDAAyD;AAAA,QAC3F,OAAOA,QAAO;AAAA,MAChB,CAAC;AAAA,IACH;AAEA,UAAM,SAAS,MAAM,OAAO,WAAW,EAAE,SAAS,KAAK;AACvD,QAAI,CAAC,OAAO,UAAU,WAAW,OAAQ,QAAO,OAAO;AACvD,UAAM,IAAI,0BAA0B,yDAAyD;AAAA,MAC3F,OAAO,OAAO;AAAA,IAChB,CAAC;AAAA,EACH,SAAS,OAAO;AACd,QAAI,iBAAiB,0BAA2B,OAAM;AACtD,UAAM,IAAI,0BAA0B,yDAAyD;AAAA,MAC3F;AAAA,IACF,CAAC;AAAA,EACH;AACF;AAEA,eAAsB,iBACpB,MACA,QAC0B;AAC1B,SAAO,EAAE,GAAG,MAAM,MAAM,MAAM,cAAc,QAAQ,KAAK,IAAI,EAAE;AACjE;","names":["result"]}

package/dist/core.d.ts

@@ -0,0 +1,66 @@
+import { K as KeepSchema, b as KeepInvalidItemPolicy, a as KeepItem, S as StorageAdapter, c as KeepPluginContext, d as KeepPlugin } from './types-DtILwEQ0.js';
+export { e as KeepAction, f as KeepChangeContext, g as KeepChangePhase, h as KeepConflictContext, i as KeepConflictResolver, j as KeepErrorContext, k as KeepErrorHandler, l as KeepEventHandlers, m as KeepItemInput, n as KeepSchemaParseResult, o as KeepStorageAccessError, p as KeepStorageError, q as KeepStorageOperation, r as KeepStorageParseError, s as KeepStorageQuotaError, t as KeepSyncState, u as KeepSyncStatus, R as RemoteSyncDriver, v as RemoteSyncResult, w as SyncCapableStorageAdapter, x as SyncOperation, y as SyncQueueAdapter, z as normalizeKeepTags } from './types-DtILwEQ0.js';
+export { K as KeepListOptions, a as KeepStore, b as KeepStoreActions, c as KeepStoreState, Q as QueryKeepItemsResult, g as getTagCounts, q as queryKeepItems } from './store-BAvx_Iaw.js';
+export { KeepSchemaValidationError, parseKeepMeta, validateKeepItem } from './schema.js';
+export { BrowserStorageAdapterOptions, DEFAULT_INDEXEDDB_DATABASE, DEFAULT_INDEXEDDB_STORE, DEFAULT_STORAGE_KEY, DEFAULT_SYNC_QUEUE_DATABASE, DEFAULT_SYNC_QUEUE_KEY, DEFAULT_SYNC_QUEUE_STORE, FallbackStorageAdapter, FallbackStorageAdapterOptions, FallbackSyncQueueAdapter, FallbackSyncQueueAdapterOptions, IndexedDBAdapter, IndexedDBAdapterOptions, IndexedDBSyncQueueAdapter, IndexedDBSyncQueueOptions, LocalStorageAdapter, LocalStorageAdapterOptions, LocalStorageSyncQueueAdapter, LocalStorageSyncQueueOptions, StorageAdapterFactoryOptions, SyncStorageAdapter, SyncStorageAdapterOptions, createBrowserStorageAdapter, createStorageAdapter } from './storage.js';
+
+declare const KEEP_BACKUP_FORMAT = "keepkit";
+declare const KEEP_BACKUP_VERSION = 1;
+type KeepBackup<TMeta = Record<string, unknown>> = {
+    format: typeof KEEP_BACKUP_FORMAT;
+    version: typeof KEEP_BACKUP_VERSION;
+    exportedAt: number;
+    items: KeepItem<TMeta>[];
+};
+type ImportItemsOptions<TMeta = unknown> = {
+    mode?: "replace" | "merge";
+    schema?: KeepSchema<TMeta>;
+    invalidItemPolicy?: KeepInvalidItemPolicy;
+    onInvalidItem?: (error: unknown, item: KeepItem<unknown>) => void;
+};
+type ImportItemsResult<TMeta = Record<string, unknown>> = {
+    mode: "replace" | "merge";
+    imported: number;
+    failed: number;
+    total: number;
+    items: KeepItem<TMeta>[];
+};
+declare class KeepBackupParseError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class KeepBackupImportError extends Error {
+    readonly mode: "replace" | "merge";
+    readonly imported: number;
+    readonly failed: number;
+    readonly cause?: unknown;
+    constructor(message: string, options: {
+        mode: "replace" | "merge";
+        imported: number;
+        failed: number;
+        cause?: unknown;
+    });
+}
+/** Serialize all adapter data into a versioned JSON backup. */
+declare function exportItems<TMeta>(adapter: StorageAdapter<TMeta>): Promise<string>;
+/** Validate and restore a backup, either replacing or merging existing data. */
+declare function importItems<TMeta>(adapter: StorageAdapter<TMeta>, data: string | KeepBackup<TMeta>, options?: ImportItemsOptions<TMeta>): Promise<ImportItemsResult<TMeta>>;
+
+type KeepInvalidationPluginOptions<TMeta = Record<string, unknown>> = {
+    /** Query keys to invalidate after a successful local KeepKit mutation. */
+    queryKeys: readonly unknown[] | ((context: KeepPluginContext<TMeta>) => readonly (readonly unknown[])[]);
+    /** Connect this callback to queryClient.invalidateQueries or SWR mutate. */
+    invalidate: (queryKey: readonly unknown[], context: KeepPluginContext<TMeta>) => void | Promise<void>;
+    name?: string;
+};
+/** Framework-neutral bridge for TanStack Query, SWR, and similar caches. */
+declare function createKeepInvalidationPlugin<TMeta = Record<string, unknown>>(options: KeepInvalidationPluginOptions<TMeta>): KeepPlugin<TMeta>;
+
+/** Merge anonymous local items into a signed-in or remote adapter. */
+declare function mergeKeepItems<TMeta>(localItems: KeepItem<TMeta>[], target: StorageAdapter<TMeta>): Promise<KeepItem<TMeta>[]>;
+/** Read anonymous items, merge them into the target, then clear the source. */
+declare function migrateKeepItems<TMeta>(source: StorageAdapter<TMeta>, target: StorageAdapter<TMeta>): Promise<KeepItem<TMeta>[]>;
+
+export { type ImportItemsOptions, type ImportItemsResult, KEEP_BACKUP_FORMAT, KEEP_BACKUP_VERSION, type KeepBackup, KeepBackupImportError, KeepBackupParseError, KeepInvalidItemPolicy, type KeepInvalidationPluginOptions, KeepItem, KeepPlugin, KeepPluginContext, KeepSchema, StorageAdapter, createKeepInvalidationPlugin, exportItems, importItems, mergeKeepItems, migrateKeepItems };

package/dist/core.js

@@ -0,0 +1,214 @@
+import {
+  KeepStore,
+  getTagCounts,
+  queryKeepItems
+} from "./chunk-PLT2WJVM.js";
+import {
+  KeepSchemaValidationError,
+  parseKeepMeta,
+  validateKeepItem
+} from "./chunk-THZ3ACR2.js";
+import {
+  DEFAULT_INDEXEDDB_DATABASE,
+  DEFAULT_INDEXEDDB_STORE,
+  DEFAULT_STORAGE_KEY,
+  DEFAULT_SYNC_QUEUE_DATABASE,
+  DEFAULT_SYNC_QUEUE_KEY,
+  DEFAULT_SYNC_QUEUE_STORE,
+  FallbackStorageAdapter,
+  FallbackSyncQueueAdapter,
+  IndexedDBAdapter,
+  IndexedDBSyncQueueAdapter,
+  KeepStorageAccessError,
+  KeepStorageError,
+  KeepStorageParseError,
+  KeepStorageQuotaError,
+  LocalStorageAdapter,
+  LocalStorageSyncQueueAdapter,
+  SyncStorageAdapter,
+  createBrowserStorageAdapter,
+  createStorageAdapter,
+  normalizeKeepTags
+} from "./chunk-C3SOQCVW.js";
+
+// src/migration.ts
+async function mergeKeepItems(localItems, target) {
+  if (target.merge) return target.merge(localItems);
+  const remoteItems = await target.getAll();
+  const byId = new Map(remoteItems.map((item) => [item.id, item]));
+  for (const localItem of localItems) {
+    const remoteItem = byId.get(localItem.id);
+    if (!remoteItem || localItem.updatedAt > remoteItem.updatedAt) {
+      byId.set(localItem.id, localItem);
+    }
+  }
+  const merged = [...byId.values()].sort((a, b) => b.updatedAt - a.updatedAt);
+  await Promise.all(merged.map((item) => target.set(item)));
+  return merged;
+}
+async function migrateKeepItems(source, target) {
+  const localItems = await source.getAll();
+  const merged = await mergeKeepItems(localItems, target);
+  await source.clear();
+  return merged;
+}
+
+// src/backup.ts
+var KEEP_BACKUP_FORMAT = "keepkit";
+var KEEP_BACKUP_VERSION = 1;
+var KeepBackupParseError = class extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "KeepBackupParseError";
+    if (options?.cause !== void 0) this.cause = options.cause;
+  }
+};
+var KeepBackupImportError = class extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "KeepBackupImportError";
+    this.mode = options.mode;
+    this.imported = options.imported;
+    this.failed = options.failed;
+    if (options.cause !== void 0) this.cause = options.cause;
+  }
+};
+async function exportItems(adapter) {
+  const backup = {
+    format: KEEP_BACKUP_FORMAT,
+    version: KEEP_BACKUP_VERSION,
+    exportedAt: Date.now(),
+    items: await adapter.getAll()
+  };
+  return JSON.stringify(backup, null, 2);
+}
+async function importItems(adapter, data, options = {}) {
+  const backup = parseBackup(data);
+  const mode = options.mode ?? "merge";
+  const validItems = [];
+  let failed = 0;
+  for (const item of backup.items) {
+    if (!options.schema) {
+      validItems.push(item);
+      continue;
+    }
+    try {
+      validItems.push(await validateKeepItem(item, options.schema));
+    } catch (cause) {
+      options.onInvalidItem?.(cause, item);
+      if ((options.invalidItemPolicy ?? "error") === "drop") {
+        failed += 1;
+        continue;
+      }
+      throw cause;
+    }
+  }
+  let items;
+  if (mode === "merge") {
+    try {
+      items = await mergeKeepItems(validItems, adapter);
+    } catch (cause) {
+      throw new KeepBackupImportError("KeepKit could not merge the backup.", {
+        mode,
+        imported: 0,
+        failed: validItems.length + failed,
+        cause
+      });
+    }
+  } else {
+    let imported = 0;
+    try {
+      await adapter.clear();
+      for (const item of validItems) {
+        await adapter.set(item);
+        imported += 1;
+      }
+      items = await adapter.getAll();
+    } catch (cause) {
+      throw new KeepBackupImportError("KeepKit could not replace the stored items.", {
+        mode,
+        imported,
+        failed: validItems.length + failed - imported,
+        cause
+      });
+    }
+  }
+  return { mode, imported: validItems.length, failed, total: items.length, items };
+}
+function parseBackup(data) {
+  let value = data;
+  if (typeof data === "string") {
+    try {
+      value = JSON.parse(data);
+    } catch (cause) {
+      throw new KeepBackupParseError("KeepKit backup is not valid JSON.", { cause });
+    }
+  }
+  if (!isRecord(value)) throw new KeepBackupParseError("KeepKit backup must be an object.");
+  if (value.format !== KEEP_BACKUP_FORMAT || value.version !== KEEP_BACKUP_VERSION) {
+    throw new KeepBackupParseError("KeepKit backup format or version is unsupported.");
+  }
+  if (typeof value.exportedAt !== "number" || !Number.isFinite(value.exportedAt)) {
+    throw new KeepBackupParseError("KeepKit backup has an invalid export timestamp.");
+  }
+  if (!Array.isArray(value.items) || !value.items.every(isKeepItem)) {
+    throw new KeepBackupParseError("KeepKit backup contains invalid items.");
+  }
+  return value;
+}
+function isKeepItem(value) {
+  if (!isRecord(value)) return false;
+  return typeof value.id === "string" && typeof value.savedAt === "number" && Number.isFinite(value.savedAt) && typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt) && "meta" in value && (value.targetType === void 0 || typeof value.targetType === "string") && (value.note === void 0 || typeof value.note === "string") && (value.schemaVersion === void 0 || typeof value.schemaVersion === "number" && Number.isFinite(value.schemaVersion)) && (value.revision === void 0 || typeof value.revision === "string") && (value.tags === void 0 || Array.isArray(value.tags) && value.tags.every((tag) => typeof tag === "string"));
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// src/integrations.ts
+function createKeepInvalidationPlugin(options) {
+  return {
+    name: options.name ?? "keepkit-cache-invalidation",
+    after: async (context) => {
+      const keys = typeof options.queryKeys === "function" ? options.queryKeys(context) : [options.queryKeys];
+      await Promise.all(keys.map((queryKey) => options.invalidate(queryKey, context)));
+    }
+  };
+}
+export {
+  DEFAULT_INDEXEDDB_DATABASE,
+  DEFAULT_INDEXEDDB_STORE,
+  DEFAULT_STORAGE_KEY,
+  DEFAULT_SYNC_QUEUE_DATABASE,
+  DEFAULT_SYNC_QUEUE_KEY,
+  DEFAULT_SYNC_QUEUE_STORE,
+  FallbackStorageAdapter,
+  FallbackSyncQueueAdapter,
+  IndexedDBAdapter,
+  IndexedDBSyncQueueAdapter,
+  KEEP_BACKUP_FORMAT,
+  KEEP_BACKUP_VERSION,
+  KeepBackupImportError,
+  KeepBackupParseError,
+  KeepSchemaValidationError,
+  KeepStorageAccessError,
+  KeepStorageError,
+  KeepStorageParseError,
+  KeepStorageQuotaError,
+  KeepStore,
+  LocalStorageAdapter,
+  LocalStorageSyncQueueAdapter,
+  SyncStorageAdapter,
+  createBrowserStorageAdapter,
+  createKeepInvalidationPlugin,
+  createStorageAdapter,
+  exportItems,
+  getTagCounts,
+  importItems,
+  mergeKeepItems,
+  migrateKeepItems,
+  normalizeKeepTags,
+  parseKeepMeta,
+  queryKeepItems,
+  validateKeepItem
+};
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/migration.ts","../src/backup.ts","../src/integrations.ts"],"sourcesContent":["import type { KeepItem, StorageAdapter } from \"./types\";\n\n/** Merge anonymous local items into a signed-in or remote adapter. */\nexport async function mergeKeepItems<TMeta>(\n  localItems: KeepItem<TMeta>[],\n  target: StorageAdapter<TMeta>,\n): Promise<KeepItem<TMeta>[]> {\n  if (target.merge) return target.merge(localItems);\n\n  const remoteItems = await target.getAll();\n  const byId = new Map(remoteItems.map((item) => [item.id, item]));\n  for (const localItem of localItems) {\n    const remoteItem = byId.get(localItem.id);\n    if (!remoteItem || localItem.updatedAt > remoteItem.updatedAt) {\n      byId.set(localItem.id, localItem);\n    }\n  }\n\n  const merged = [...byId.values()].sort((a, b) => b.updatedAt - a.updatedAt);\n  await Promise.all(merged.map((item) => target.set(item)));\n  return merged;\n}\n\n/** Read anonymous items, merge them into the target, then clear the source. */\nexport async function migrateKeepItems<TMeta>(\n  source: StorageAdapter<TMeta>,\n  target: StorageAdapter<TMeta>,\n): Promise<KeepItem<TMeta>[]> {\n  const localItems = await source.getAll();\n  const merged = await mergeKeepItems(localItems, target);\n  await source.clear();\n  return merged;\n}\n","import { mergeKeepItems } from \"./migration\";\nimport { validateKeepItem } from \"./schema\";\nimport type { KeepInvalidItemPolicy, KeepItem, KeepSchema, StorageAdapter } from \"./types\";\n\nexport const KEEP_BACKUP_FORMAT = \"keepkit\";\nexport const KEEP_BACKUP_VERSION = 1;\n\nexport type KeepBackup<TMeta = Record<string, unknown>> = {\n  format: typeof KEEP_BACKUP_FORMAT;\n  version: typeof KEEP_BACKUP_VERSION;\n  exportedAt: number;\n  items: KeepItem<TMeta>[];\n};\n\nexport type ImportItemsOptions<TMeta = unknown> = {\n  mode?: \"replace\" | \"merge\";\n  schema?: KeepSchema<TMeta>;\n  invalidItemPolicy?: KeepInvalidItemPolicy;\n  onInvalidItem?: (error: unknown, item: KeepItem<unknown>) => void;\n};\n\nexport type ImportItemsResult<TMeta = Record<string, unknown>> = {\n  mode: \"replace\" | \"merge\";\n  imported: number;\n  failed: number;\n  total: number;\n  items: KeepItem<TMeta>[];\n};\n\nexport class KeepBackupParseError extends Error {\n  readonly cause?: unknown;\n\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message);\n    this.name = \"KeepBackupParseError\";\n    if (options?.cause !== undefined) this.cause = options.cause;\n  }\n}\n\nexport class KeepBackupImportError extends Error {\n  readonly mode: \"replace\" | \"merge\";\n  readonly imported: number;\n  readonly failed: number;\n  readonly cause?: unknown;\n\n  constructor(\n    message: string,\n    options: {\n      mode: \"replace\" | \"merge\";\n      imported: number;\n      failed: number;\n      cause?: unknown;\n    },\n  ) {\n    super(message);\n    this.name = \"KeepBackupImportError\";\n    this.mode = options.mode;\n    this.imported = options.imported;\n    this.failed = options.failed;\n    if (options.cause !== undefined) this.cause = options.cause;\n  }\n}\n\n/** Serialize all adapter data into a versioned JSON backup. */\nexport async function exportItems<TMeta>(adapter: StorageAdapter<TMeta>): Promise<string> {\n  const backup: KeepBackup<TMeta> = {\n    format: KEEP_BACKUP_FORMAT,\n    version: KEEP_BACKUP_VERSION,\n    exportedAt: Date.now(),\n    items: await adapter.getAll(),\n  };\n  return JSON.stringify(backup, null, 2);\n}\n\n/** Validate and restore a backup, either replacing or merging existing data. */\nexport async function importItems<TMeta>(\n  adapter: StorageAdapter<TMeta>,\n  data: string | KeepBackup<TMeta>,\n  options: ImportItemsOptions<TMeta> = {},\n): Promise<ImportItemsResult<TMeta>> {\n  const backup = parseBackup<TMeta>(data);\n  const mode = options.mode ?? \"merge\";\n  const validItems: KeepItem<TMeta>[] = [];\n  let failed = 0;\n  for (const item of backup.items) {\n    if (!options.schema) {\n      validItems.push(item);\n      continue;\n    }\n    try {\n      validItems.push(await validateKeepItem(item, options.schema));\n    } catch (cause) {\n      options.onInvalidItem?.(cause, item);\n      if ((options.invalidItemPolicy ?? \"error\") === \"drop\") {\n        failed += 1;\n        continue;\n      }\n      throw cause;\n    }\n  }\n  let items: KeepItem<TMeta>[];\n\n  if (mode === \"merge\") {\n    try {\n      items = await mergeKeepItems(validItems, adapter);\n    } catch (cause) {\n      throw new KeepBackupImportError(\"KeepKit could not merge the backup.\", {\n        mode,\n        imported: 0,\n        failed: validItems.length + failed,\n        cause,\n      });\n    }\n  } else {\n    let imported = 0;\n    try {\n      await adapter.clear();\n      for (const item of validItems) {\n        await adapter.set(item);\n        imported += 1;\n      }\n      items = await adapter.getAll();\n    } catch (cause) {\n      throw new KeepBackupImportError(\"KeepKit could not replace the stored items.\", {\n        mode,\n        imported,\n        failed: validItems.length + failed - imported,\n        cause,\n      });\n    }\n  }\n\n  return { mode, imported: validItems.length, failed, total: items.length, items };\n}\n\nfunction parseBackup<TMeta>(data: string | KeepBackup<TMeta>): KeepBackup<TMeta> {\n  let value: unknown = data;\n  if (typeof data === \"string\") {\n    try {\n      value = JSON.parse(data);\n    } catch (cause) {\n      throw new KeepBackupParseError(\"KeepKit backup is not valid JSON.\", { cause });\n    }\n  }\n\n  if (!isRecord(value)) throw new KeepBackupParseError(\"KeepKit backup must be an object.\");\n  if (value.format !== KEEP_BACKUP_FORMAT || value.version !== KEEP_BACKUP_VERSION) {\n    throw new KeepBackupParseError(\"KeepKit backup format or version is unsupported.\");\n  }\n  if (typeof value.exportedAt !== \"number\" || !Number.isFinite(value.exportedAt)) {\n    throw new KeepBackupParseError(\"KeepKit backup has an invalid export timestamp.\");\n  }\n  if (!Array.isArray(value.items) || !value.items.every(isKeepItem)) {\n    throw new KeepBackupParseError(\"KeepKit backup contains invalid items.\");\n  }\n  return value as KeepBackup<TMeta>;\n}\n\nfunction isKeepItem(value: unknown): value is KeepItem {\n  if (!isRecord(value)) return false;\n  return (\n    typeof value.id === \"string\" &&\n    typeof value.savedAt === \"number\" &&\n    Number.isFinite(value.savedAt) &&\n    typeof value.updatedAt === \"number\" &&\n    Number.isFinite(value.updatedAt) &&\n    \"meta\" in value &&\n    (value.targetType === undefined || typeof value.targetType === \"string\") &&\n    (value.note === undefined || typeof value.note === \"string\") &&\n    (value.schemaVersion === undefined ||\n      (typeof value.schemaVersion === \"number\" && Number.isFinite(value.schemaVersion))) &&\n    (value.revision === undefined || typeof value.revision === \"string\") &&\n    (value.tags === undefined || (Array.isArray(value.tags) && value.tags.every((tag) => typeof tag === \"string\")))\n  );\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n","import type { KeepPlugin, KeepPluginContext } from \"./types\";\n\nexport type KeepInvalidationPluginOptions<TMeta = Record<string, unknown>> = {\n  /** Query keys to invalidate after a successful local KeepKit mutation. */\n  queryKeys: readonly unknown[] | ((context: KeepPluginContext<TMeta>) => readonly (readonly unknown[])[]);\n  /** Connect this callback to queryClient.invalidateQueries or SWR mutate. */\n  invalidate: (queryKey: readonly unknown[], context: KeepPluginContext<TMeta>) => void | Promise<void>;\n  name?: string;\n};\n\n/** Framework-neutral bridge for TanStack Query, SWR, and similar caches. */\nexport function createKeepInvalidationPlugin<TMeta = Record<string, unknown>>(\n  options: KeepInvalidationPluginOptions<TMeta>,\n): KeepPlugin<TMeta> {\n  return {\n    name: options.name ?? \"keepkit-cache-invalidation\",\n    after: async (context) => {\n      const keys = typeof options.queryKeys === \"function\" ? options.queryKeys(context) : [options.queryKeys];\n      await Promise.all(keys.map((queryKey) => options.invalidate(queryKey, context)));\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/react.d.ts

@@ -0,0 +1,151 @@
+import * as react from 'react';
+import { ReactNode, ButtonHTMLAttributes, MouseEvent, HTMLAttributes, ReactElement, PropsWithChildren, ComponentType } from 'react';
+import { m as KeepItemInput, a as KeepItem, l as KeepEventHandlers, S as StorageAdapter, d as KeepPlugin, K as KeepSchema, b as KeepInvalidItemPolicy, t as KeepSyncState } from './types-DtILwEQ0.js';
+import { K as KeepListOptions, a as KeepStore, b as KeepStoreActions } from './store-BAvx_Iaw.js';
+
+type UseKeepItemResult<TMeta = Record<string, unknown>> = {
+    item: KeepItem<TMeta> | undefined;
+    isSaved: boolean;
+    isLoading: boolean;
+    isMutating: boolean;
+    error: unknown | null;
+    save: () => Promise<void>;
+    remove: () => Promise<void>;
+    toggle: () => Promise<void>;
+    updateNote: (note?: string) => Promise<void>;
+    updateTags: (tags?: string[]) => Promise<void>;
+};
+declare function useKeepItem<TMeta = Record<string, unknown>>(id: string, itemPayload?: KeepItemInput<TMeta>): UseKeepItemResult<TMeta>;
+
+type UseKeepListResult<TMeta = Record<string, unknown>> = {
+    items: KeepItem<TMeta>[];
+    totalCount: number;
+    tags: string[];
+    tagCounts: Record<string, number>;
+    isLoading: boolean;
+    isHydrated: boolean;
+    isMutating: boolean;
+    error: unknown | null;
+    remove: (id: string) => Promise<void>;
+    removeBatch: (ids: string[]) => Promise<void>;
+    updateTagsBatch: (ids: string[], tags?: string[]) => Promise<void>;
+    addTagsBatch: (ids: string[], tags: string[]) => Promise<void>;
+    removeTagsBatch: (ids: string[], tags: string[]) => Promise<void>;
+    clear: () => Promise<void>;
+    refresh: () => Promise<void>;
+};
+declare function useKeepList<TMeta = Record<string, unknown>>(options?: KeepListOptions<TMeta>): UseKeepListResult<TMeta>;
+
+type KeepShortcutModifier = "meta" | "ctrl" | "alt" | "shift";
+type KeepShortcutOptions<TMeta = Record<string, unknown>> = {
+    key: string;
+    modifier?: KeepShortcutModifier;
+    id?: string;
+    itemPayload?: KeepItemInput<TMeta>;
+    action?: "toggle" | "save" | "remove";
+    enabled?: boolean;
+    preventDefault?: boolean;
+    allowInEditable?: boolean;
+    onTrigger?: (event: KeyboardEvent) => void | Promise<void>;
+    onError?: (error: unknown) => void;
+};
+/** Bind a keyboard shortcut to a Keep action or an arbitrary command. */
+declare function useKeepShortcut<TMeta = Record<string, unknown>>(options: KeepShortcutOptions<TMeta>): void;
+
+type KeepButtonItem<TMeta = Record<string, unknown>> = KeepItemInput<TMeta> & {
+    id: string;
+};
+type KeepButtonSharedProps<TMeta> = {
+    item: KeepButtonItem<TMeta>;
+    children?: ReactNode | ((state: KeepButtonState<TMeta>) => ReactNode);
+    savedLabel?: ReactNode;
+    unsavedLabel?: ReactNode;
+    disabled?: boolean;
+    onToggleError?: (error: unknown) => void;
+};
+type KeepButtonProps<TMeta = Record<string, unknown>> = KeepButtonSharedProps<TMeta> & ((Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "onClick" | "aria-pressed"> & {
+    asChild?: false;
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+}) | (Omit<HTMLAttributes<HTMLElement>, "children" | "onClick" | "aria-pressed"> & {
+    asChild: true;
+    children: ReactElement | ((state: KeepButtonState<TMeta>) => ReactElement);
+    onClick?: (event: MouseEvent<HTMLElement>) => void;
+}));
+type KeepButtonState<TMeta = Record<string, unknown>> = {
+    item: ReturnType<typeof useKeepItem<TMeta>>["item"];
+    isSaved: boolean;
+    isLoading: boolean;
+    isMutating: boolean;
+    error: unknown | null;
+    save: () => Promise<void>;
+    remove: () => Promise<void>;
+    toggle: () => Promise<void>;
+    updateNote: (note?: string) => Promise<void>;
+    updateTags: (tags?: string[]) => Promise<void>;
+};
+/** A style-free accessible save toggle. Consumers provide all visual styling. */
+declare function KeepButton<TMeta = Record<string, unknown>>({ item, children, savedLabel, unsavedLabel, asChild, onToggleError, onClick, disabled, ...buttonProps }: KeepButtonProps<TMeta>): react.JSX.Element;
+
+type KeepContextValue<TMeta = Record<string, unknown>> = {
+    items: KeepItem<TMeta>[];
+    isLoading: boolean;
+    isHydrated: boolean;
+    isMutating: boolean;
+    error: unknown | null;
+    syncState: KeepSyncState;
+    saveItem: (item: KeepItem<TMeta>) => Promise<void>;
+    updateNote: (id: string, note?: string) => Promise<void>;
+    updateTags: (id: string, tags?: string[]) => Promise<void>;
+    updateTagsBatch: (ids: string[], tags?: string[]) => Promise<void>;
+    addTagsBatch: (ids: string[], tags: string[]) => Promise<void>;
+    removeTagsBatch: (ids: string[], tags: string[]) => Promise<void>;
+    removeItem: (id: string) => Promise<void>;
+    removeItems: (ids: string[]) => Promise<void>;
+    clear: () => Promise<void>;
+    refresh: () => Promise<void>;
+    flushSync: () => Promise<void>;
+};
+type KeepProviderProps<TMeta = Record<string, unknown>> = PropsWithChildren<KeepEventHandlers<TMeta> & {
+    storage?: StorageAdapter<TMeta>;
+    /**
+     * Optional server-provided snapshot rendered before the client adapter
+     * finishes hydrating. The adapter remains the source of truth after the
+     * first refresh.
+     */
+    initialItems?: KeepItem<TMeta>[];
+    plugins?: KeepPlugin<TMeta>[];
+    schemaVersion?: number;
+    schema?: KeepSchema<TMeta>;
+    invalidItemPolicy?: KeepInvalidItemPolicy;
+    onInvalidItem?: (error: unknown, item: KeepItem<unknown>) => void;
+    migrateMeta?: (meta: unknown, fromVersion: number, toVersion: number, item: KeepItem<TMeta>) => TMeta | Promise<TMeta>;
+}>;
+type KeepStoreAccess<TMeta> = {
+    store: KeepStore<TMeta>;
+    actions: KeepStoreActions<TMeta>;
+};
+declare function KeepProvider<TMeta = Record<string, unknown>>({ storage, initialItems, onSave, onRemove, onNoteUpdate, onTagsUpdate, onChange, onError, plugins, schemaVersion, schema, invalidItemPolicy, onInvalidItem, migrateMeta, children, }: KeepProviderProps<TMeta>): react.JSX.Element;
+declare function useKeepContext<TMeta = Record<string, unknown>>(): KeepContextValue<TMeta>;
+declare function useKeepStore<TMeta = Record<string, unknown>>(): KeepStoreAccess<TMeta>;
+
+type CreateKeepKitOptions<TMeta = Record<string, unknown>> = {
+    initialItems?: KeepProviderProps<TMeta>["initialItems"];
+    plugins?: KeepPlugin<TMeta>[];
+    schemaVersion?: number;
+    schema?: KeepSchema<TMeta>;
+    invalidItemPolicy?: KeepInvalidItemPolicy;
+    onInvalidItem?: KeepProviderProps<TMeta>["onInvalidItem"];
+    migrateMeta?: KeepProviderProps<TMeta>["migrateMeta"];
+};
+type KeepKit<TMeta> = {
+    KeepProvider: ComponentType<KeepProviderProps<TMeta>>;
+    KeepButton: ComponentType<KeepButtonProps<TMeta>>;
+    useKeepContext: () => ReturnType<typeof useKeepContext<TMeta>>;
+    useKeepItem: (id: string, itemPayload?: KeepItemInput<TMeta>) => UseKeepItemResult<TMeta>;
+    useKeepList: (options?: KeepListOptions<TMeta>) => UseKeepListResult<TMeta>;
+    useKeepShortcut: (options: KeepShortcutOptions<TMeta>) => void;
+};
+/** Create an app-specific, fully typed set of KeepKit components and hooks. */
+declare function createKeepKit<TMeta = Record<string, unknown>>(options?: CreateKeepKitOptions<TMeta>): KeepKit<TMeta>;
+
+export { type CreateKeepKitOptions, KeepButton, type KeepButtonItem, type KeepButtonProps, type KeepButtonState, type KeepContextValue, type KeepKit, KeepListOptions, KeepProvider, type KeepProviderProps, type KeepShortcutModifier, type KeepShortcutOptions, type UseKeepItemResult, type UseKeepListResult, createKeepKit, useKeepContext, useKeepItem, useKeepList, useKeepShortcut, useKeepStore };