@keepkit/core 0.1.0

package/dist/index.js

@@ -0,0 +1,1093 @@
+import {
+  DEFAULT_INDEXEDDB_DATABASE,
+  DEFAULT_INDEXEDDB_STORE,
+  DEFAULT_STORAGE_KEY,
+  DEFAULT_SYNC_QUEUE_DATABASE,
+  DEFAULT_SYNC_QUEUE_KEY,
+  DEFAULT_SYNC_QUEUE_STORE,
+  IndexedDBAdapter,
+  IndexedDBSyncQueueAdapter,
+  KeepStorageAccessError,
+  KeepStorageError,
+  KeepStorageParseError,
+  KeepStorageQuotaError,
+  LocalStorageAdapter,
+  LocalStorageSyncQueueAdapter,
+  SyncStorageAdapter,
+  createStorageAdapter,
+  normalizeKeepTags
+} from "./chunk-H4A322SZ.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/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) };
+}
+
+// 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/hooks/useKeepItem.ts
+import { useCallback as useCallback3 } from "react";
+
+// src/KeepProvider.tsx
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore
+} from "react";
+
+// src/store.ts
+var KeepStore = class {
+  constructor(initialState) {
+    this.listeners = /* @__PURE__ */ new Set();
+    this.getSnapshot = () => this.state;
+    this.subscribe = (listener) => {
+      this.listeners.add(listener);
+      return () => this.listeners.delete(listener);
+    };
+    this.state = initialState;
+  }
+  setState(next) {
+    let changed = false;
+    for (const key of Object.keys(next)) {
+      if (!Object.is(this.state[key], next[key])) {
+        changed = true;
+        break;
+      }
+    }
+    if (!changed) return;
+    this.state = { ...this.state, ...next };
+    for (const listener of this.listeners) listener();
+  }
+};
+
+// src/KeepProvider.tsx
+import { jsx } from "react/jsx-runtime";
+var defaultStorage = new LocalStorageAdapter();
+var KeepContext = createContext(null);
+var KeepStoreContext = createContext(null);
+function KeepProvider({
+  storage = defaultStorage,
+  onSave,
+  onRemove,
+  onNoteUpdate,
+  onTagsUpdate,
+  onChange,
+  onError,
+  plugins = [],
+  schemaVersion,
+  schema,
+  invalidItemPolicy = "error",
+  onInvalidItem,
+  migrateMeta,
+  children
+}) {
+  const storeRef = useRef(null);
+  if (!storeRef.current) {
+    storeRef.current = new KeepStore({
+      items: [],
+      isLoading: true,
+      isHydrated: false,
+      isMutating: false,
+      error: null
+    });
+  }
+  const store = storeRef.current;
+  const state = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+  const { items, isLoading, isHydrated, isMutating, error } = state;
+  const itemsRef = useRef(items);
+  const pluginsRef = useRef(plugins);
+  pluginsRef.current = plugins;
+  const handlersRef = useRef({ onSave, onRemove, onNoteUpdate, onTagsUpdate, onChange, onError });
+  handlersRef.current = { onSave, onRemove, onNoteUpdate, onTagsUpdate, onChange, onError };
+  const migrationRef = useRef({
+    schemaVersion,
+    migrateMeta,
+    schema,
+    invalidItemPolicy,
+    onInvalidItem
+  });
+  migrationRef.current = { schemaVersion, migrateMeta, schema, invalidItemPolicy, onInvalidItem };
+  const operationTailRef = useRef(Promise.resolve());
+  const pendingRefreshesRef = useRef(0);
+  const pendingMutationsRef = useRef(0);
+  const syncStorage = isSyncCapableStorage(storage) ? storage : void 0;
+  const getSyncState = useCallback(
+    () => syncStorage?.getSyncState() ?? IDLE_SYNC_STATE,
+    [syncStorage]
+  );
+  const subscribeSync = useCallback(
+    (listener) => syncStorage?.subscribeSync(listener) ?? (() => void 0),
+    [syncStorage]
+  );
+  const syncState = useSyncExternalStore(subscribeSync, getSyncState, getSyncState);
+  const reportError = useCallback(
+    (cause, context) => {
+      store.setState({ error: cause });
+      handlersRef.current.onError?.(cause, context);
+      for (const plugin of pluginsRef.current) plugin.onError?.(cause, context);
+    },
+    [store]
+  );
+  const setItems = useCallback(
+    (next) => {
+      itemsRef.current = next;
+      store.setState({ items: next });
+    },
+    [store]
+  );
+  const runBeforePlugins = useCallback(
+    async (context) => {
+      for (const plugin of pluginsRef.current) await plugin.before?.(context);
+      return context;
+    },
+    []
+  );
+  const runAfterPlugins = useCallback(
+    async (context) => {
+      for (const plugin of pluginsRef.current) await plugin.after?.(context);
+    },
+    []
+  );
+  const enqueueOperation = useCallback((operation) => {
+    const run = operationTailRef.current.then(operation, operation);
+    operationTailRef.current = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }, []);
+  const refresh = useCallback(async () => {
+    pendingRefreshesRef.current += 1;
+    store.setState({ isLoading: true });
+    try {
+      await enqueueOperation(async () => {
+        try {
+          let next = await storage.getAll();
+          let needsMigrationPersist = false;
+          if (migrationRef.current.schemaVersion !== void 0) {
+            const migrated = await Promise.all(
+              next.map(async (item) => {
+                const currentSchemaVersion = migrationRef.current.schemaVersion;
+                if (item.schemaVersion === currentSchemaVersion) return item;
+                const meta = migrationRef.current.migrateMeta ? await migrationRef.current.migrateMeta(
+                  item.meta,
+                  item.schemaVersion ?? 0,
+                  currentSchemaVersion,
+                  item
+                ) : item.meta;
+                return { ...item, meta, schemaVersion: currentSchemaVersion };
+              })
+            );
+            if (migrated.some((item, index) => item !== next[index])) {
+              next = migrated;
+              needsMigrationPersist = true;
+            }
+          }
+          if (migrationRef.current.schema) {
+            const validated = [];
+            for (const item of next) {
+              try {
+                validated.push(await parseKeepMetaItem(item, migrationRef.current.schema));
+              } catch (cause) {
+                migrationRef.current.onInvalidItem?.(cause, item);
+                if (migrationRef.current.invalidItemPolicy === "drop") continue;
+                throw cause;
+              }
+            }
+            next = validated;
+          }
+          if (needsMigrationPersist) {
+            if (storage.setMany) await storage.setMany(next);
+            else for (const item of next) await storage.set(item);
+          }
+          setItems(next);
+          store.setState({ error: null });
+        } catch (cause) {
+          reportError(cause, { action: "refresh" });
+        }
+      });
+    } finally {
+      pendingRefreshesRef.current -= 1;
+      if (pendingRefreshesRef.current === 0) store.setState({ isLoading: false });
+      store.setState({ isHydrated: true });
+    }
+  }, [enqueueOperation, reportError, setItems, storage, store]);
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+  useEffect(() => {
+    if (!storage.subscribe) return;
+    return storage.subscribe(() => void refresh());
+  }, [refresh, storage]);
+  const runMutation = useCallback(
+    (action, id, createPlan) => {
+      pendingMutationsRef.current += 1;
+      store.setState({ isMutating: true });
+      const run = enqueueOperation(async () => {
+        const previous = itemsRef.current;
+        const plan = createPlan(previous);
+        if (!plan) return;
+        try {
+          if (plan.pluginContext) await runBeforePlugins(plan.pluginContext);
+          setItems(plan.next);
+          store.setState({ error: null });
+          await plan.persist();
+          plan.onSuccess?.();
+          if (plan.pluginContext) await runAfterPlugins(plan.pluginContext);
+          if (plan.pluginContext) {
+            const change = { ...plan.pluginContext, phase: "local" };
+            void Promise.resolve(handlersRef.current.onChange?.(change)).catch(
+              (cause) => reportError(cause, { action, id })
+            );
+          }
+        } catch (cause) {
+          setItems(previous);
+          reportError(cause, { action, id });
+          throw cause;
+        }
+      });
+      return run.finally(() => {
+        pendingMutationsRef.current -= 1;
+        if (pendingMutationsRef.current === 0) store.setState({ isMutating: false });
+      });
+    },
+    [enqueueOperation, reportError, runAfterPlugins, runBeforePlugins, setItems, store]
+  );
+  const saveItem = useCallback(
+    async (item) => {
+      let normalizedItem;
+      try {
+        const meta = migrationRef.current.schema ? await parseKeepMeta(migrationRef.current.schema, item.meta) : item.meta;
+        normalizedItem = {
+          ...item,
+          meta,
+          tags: normalizeKeepTags(item.tags),
+          ...migrationRef.current.schemaVersion === void 0 ? {} : { schemaVersion: migrationRef.current.schemaVersion }
+        };
+      } catch (cause) {
+        reportError(cause, { action: "save", id: item.id });
+        throw cause;
+      }
+      await runMutation("save", normalizedItem.id, (previous) => ({
+        next: [
+          ...previous.filter((current) => current.id !== normalizedItem.id),
+          normalizedItem
+        ].sort((a, b) => b.updatedAt - a.updatedAt),
+        persist: () => storage.set(normalizedItem),
+        onSuccess: () => handlersRef.current.onSave?.(normalizedItem),
+        pluginContext: { action: "save", id: normalizedItem.id, item: normalizedItem }
+      }));
+    },
+    [reportError, runMutation, storage]
+  );
+  const updateNote = useCallback(
+    async (id, note) => {
+      const nextNote = note?.trim() || void 0;
+      await runMutation("updateNote", id, (previous) => {
+        const current = previous.find((item) => item.id === id);
+        if (!current) return void 0;
+        const next = { ...current, note: nextNote, updatedAt: Date.now() };
+        return {
+          next: previous.map((item) => item.id === id ? next : item),
+          persist: () => storage.set(next),
+          onSuccess: () => handlersRef.current.onNoteUpdate?.(id, nextNote),
+          pluginContext: { action: "updateNote", id, item: next }
+        };
+      });
+    },
+    [runMutation, storage]
+  );
+  const updateTags = useCallback(
+    async (id, tags) => {
+      const nextTags = normalizeKeepTags(tags);
+      await runMutation("updateTags", id, (previous) => {
+        const current = previous.find((item) => item.id === id);
+        if (!current) return void 0;
+        const next = { ...current, tags: nextTags, updatedAt: Date.now() };
+        return {
+          next: previous.map((item) => item.id === id ? next : item),
+          persist: () => storage.set(next),
+          onSuccess: () => handlersRef.current.onTagsUpdate?.(id, nextTags),
+          pluginContext: { action: "updateTags", id, item: next }
+        };
+      });
+    },
+    [runMutation, storage]
+  );
+  const updateTagsBatch = useCallback(
+    async (ids, tags) => {
+      const idSet = new Set(ids);
+      const nextTags = normalizeKeepTags(tags);
+      await runMutation("updateTagsBatch", void 0, (previous) => {
+        const currentItems = previous.filter((item) => idSet.has(item.id));
+        if (currentItems.length === 0) return void 0;
+        const updatedItems = currentItems.map((item) => ({
+          ...item,
+          tags: nextTags,
+          updatedAt: Date.now()
+        }));
+        const updatedById = new Map(updatedItems.map((item) => [item.id, item]));
+        return {
+          next: previous.map((item) => updatedById.get(item.id) ?? item),
+          persist: async () => {
+            if (storage.setMany) {
+              await storage.setMany(updatedItems);
+              return;
+            }
+            const completed = [];
+            try {
+              for (const item of updatedItems) {
+                await storage.set(item);
+                completed.push(item);
+              }
+            } catch (cause) {
+              const previousById = new Map(currentItems.map((item) => [item.id, item]));
+              await Promise.allSettled(
+                completed.map((item) => {
+                  const previousItem = previousById.get(item.id);
+                  return previousItem ? storage.set(previousItem) : Promise.resolve();
+                })
+              );
+              throw cause;
+            }
+          },
+          onSuccess: () => {
+            updatedItems.forEach((item) => {
+              handlersRef.current.onTagsUpdate?.(item.id, nextTags);
+            });
+          },
+          pluginContext: { action: "updateTagsBatch", items: updatedItems }
+        };
+      });
+    },
+    [runMutation, storage]
+  );
+  const addTagsBatch = useCallback(
+    async (ids, tags) => {
+      const additions = normalizeKeepTags(tags) ?? [];
+      const idSet = new Set(ids);
+      const currentItems = itemsRef.current.filter((item) => idSet.has(item.id));
+      await Promise.all(
+        currentItems.map(
+          (item) => updateTags(item.id, normalizeKeepTags([...item.tags ?? [], ...additions]))
+        )
+      );
+    },
+    [updateTags]
+  );
+  const removeTagsBatch = useCallback(
+    async (ids, tags) => {
+      const removals = new Set(normalizeKeepTags(tags) ?? []);
+      const idSet = new Set(ids);
+      const currentItems = itemsRef.current.filter((item) => idSet.has(item.id));
+      await Promise.all(
+        currentItems.map(
+          (item) => updateTags(
+            item.id,
+            normalizeKeepTags((item.tags ?? []).filter((tag) => !removals.has(tag)))
+          )
+        )
+      );
+    },
+    [updateTags]
+  );
+  const removeItem = useCallback(
+    async (id) => {
+      await runMutation("remove", id, (previous) => {
+        const current = previous.find((item) => item.id === id);
+        if (!current) return void 0;
+        return {
+          next: previous.filter((item) => item.id !== id),
+          persist: () => storage.remove(id),
+          onSuccess: () => handlersRef.current.onRemove?.(current),
+          pluginContext: { action: "remove", id, item: current }
+        };
+      });
+    },
+    [runMutation, storage]
+  );
+  const removeItems = useCallback(
+    async (ids) => {
+      const idSet = new Set(ids);
+      await runMutation("removeBatch", void 0, (previous) => {
+        const removedItems = previous.filter((item) => idSet.has(item.id));
+        if (removedItems.length === 0) return void 0;
+        return {
+          next: previous.filter((item) => !idSet.has(item.id)),
+          persist: async () => {
+            if (storage.removeMany) {
+              await storage.removeMany(removedItems.map((item) => item.id));
+              return;
+            }
+            const completed = [];
+            try {
+              for (const item of removedItems) {
+                await storage.remove(item.id);
+                completed.push(item);
+              }
+            } catch (cause) {
+              await Promise.allSettled(completed.map((item) => storage.set(item)));
+              throw cause;
+            }
+          },
+          onSuccess: () => {
+            removedItems.forEach((item) => {
+              handlersRef.current.onRemove?.(item);
+            });
+          },
+          pluginContext: { action: "removeBatch", items: removedItems }
+        };
+      });
+    },
+    [runMutation, storage]
+  );
+  const clear = useCallback(
+    () => runMutation("clear", void 0, (_previous) => ({
+      next: [],
+      persist: () => storage.clear(),
+      pluginContext: { action: "clear", items: [] }
+    })),
+    [runMutation, storage]
+  );
+  const flushSync = useCallback(
+    () => syncStorage ? syncStorage.flushSync() : Promise.resolve(),
+    [syncStorage]
+  );
+  const value = useMemo(
+    () => ({
+      items,
+      isLoading,
+      isHydrated,
+      isMutating,
+      error,
+      syncState,
+      saveItem,
+      updateNote,
+      updateTags,
+      updateTagsBatch,
+      addTagsBatch,
+      removeTagsBatch,
+      removeItem,
+      removeItems,
+      clear,
+      refresh,
+      flushSync
+    }),
+    [
+      clear,
+      error,
+      flushSync,
+      isHydrated,
+      isLoading,
+      isMutating,
+      items,
+      syncState,
+      refresh,
+      removeItem,
+      saveItem,
+      updateNote,
+      updateTags,
+      updateTagsBatch,
+      addTagsBatch,
+      removeTagsBatch,
+      removeItems
+    ]
+  );
+  const actions = useMemo(
+    () => ({
+      saveItem,
+      updateNote,
+      updateTags,
+      updateTagsBatch,
+      addTagsBatch,
+      removeTagsBatch,
+      removeItem,
+      removeItems,
+      clear,
+      refresh
+    }),
+    [
+      addTagsBatch,
+      clear,
+      refresh,
+      removeItem,
+      removeItems,
+      removeTagsBatch,
+      saveItem,
+      updateNote,
+      updateTags,
+      updateTagsBatch
+    ]
+  );
+  const storeAccess = useMemo(() => ({ store, actions }), [actions, store]);
+  return /* @__PURE__ */ jsx(KeepStoreContext.Provider, { value: storeAccess, children: /* @__PURE__ */ jsx(KeepContext.Provider, { value, children }) });
+}
+var IDLE_SYNC_STATE = Object.freeze({
+  status: "idle",
+  pendingCount: 0,
+  conflictIds: []
+});
+function isSyncCapableStorage(storage) {
+  return "getSyncState" in storage && typeof storage.getSyncState === "function" && "subscribeSync" in storage && typeof storage.subscribeSync === "function" && "flushSync" in storage && typeof storage.flushSync === "function";
+}
+async function parseKeepMetaItem(item, schema) {
+  return { ...item, meta: await parseKeepMeta(schema, item.meta) };
+}
+function useKeepContext() {
+  const context = useContext(KeepContext);
+  if (!context) throw new Error("Keep hooks must be used inside a KeepProvider");
+  return context;
+}
+function useKeepStore() {
+  const context = useContext(KeepStoreContext);
+  if (!context) throw new Error("Keep hooks must be used inside a KeepProvider");
+  return context;
+}
+
+// src/hooks/useKeepStoreSelector.ts
+import { useCallback as useCallback2, useRef as useRef2, useSyncExternalStore as useSyncExternalStore2 } from "react";
+function useKeepStoreSelector(store, selector) {
+  const cacheRef = useRef2(null);
+  const getSelectedSnapshot = useCallback2(() => {
+    const snapshot = store.getSnapshot();
+    const cached = cacheRef.current;
+    if (cached?.snapshot === snapshot && cached.selector === selector) return cached.selected;
+    const selected = selector(snapshot);
+    cacheRef.current = { snapshot, selector, selected };
+    return selected;
+  }, [selector, store]);
+  return useSyncExternalStore2(store.subscribe, getSelectedSnapshot, getSelectedSnapshot);
+}
+
+// src/hooks/useKeepItem.ts
+function useKeepItem(id, itemPayload) {
+  const { store, actions } = useKeepStore();
+  const item = useKeepStoreSelector(
+    store,
+    useCallback3((state) => state.items.find((current) => current.id === id), [id])
+  );
+  const isLoading = useKeepStoreSelector(
+    store,
+    useCallback3((state) => state.isLoading, [])
+  );
+  const isMutating = useKeepStoreSelector(
+    store,
+    useCallback3((state) => state.isMutating, [])
+  );
+  const error = useKeepStoreSelector(
+    store,
+    useCallback3((state) => state.error, [])
+  );
+  const save = useCallback3(async () => {
+    if (!itemPayload) {
+      throw new Error(`An itemPayload is required to save item "${id}".`);
+    }
+    const now = Date.now();
+    await actions.saveItem({
+      id,
+      ...itemPayload,
+      savedAt: item?.savedAt ?? now,
+      updatedAt: now
+    });
+  }, [actions, id, item?.savedAt, itemPayload]);
+  const remove = useCallback3(() => actions.removeItem(id), [actions, id]);
+  const toggle = useCallback3(() => item ? remove() : save(), [item, remove, save]);
+  const updateNote = useCallback3((note) => actions.updateNote(id, note), [actions, id]);
+  const updateTags = useCallback3((tags) => actions.updateTags(id, tags), [actions, id]);
+  return {
+    item,
+    isSaved: Boolean(item),
+    isLoading,
+    isMutating,
+    error,
+    save,
+    remove,
+    toggle,
+    updateNote,
+    updateTags
+  };
+}
+
+// src/hooks/useKeepList.ts
+import { useCallback as useCallback4, useMemo as useMemo2 } from "react";
+function useKeepList(options = {}) {
+  const { store, actions } = useKeepStore();
+  const {
+    filter,
+    filterFn,
+    limit,
+    offset,
+    order,
+    savedBetween,
+    search,
+    searchQuery,
+    sort,
+    sortBy,
+    tag,
+    tags: queryTags,
+    targetType
+  } = options;
+  const queryOptions = useMemo2(
+    () => ({
+      filter,
+      filterFn,
+      limit,
+      offset,
+      order,
+      savedBetween,
+      search,
+      searchQuery,
+      sort,
+      sortBy,
+      tag,
+      tags: queryTags,
+      targetType
+    }),
+    [
+      filter,
+      filterFn,
+      limit,
+      offset,
+      order,
+      savedBetween,
+      search,
+      searchQuery,
+      sort,
+      sortBy,
+      tag,
+      queryTags,
+      targetType
+    ]
+  );
+  const selector = useMemo2(() => {
+    let previousResult;
+    return (state) => {
+      const next = queryKeepItems(state.items, queryOptions);
+      if (previousResult && previousResult.totalCount === next.totalCount && sameItems(previousResult.items, next.items) && sameCounts(previousResult.tagCounts, next.tagCounts)) {
+        return previousResult;
+      }
+      previousResult = next;
+      return previousResult;
+    };
+  }, [queryOptions]);
+  const query = useKeepStoreSelector(store, selector);
+  const tagsSelector = useMemo2(() => {
+    let previous;
+    return (state) => {
+      const next = [...new Set(state.items.flatMap((item) => item.tags ?? []))].sort();
+      if (previous?.length === next.length && previous.every((tag2, index) => tag2 === next[index])) {
+        return previous;
+      }
+      previous = next;
+      return next;
+    };
+  }, []);
+  const items = query.items;
+  const totalCount = query.totalCount;
+  const tagCounts = query.tagCounts;
+  const tags = useKeepStoreSelector(store, tagsSelector);
+  const isLoading = useKeepStoreSelector(
+    store,
+    useCallback4((state) => state.isLoading, [])
+  );
+  const isHydrated = useKeepStoreSelector(
+    store,
+    useCallback4((state) => state.isHydrated, [])
+  );
+  const isMutating = useKeepStoreSelector(
+    store,
+    useCallback4((state) => state.isMutating, [])
+  );
+  const error = useKeepStoreSelector(
+    store,
+    useCallback4((state) => state.error, [])
+  );
+  const remove = useCallback4((id) => actions.removeItem(id), [actions]);
+  const removeBatch = useCallback4((ids) => actions.removeItems(ids), [actions]);
+  const updateTagsBatch = useCallback4(
+    (ids, tags2) => actions.updateTagsBatch(ids, tags2),
+    [actions]
+  );
+  const addTagsBatch = useCallback4(
+    (ids, tags2) => actions.addTagsBatch(ids, tags2),
+    [actions]
+  );
+  const removeTagsBatch = useCallback4(
+    (ids, tags2) => actions.removeTagsBatch(ids, tags2),
+    [actions]
+  );
+  return {
+    items,
+    totalCount,
+    tags,
+    tagCounts,
+    isLoading,
+    isHydrated,
+    isMutating,
+    error,
+    remove,
+    removeBatch,
+    updateTagsBatch,
+    addTagsBatch,
+    removeTagsBatch,
+    clear: actions.clear,
+    refresh: actions.refresh
+  };
+}
+function queryKeepItems(source, options = {}) {
+  const filtered = source.filter((item) => {
+    const [from, to] = options.savedBetween ?? [];
+    const savedAt = item.savedAt;
+    const lowerBound = from === void 0 ? void 0 : toTimestamp(from);
+    const upperBound = to === void 0 ? void 0 : toTimestamp(to);
+    return (options.targetType === void 0 || item.targetType === options.targetType) && (options.tag === void 0 || item.tags?.includes(options.tag) === true) && (options.tags === void 0 || options.tags.every((tag) => item.tags?.includes(tag))) && (lowerBound === void 0 || savedAt >= lowerBound) && (upperBound === void 0 || savedAt <= upperBound) && matchesSearch(item, options.searchQuery, options.search) && (options.filter?.(item) ?? true) && (options.filterFn?.(item) ?? true);
+  });
+  const tagCounts = getTagCounts(filtered);
+  const sortBy = options.sortBy ?? options.sort?.by;
+  const direction = (options.order ?? options.sort?.direction) === "asc" ? 1 : -1;
+  const sorted = sortBy ? [...filtered].sort((a, b) => (a[sortBy] - b[sortBy]) * direction) : filtered;
+  const offset = Math.max(0, options.offset ?? 0);
+  const items = options.limit === void 0 ? sorted.slice(offset) : sorted.slice(offset, offset + Math.max(0, options.limit));
+  return { items, totalCount: sorted.length, tagCounts };
+}
+function getTagCounts(items) {
+  const counts = {};
+  for (const item of items) {
+    for (const tag of item.tags ?? []) counts[tag] = (counts[tag] ?? 0) + 1;
+  }
+  return Object.fromEntries(Object.entries(counts).sort(([a], [b]) => a.localeCompare(b)));
+}
+function matchesSearch(item, searchQuery, search) {
+  const query = search?.query ?? searchQuery;
+  if (!query?.trim()) return true;
+  const fields = search?.fields ?? ["note", "meta", "tags"];
+  const values = fields.map((field) => {
+    if (field === "note") return item.note ?? "";
+    if (field === "tags") return (item.tags ?? []).join(" ");
+    try {
+      return JSON.stringify(item.meta) ?? "";
+    } catch {
+      return String(item.meta);
+    }
+  });
+  const text = values.join(" ").toLocaleLowerCase();
+  if (!search) return text.includes(query.trim().toLocaleLowerCase());
+  const normalized = query.trim().toLocaleLowerCase();
+  const needles = search.tokenize === false ? [normalized] : normalized.split(/\s+/).filter(Boolean);
+  const matches = needles.map((needle) => text.includes(needle));
+  return search.mode === "or" ? matches.some(Boolean) : matches.every(Boolean);
+}
+function toTimestamp(value) {
+  return value instanceof Date ? value.getTime() : value;
+}
+function sameItems(left, right) {
+  return left.length === right.length && left.every((item, index) => item === right[index]);
+}
+function sameCounts(left, right) {
+  const leftEntries = Object.entries(left);
+  const rightEntries = Object.entries(right);
+  return leftEntries.length === rightEntries.length && leftEntries.every(([key, value], index) => {
+    const [rightKey, rightValue] = rightEntries[index] ?? [];
+    return key === rightKey && value === rightValue;
+  });
+}
+
+// src/KeepButton.tsx
+import {
+  Children,
+  cloneElement,
+  isValidElement
+} from "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+function KeepButton({
+  item,
+  children,
+  savedLabel = "Saved",
+  unsavedLabel = "Save",
+  asChild = false,
+  onToggleError,
+  onClick,
+  disabled,
+  ...buttonProps
+}) {
+  const state = useKeepItem(item.id, {
+    meta: item.meta,
+    targetType: item.targetType,
+    note: item.note,
+    tags: item.tags
+  });
+  const { isSaved, toggle } = state;
+  const isDisabled = disabled ?? state.isMutating;
+  async function handleClick(event) {
+    if (asChild) {
+      onClick?.(event);
+    } else {
+      onClick?.(
+        event
+      );
+    }
+    if (event.defaultPrevented) return;
+    try {
+      await toggle();
+    } catch (error) {
+      onToggleError?.(error);
+    }
+  }
+  const content = typeof children === "function" ? children(state) : children ?? (isSaved ? savedLabel : unsavedLabel);
+  function handleElementClick(event) {
+    if (asChild && isValidElement(content)) {
+      content.props.onClick?.(event);
+    }
+    if (!event.defaultPrevented) void handleClick(event);
+  }
+  const commonProps = {
+    ...buttonProps,
+    "aria-pressed": isSaved,
+    "aria-label": ("aria-label" in buttonProps ? buttonProps["aria-label"] : void 0) ?? (isSaved ? "Remove saved item" : "Save item"),
+    disabled: isDisabled,
+    onClick: handleElementClick
+  };
+  if (asChild) {
+    const child = Children.only(content);
+    if (!isValidElement(child)) {
+      throw new Error("KeepButton with asChild requires a single React element child.");
+    }
+    return cloneElement(child, commonProps);
+  }
+  return /* @__PURE__ */ jsx2(
+    "button",
+    {
+      ...commonProps,
+      type: "type" in buttonProps ? buttonProps.type ?? "button" : "button",
+      children: content
+    }
+  );
+}
+
+// src/createKeepKit.tsx
+import { jsx as jsx3 } from "react/jsx-runtime";
+function createKeepKit(options = {}) {
+  return {
+    KeepProvider: (props) => /* @__PURE__ */ jsx3(KeepProvider, { ...options, ...props }),
+    KeepButton: (props) => /* @__PURE__ */ jsx3(KeepButton, { ...props }),
+    useKeepContext: () => useKeepContext(),
+    useKeepItem: (id, itemPayload) => useKeepItem(id, itemPayload),
+    useKeepList: (options2) => useKeepList(options2)
+  };
+}
+
+// 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,
+  IndexedDBAdapter,
+  IndexedDBSyncQueueAdapter,
+  KEEP_BACKUP_FORMAT,
+  KEEP_BACKUP_VERSION,
+  KeepBackupImportError,
+  KeepBackupParseError,
+  KeepButton,
+  KeepProvider,
+  KeepSchemaValidationError,
+  KeepStorageAccessError,
+  KeepStorageError,
+  KeepStorageParseError,
+  KeepStorageQuotaError,
+  LocalStorageAdapter,
+  LocalStorageSyncQueueAdapter,
+  SyncStorageAdapter,
+  createKeepInvalidationPlugin,
+  createKeepKit,
+  createStorageAdapter,
+  exportItems,
+  getTagCounts,
+  importItems,
+  mergeKeepItems,
+  migrateKeepItems,
+  normalizeKeepTags,
+  parseKeepMeta,
+  queryKeepItems,
+  useKeepContext,
+  useKeepItem,
+  useKeepList,
+  validateKeepItem
+};
+//# sourceMappingURL=index.js.map