gjendje 0.5.0 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 # gjendje
 
-Every app juggles `localStorage`, `sessionStorage`, URL params, and in-memory state — each with its own API. **gjendje** replaces it all with a single primitive. Choose where state lives. The rest is handled.
+Every app juggles localStorage, sessionStorage, URL params, and in-memory state — each with its own API. **gjendje** replaces it all with a single primitive. Choose where state lives. The rest is handled.
 
 ## Install
 
@@ -13,41 +13,40 @@ npm install gjendje
 ## Quick start
 
 ```ts
-import { state } from 'gjendje'
+import { local, session, url, bucket, server } from 'gjendje'
 
-// 1. Create state
-const counter = state('counter', 0)
+// localStorage — survives refresh, works across tabs
+const theme = local({ theme: 'light' })
 
-// 2. Read
-counter.get() // 0
+// sessionStorage — survives refresh, gone when tab closes
+const draft = session({ draft: '' })
 
-// 3. Write
-counter.set(1)
-counter.set((prev) => prev + 1)
+// URL params — shareable via address bar
+const filters = url({ q: '' })
 
-// 4. Subscribe
-counter.subscribe((value) => console.log(value))
+// Storage Bucket — isolated, quota-managed, expirable
+const cache = bucket({ cache: [] }, { bucket: { name: 'app-cache', expires: '7d' } })
 
-// 5. Reset
-counter.reset() // back to 0
+// AsyncLocalStorage — server-side, session-scoped
+const user = server({ user: null })
 ```
 
-To persist across page reloads, add a scope:
+For in-memory state that doesn't persist, use `state` directly:
 
 ```ts
-const theme = state('theme', { default: 'light', scope: 'local' })
+import { state } from 'gjendje'
 
-theme.set('dark')
-// Survives refresh — stored in localStorage
+const counter = state({ counter: 0 })
+
+counter.set((prev) => prev + 1)
 ```
 
 ## Configure
 
 Sets global defaults for all state instances.
 
-Call once at your app entry point.
-
 ```ts
+// app.ts
 import { configure } from 'gjendje'
 
 configure({ scope: 'local' })
@@ -56,7 +55,7 @@ configure({ scope: 'local' })
 Now every `state` call inherits that default:
 
 ```ts
-const theme = state('theme', 'light')
+const theme = state({ theme: 'light' })
 
 theme.scope // 'local' — derived from configure
 ```
@@ -65,33 +64,20 @@ theme.scope // 'local' — derived from configure
 
 ## Scopes
 
-|Scope      |Description                                             |
-|-----------|--------------------------------------------------------|
-|`render`   | `memory` |
-|`local`    |`localStorage` |                   
-|`server`   |`AsyncLocalStorage` |
-|`bucket`   | `Storage Buckets API ` |
-|`url`      |`URLSearchParams` |
-|`tab`      |`sessionStorage` |
+| Scope    | Backend              | Shortcut    |
+|----------|----------------------|-------------|
+| `memory` | In-memory            | `state()`   |
+| `local`  | `localStorage`       | `local()`   |
+| `tab`    | `sessionStorage`     | `session()` |
+| `url`    | `URLSearchParams`    | `url()`     |
+| `bucket` | Storage Buckets API  | `bucket()`  |
+| `server` | `AsyncLocalStorage`  | `server()`  |
 
 [Scope decision guide](https://github.com/charliebeckstrand/gjendje/blob/main/docs/scopes.md)
 
 ## API
 
-#### `get()`
-Returns the current value. Reactive — triggers tracking in `computed` and `effect`.
-
-#### `set(value)` / `set(prev => next)`
-Replaces the current value. Accepts a direct value or an updater function that receives the previous value.
-
-#### `subscribe(fn)`
-Calls `fn` on every change. Returns an `unsubscribe` function.
-
-#### `watch(key, fn)`
-Like `subscribe`, but scoped to a single key within an object value. Only fires when that key changes.
-
-#### `intercept(fn)`
-Receives `(next, prev)` before each update. Return the value to store, or return `prev` to reject the change. Returns an `unsubscribe` function.
+Every primitive — `state`, `local`, `session`, `url`, `bucket`, and `server` — shares the same core API: `get`, `set`, `reset`, `subscribe`, `watch`, `intercept`, and more.
 
 [Full API reference](https://github.com/charliebeckstrand/gjendje/blob/main/docs/api.md) · [Persistence reference](https://github.com/charliebeckstrand/gjendje/blob/main/docs/persistence.md)
 

package/dist/{chunk-Z32544QA.js → chunk-5J2W34MR.js}

@@ -633,6 +633,7 @@ function resolveStorageKey(key, options, configPrefix) {
 }
 function resolveAdapter(storageKey, scope, options) {
   switch (scope) {
+    case "memory":
     case "render":
       return createRenderAdapter(options.default);
     case "tab":
@@ -993,7 +994,8 @@ function createBase(key, options) {
       `[gjendje] Key "${key}" does not match the configured keyPattern ${config.keyPattern}.`
     );
   }
-  const scope = options.scope ?? config.scope ?? "render";
+  const rawScope = options.scope ?? config.scope ?? "render";
+  const scope = rawScope === "memory" ? "render" : rawScope;
   const rKey = scopedKey(key, scope);
   const existing = getRegistered(rKey);
   if (existing && !existing.isDestroyed) return existing;

package/dist/{chunk-SCIDKAI5.cjs → chunk-IC7SQVDX.cjs}

@@ -635,6 +635,7 @@ function resolveStorageKey(key, options, configPrefix) {
 }
 function resolveAdapter(storageKey, scope, options) {
   switch (scope) {
+    case "memory":
     case "render":
       return createRenderAdapter(options.default);
     case "tab":
@@ -995,7 +996,8 @@ function createBase(key, options) {
       `[gjendje] Key "${key}" does not match the configured keyPattern ${config.keyPattern}.`
     );
   }
-  const scope = options.scope ?? config.scope ?? "render";
+  const rawScope = options.scope ?? config.scope ?? "render";
+  const scope = rawScope === "memory" ? "render" : rawScope;
   const rKey = scopedKey(key, scope);
   const existing = getRegistered(rKey);
   if (existing && !existing.isDestroyed) return existing;

package/dist/index.cjs

@@ -1,10 +1,10 @@
 'use strict';
 
-var chunkSCIDKAI5_cjs = require('./chunk-SCIDKAI5.cjs');
+var chunkIC7SQVDX_cjs = require('./chunk-IC7SQVDX.cjs');
 
 // src/collection.ts
 function collection(key, options) {
-  const base = chunkSCIDKAI5_cjs.createBase(key, options);
+  const base = chunkIC7SQVDX_cjs.createBase(key, options);
   const watchers = /* @__PURE__ */ new Map();
   let prevItems = base.get();
   const unsubscribe = base.subscribe((next) => {
@@ -139,7 +139,7 @@ function collection(key, options) {
 // src/computed.ts
 var computedCounter = 0;
 function computed(deps, fn, options) {
-  const listeners = chunkSCIDKAI5_cjs.createListeners();
+  const listeners = chunkIC7SQVDX_cjs.createListeners();
   const instanceKey = options?.key ?? `computed:${computedCounter++}`;
   let cached;
   let isDirty = true;
@@ -164,7 +164,7 @@ function computed(deps, fn, options) {
   };
   const markDirty = () => {
     isDirty = true;
-    chunkSCIDKAI5_cjs.notify(notifyListeners);
+    chunkIC7SQVDX_cjs.notify(notifyListeners);
   };
   const unsubscribers = new Array(depLen);
   for (let i = 0; i < depLen; i++) {
@@ -224,7 +224,7 @@ function computed(deps, fn, options) {
 
 // src/devtools.ts
 function snapshot() {
-  const registry = chunkSCIDKAI5_cjs.getRegistry();
+  const registry = chunkIC7SQVDX_cjs.getRegistry();
   const result = [];
   for (const instance of registry.values()) {
     result.push({
@@ -404,45 +404,10 @@ function withWatch(instance) {
   return result;
 }
 
-// src/factory.ts
-function state(key, optionsOrDefault) {
-  const options = optionsOrDefault !== null && typeof optionsOrDefault === "object" && "default" in optionsOrDefault ? optionsOrDefault : { default: optionsOrDefault };
-  if (!key) {
-    throw new Error("[state] key must be a non-empty string.");
-  }
-  const config = chunkSCIDKAI5_cjs.getConfig();
-  if (config.keyPattern && !config.keyPattern.test(key)) {
-    throw new Error(
-      `[gjendje] Key "${key}" does not match the configured keyPattern ${config.keyPattern}.`
-    );
-  }
-  const scope = options.scope ?? config.scope ?? "render";
-  const rKey = chunkSCIDKAI5_cjs.scopedKey(key, scope);
-  const existing = chunkSCIDKAI5_cjs.getRegistered(rKey);
-  if (existing && !existing.isDestroyed) {
-    if (config.warnOnDuplicate) {
-      chunkSCIDKAI5_cjs.log("warn", `Duplicate state("${key}") with scope "${scope}". Returning cached instance.`);
-    }
-    return existing;
-  }
-  if (scope === "render" && !options.ssr && !config.ssr) {
-    if (options.sync) {
-      chunkSCIDKAI5_cjs.log(
-        "warn",
-        `sync: true is ignored for scope "render". Only "local" and "bucket" scopes support cross-tab sync.`
-      );
-    }
-    const instance = chunkSCIDKAI5_cjs.createRenderState(key, rKey, options, config);
-    chunkSCIDKAI5_cjs.registerByKey(rKey, key, scope, instance, config);
-    return instance;
-  }
-  return chunkSCIDKAI5_cjs.createBase(key, options);
-}
-
 // src/previous.ts
 var previousCounter = 0;
 function previous(source, options) {
-  const listeners = chunkSCIDKAI5_cjs.createListeners();
+  const listeners = chunkIC7SQVDX_cjs.createListeners();
   const instanceKey = options?.key ?? `previous:${previousCounter++}`;
   let prev;
   let current = source.get();
@@ -452,7 +417,7 @@ function previous(source, options) {
     prev = current;
     current = next;
     if (old !== prev) {
-      chunkSCIDKAI5_cjs.notify(() => listeners.notify(prev));
+      chunkIC7SQVDX_cjs.notify(() => listeners.notify(prev));
     }
   });
   let destroyedPromise;
@@ -514,7 +479,7 @@ function readonly(instance) {
 // src/select.ts
 var selectCounter = 0;
 function select(source, fn, options) {
-  const listeners = chunkSCIDKAI5_cjs.createListeners();
+  const listeners = chunkIC7SQVDX_cjs.createListeners();
   const instanceKey = options?.key ?? `select:${selectCounter++}`;
   let cached;
   let isDirty = true;
@@ -533,7 +498,7 @@ function select(source, fn, options) {
   };
   const markDirty = () => {
     isDirty = true;
-    chunkSCIDKAI5_cjs.notify(notifyListeners);
+    chunkIC7SQVDX_cjs.notify(notifyListeners);
   };
   const unsubscribe = source.subscribe(markDirty);
   recompute();
@@ -583,25 +548,110 @@ function select(source, fn, options) {
   };
 }
 
+// src/factory.ts
+function createState(key, options) {
+  if (!key) {
+    throw new Error("[state] key must be a non-empty string.");
+  }
+  const config = chunkIC7SQVDX_cjs.getConfig();
+  if (config.keyPattern && !config.keyPattern.test(key)) {
+    throw new Error(
+      `[gjendje] Key "${key}" does not match the configured keyPattern ${config.keyPattern}.`
+    );
+  }
+  const rawScope = options.scope ?? config.scope ?? "render";
+  const scope = rawScope === "memory" ? "render" : rawScope;
+  const rKey = chunkIC7SQVDX_cjs.scopedKey(key, scope);
+  const existing = chunkIC7SQVDX_cjs.getRegistered(rKey);
+  if (existing && !existing.isDestroyed) {
+    if (config.warnOnDuplicate) {
+      chunkIC7SQVDX_cjs.log("warn", `Duplicate state("${key}") with scope "${scope}". Returning cached instance.`);
+    }
+    return existing;
+  }
+  if (scope === "render" && !options.ssr && !config.ssr) {
+    if (options.sync) {
+      chunkIC7SQVDX_cjs.log(
+        "warn",
+        `sync: true is ignored for scope "render". Only "local" and "bucket" scopes support cross-tab sync.`
+      );
+    }
+    const instance = chunkIC7SQVDX_cjs.createRenderState(key, rKey, options, config);
+    chunkIC7SQVDX_cjs.registerByKey(rKey, key, scope, instance, config);
+    return instance;
+  }
+  return chunkIC7SQVDX_cjs.createBase(key, options);
+}
+
+// src/shortcuts.ts
+function extractEntry(entry) {
+  const keys = Object.keys(entry);
+  if (keys.length !== 1) {
+    throw new Error(
+      `[gjendje] Shortcut expects exactly one key, got ${keys.length}: ${keys.join(", ")}`
+    );
+  }
+  const key = keys[0];
+  return [key, entry[key]];
+}
+function state(keyOrEntry, optionsOrDefault, extraOptions) {
+  let key;
+  let options;
+  if (typeof keyOrEntry === "object") {
+    const [entryKey, defaultValue] = extractEntry(keyOrEntry);
+    key = entryKey;
+    options = { ...optionsOrDefault, default: defaultValue };
+  } else {
+    key = keyOrEntry;
+    options = extraOptions ? { ...extraOptions, default: optionsOrDefault } : optionsOrDefault !== null && typeof optionsOrDefault === "object" && "default" in optionsOrDefault ? optionsOrDefault : { default: optionsOrDefault };
+  }
+  return createState(key, options);
+}
+function local(entry, options) {
+  const [key, defaultValue] = extractEntry(entry);
+  return createState(key, { ...options, default: defaultValue, scope: "local" });
+}
+function session(entry, options) {
+  const [key, defaultValue] = extractEntry(entry);
+  return createState(key, { ...options, default: defaultValue, scope: "tab" });
+}
+function url(entry, options) {
+  const [key, defaultValue] = extractEntry(entry);
+  return createState(key, { ...options, default: defaultValue, scope: "url" });
+}
+function server(entry, options) {
+  const [key, defaultValue] = extractEntry(entry);
+  return createState(key, { ...options, default: defaultValue, scope: "server" });
+}
+function bucket(entry, options) {
+  const [key, defaultValue] = extractEntry(entry);
+  return createState(key, { ...options, default: defaultValue, scope: "bucket" });
+}
+
 Object.defineProperty(exports, "batch", {
   enumerable: true,
-  get: function () { return chunkSCIDKAI5_cjs.batch; }
+  get: function () { return chunkIC7SQVDX_cjs.batch; }
 });
 Object.defineProperty(exports, "configure", {
   enumerable: true,
-  get: function () { return chunkSCIDKAI5_cjs.configure; }
+  get: function () { return chunkIC7SQVDX_cjs.configure; }
 });
 Object.defineProperty(exports, "shallowEqual", {
   enumerable: true,
-  get: function () { return chunkSCIDKAI5_cjs.shallowEqual; }
+  get: function () { return chunkIC7SQVDX_cjs.shallowEqual; }
 });
+exports.bucket = bucket;
 exports.collection = collection;
 exports.computed = computed;
 exports.effect = effect;
+exports.local = local;
 exports.previous = previous;
 exports.readonly = readonly;
 exports.select = select;
+exports.server = server;
+exports.session = session;
 exports.snapshot = snapshot;
 exports.state = state;
+exports.url = url;
 exports.withHistory = withHistory;
 exports.withWatch = withWatch;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { B as BaseInstance, U as Unsubscribe, S as StateOptions, R as ReadonlyInstance, a as Scope, b as StateInstance } from './types-BQb8Z14O.cjs';
-export { A as Adapter, c as BucketOptions, E as Enhancer, L as Listener, d as Serializer } from './types-BQb8Z14O.cjs';
+import { B as BaseInstance, U as Unsubscribe, S as StateOptions, R as ReadonlyInstance, a as Scope, b as StateInstance } from './types-CmmPImmo.cjs';
+export { A as Adapter, c as BucketOptions, E as Enhancer, L as Listener, d as Serializer } from './types-CmmPImmo.cjs';
 
 /**
  * Runs all state updates inside fn as a single batch.
@@ -286,26 +286,6 @@ interface WithWatch<T> {
  */
 declare function withWatch<TIn extends BaseInstance<any>>(instance: TIn): TIn & WithWatch<TIn extends BaseInstance<infer T> ? T : unknown>;
 
-type Widen<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
-/**
- * Create a stateful value.
- *
- * Same key + same scope always returns the same instance.
- * Change scope to move state anywhere.
- *
- * ```ts
- * const theme = state('theme', { default: 'light', scope: 'local' })
- * const filters = state('filters', { default: {}, scope: 'url' })
- * const user = state('user', { default: null, scope: 'server' })
- *
- * // Shorthand — pass a default value directly
- * const counter = state('counter', 0)
- * const name = state('name', 'guest')
- * ```
- */
-declare function state<T>(key: string, options: StateOptions<T>): StateInstance<T>;
-declare function state<T extends string | number | boolean | null | undefined>(key: string, defaultValue: T): StateInstance<Widen<T>>;
-
 /**
  * A read-only reactive value that tracks the previous value of a source.
  * Lighter than `withHistory` — stores only the single prior value,
@@ -384,10 +364,77 @@ interface SelectOptions {
  */
 declare function select<TSource, TResult>(source: ReadonlyInstance<TSource>, fn: (value: TSource) => TResult, options?: SelectOptions): SelectInstance<TResult>;
 
+type Widen<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
+type ShortcutOptions<T> = Omit<StateOptions<T>, 'default' | 'scope'>;
+type BucketShortcutOptions<T> = Omit<StateOptions<T>, 'default' | 'scope' | 'bucket'> & Pick<StateOptions<T>, 'bucket'>;
+/**
+ * Create a stateful value.
+ *
+ * Preferred — entry object form (key derived from property name):
+ *
+ * ```ts
+ * const counter = state({ counter: 0 })
+ * const theme = state({ theme: 'light' }, { scope: 'local' })
+ * ```
+ *
+ * Alternative — string key forms:
+ *
+ * ```ts
+ * const theme = state('theme', { default: 'light', scope: 'local' })
+ * const synced = state('theme', 'light', { scope: 'local', sync: true })
+ * const counter = state('counter', 0)
+ * ```
+ */
+declare function state<T>(entry: Record<string, T>, options?: Omit<StateOptions<T>, 'default'>): StateInstance<T>;
+declare function state<T>(key: string, options: StateOptions<T>): StateInstance<T>;
+declare function state<T>(key: string, defaultValue: T, options: Omit<StateOptions<T>, 'default'>): StateInstance<T>;
+declare function state<T extends string | number | boolean | null | undefined>(key: string, defaultValue: T): StateInstance<Widen<T>>;
+/**
+ * Create state stored in `localStorage`.
+ *
+ * ```ts
+ * const theme = local({ theme: 'light' })
+ * const synced = local({ theme: 'dark' }, { sync: true })
+ * ```
+ */
+declare function local<T>(entry: Record<string, T>, options?: ShortcutOptions<T>): StateInstance<T>;
+/**
+ * Create state stored in `sessionStorage`.
+ *
+ * ```ts
+ * const draft = session({ draft: '' })
+ * ```
+ */
+declare function session<T>(entry: Record<string, T>, options?: ShortcutOptions<T>): StateInstance<T>;
+/**
+ * Create state stored in `URLSearchParams`.
+ *
+ * ```ts
+ * const filters = url({ filters: { q: '' } })
+ * ```
+ */
+declare function url<T>(entry: Record<string, T>, options?: ShortcutOptions<T>): StateInstance<T>;
+/**
+ * Create state stored in server-side `AsyncLocalStorage`.
+ *
+ * ```ts
+ * const user = server({ user: null })
+ * ```
+ */
+declare function server<T>(entry: Record<string, T>, options?: ShortcutOptions<T>): StateInstance<T>;
+/**
+ * Create state stored in a Storage Bucket.
+ *
+ * ```ts
+ * const data = bucket({ cache: [] }, { bucket: { name: 'my-bucket' } })
+ * ```
+ */
+declare function bucket<T>(entry: Record<string, T>, options: BucketShortcutOptions<T>): StateInstance<T>;
+
 /**
  * Shallow equality check for primitives, arrays, and plain objects.
  * Returns true if the two values are structurally equal at one level deep.
  */
 declare function shallowEqual(a: unknown, b: unknown): boolean;
 
-export { BaseInstance, type CollectionInstance, type ComputedInstance, type ComputedOptions, type DestroyContext, type EffectHandle, type ErrorContext, type GjendjeConfig, type HistoryOptions, type HydrateContext, type LogLevel, type MigrateContext, type PreviousInstance, type PreviousOptions, type QuotaExceededContext, ReadonlyInstance, type RegisterContext, Scope, type SelectInstance, type SelectOptions, StateInstance, StateOptions, type StateSnapshot, type SyncContext, Unsubscribe, type WithHistoryInstance, type WithWatch, batch, collection, computed, configure, effect, previous, readonly, select, shallowEqual, snapshot, state, withHistory, withWatch };
+export { BaseInstance, type CollectionInstance, type ComputedInstance, type ComputedOptions, type DestroyContext, type EffectHandle, type ErrorContext, type GjendjeConfig, type HistoryOptions, type HydrateContext, type LogLevel, type MigrateContext, type PreviousInstance, type PreviousOptions, type QuotaExceededContext, ReadonlyInstance, type RegisterContext, Scope, type SelectInstance, type SelectOptions, StateInstance, StateOptions, type StateSnapshot, type SyncContext, Unsubscribe, type WithHistoryInstance, type WithWatch, batch, bucket, collection, computed, configure, effect, local, previous, readonly, select, server, session, shallowEqual, snapshot, state, url, withHistory, withWatch };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { B as BaseInstance, U as Unsubscribe, S as StateOptions, R as ReadonlyInstance, a as Scope, b as StateInstance } from './types-BQb8Z14O.js';
-export { A as Adapter, c as BucketOptions, E as Enhancer, L as Listener, d as Serializer } from './types-BQb8Z14O.js';
+import { B as BaseInstance, U as Unsubscribe, S as StateOptions, R as ReadonlyInstance, a as Scope, b as StateInstance } from './types-CmmPImmo.js';
+export { A as Adapter, c as BucketOptions, E as Enhancer, L as Listener, d as Serializer } from './types-CmmPImmo.js';
 
 /**
  * Runs all state updates inside fn as a single batch.
@@ -286,26 +286,6 @@ interface WithWatch<T> {
  */
 declare function withWatch<TIn extends BaseInstance<any>>(instance: TIn): TIn & WithWatch<TIn extends BaseInstance<infer T> ? T : unknown>;
 
-type Widen<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
-/**
- * Create a stateful value.
- *
- * Same key + same scope always returns the same instance.
- * Change scope to move state anywhere.
- *
- * ```ts
- * const theme = state('theme', { default: 'light', scope: 'local' })
- * const filters = state('filters', { default: {}, scope: 'url' })
- * const user = state('user', { default: null, scope: 'server' })
- *
- * // Shorthand — pass a default value directly
- * const counter = state('counter', 0)
- * const name = state('name', 'guest')
- * ```
- */
-declare function state<T>(key: string, options: StateOptions<T>): StateInstance<T>;
-declare function state<T extends string | number | boolean | null | undefined>(key: string, defaultValue: T): StateInstance<Widen<T>>;
-
 /**
  * A read-only reactive value that tracks the previous value of a source.
  * Lighter than `withHistory` — stores only the single prior value,
@@ -384,10 +364,77 @@ interface SelectOptions {
  */
 declare function select<TSource, TResult>(source: ReadonlyInstance<TSource>, fn: (value: TSource) => TResult, options?: SelectOptions): SelectInstance<TResult>;
 
+type Widen<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
+type ShortcutOptions<T> = Omit<StateOptions<T>, 'default' | 'scope'>;
+type BucketShortcutOptions<T> = Omit<StateOptions<T>, 'default' | 'scope' | 'bucket'> & Pick<StateOptions<T>, 'bucket'>;
+/**
+ * Create a stateful value.
+ *
+ * Preferred — entry object form (key derived from property name):
+ *
+ * ```ts
+ * const counter = state({ counter: 0 })
+ * const theme = state({ theme: 'light' }, { scope: 'local' })
+ * ```
+ *
+ * Alternative — string key forms:
+ *
+ * ```ts
+ * const theme = state('theme', { default: 'light', scope: 'local' })
+ * const synced = state('theme', 'light', { scope: 'local', sync: true })
+ * const counter = state('counter', 0)
+ * ```
+ */
+declare function state<T>(entry: Record<string, T>, options?: Omit<StateOptions<T>, 'default'>): StateInstance<T>;
+declare function state<T>(key: string, options: StateOptions<T>): StateInstance<T>;
+declare function state<T>(key: string, defaultValue: T, options: Omit<StateOptions<T>, 'default'>): StateInstance<T>;
+declare function state<T extends string | number | boolean | null | undefined>(key: string, defaultValue: T): StateInstance<Widen<T>>;
+/**
+ * Create state stored in `localStorage`.
+ *
+ * ```ts
+ * const theme = local({ theme: 'light' })
+ * const synced = local({ theme: 'dark' }, { sync: true })
+ * ```
+ */
+declare function local<T>(entry: Record<string, T>, options?: ShortcutOptions<T>): StateInstance<T>;
+/**
+ * Create state stored in `sessionStorage`.
+ *
+ * ```ts
+ * const draft = session({ draft: '' })
+ * ```
+ */
+declare function session<T>(entry: Record<string, T>, options?: ShortcutOptions<T>): StateInstance<T>;
+/**
+ * Create state stored in `URLSearchParams`.
+ *
+ * ```ts
+ * const filters = url({ filters: { q: '' } })
+ * ```
+ */
+declare function url<T>(entry: Record<string, T>, options?: ShortcutOptions<T>): StateInstance<T>;
+/**
+ * Create state stored in server-side `AsyncLocalStorage`.
+ *
+ * ```ts
+ * const user = server({ user: null })
+ * ```
+ */
+declare function server<T>(entry: Record<string, T>, options?: ShortcutOptions<T>): StateInstance<T>;
+/**
+ * Create state stored in a Storage Bucket.
+ *
+ * ```ts
+ * const data = bucket({ cache: [] }, { bucket: { name: 'my-bucket' } })
+ * ```
+ */
+declare function bucket<T>(entry: Record<string, T>, options: BucketShortcutOptions<T>): StateInstance<T>;
+
 /**
  * Shallow equality check for primitives, arrays, and plain objects.
  * Returns true if the two values are structurally equal at one level deep.
  */
 declare function shallowEqual(a: unknown, b: unknown): boolean;
 
-export { BaseInstance, type CollectionInstance, type ComputedInstance, type ComputedOptions, type DestroyContext, type EffectHandle, type ErrorContext, type GjendjeConfig, type HistoryOptions, type HydrateContext, type LogLevel, type MigrateContext, type PreviousInstance, type PreviousOptions, type QuotaExceededContext, ReadonlyInstance, type RegisterContext, Scope, type SelectInstance, type SelectOptions, StateInstance, StateOptions, type StateSnapshot, type SyncContext, Unsubscribe, type WithHistoryInstance, type WithWatch, batch, collection, computed, configure, effect, previous, readonly, select, shallowEqual, snapshot, state, withHistory, withWatch };
+export { BaseInstance, type CollectionInstance, type ComputedInstance, type ComputedOptions, type DestroyContext, type EffectHandle, type ErrorContext, type GjendjeConfig, type HistoryOptions, type HydrateContext, type LogLevel, type MigrateContext, type PreviousInstance, type PreviousOptions, type QuotaExceededContext, ReadonlyInstance, type RegisterContext, Scope, type SelectInstance, type SelectOptions, StateInstance, StateOptions, type StateSnapshot, type SyncContext, Unsubscribe, type WithHistoryInstance, type WithWatch, batch, bucket, collection, computed, configure, effect, local, previous, readonly, select, server, session, shallowEqual, snapshot, state, url, withHistory, withWatch };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { createBase, createListeners, getRegistry, getConfig, scopedKey, getRegistered, log, createRenderState, registerByKey, notify } from './chunk-Z32544QA.js';
-export { batch, configure, shallowEqual } from './chunk-Z32544QA.js';
+import { createBase, createListeners, getRegistry, notify, getConfig, scopedKey, getRegistered, log, createRenderState, registerByKey } from './chunk-5J2W34MR.js';
+export { batch, configure, shallowEqual } from './chunk-5J2W34MR.js';
 
 // src/collection.ts
 function collection(key, options) {
@@ -403,41 +403,6 @@ function withWatch(instance) {
   return result;
 }
 
-// src/factory.ts
-function state(key, optionsOrDefault) {
-  const options = optionsOrDefault !== null && typeof optionsOrDefault === "object" && "default" in optionsOrDefault ? optionsOrDefault : { default: optionsOrDefault };
-  if (!key) {
-    throw new Error("[state] key must be a non-empty string.");
-  }
-  const config = getConfig();
-  if (config.keyPattern && !config.keyPattern.test(key)) {
-    throw new Error(
-      `[gjendje] Key "${key}" does not match the configured keyPattern ${config.keyPattern}.`
-    );
-  }
-  const scope = options.scope ?? config.scope ?? "render";
-  const rKey = scopedKey(key, scope);
-  const existing = getRegistered(rKey);
-  if (existing && !existing.isDestroyed) {
-    if (config.warnOnDuplicate) {
-      log("warn", `Duplicate state("${key}") with scope "${scope}". Returning cached instance.`);
-    }
-    return existing;
-  }
-  if (scope === "render" && !options.ssr && !config.ssr) {
-    if (options.sync) {
-      log(
-        "warn",
-        `sync: true is ignored for scope "render". Only "local" and "bucket" scopes support cross-tab sync.`
-      );
-    }
-    const instance = createRenderState(key, rKey, options, config);
-    registerByKey(rKey, key, scope, instance, config);
-    return instance;
-  }
-  return createBase(key, options);
-}
-
 // src/previous.ts
 var previousCounter = 0;
 function previous(source, options) {
@@ -582,4 +547,84 @@ function select(source, fn, options) {
   };
 }
 
-export { collection, computed, effect, previous, readonly, select, snapshot, state, withHistory, withWatch };
+// src/factory.ts
+function createState(key, options) {
+  if (!key) {
+    throw new Error("[state] key must be a non-empty string.");
+  }
+  const config = getConfig();
+  if (config.keyPattern && !config.keyPattern.test(key)) {
+    throw new Error(
+      `[gjendje] Key "${key}" does not match the configured keyPattern ${config.keyPattern}.`
+    );
+  }
+  const rawScope = options.scope ?? config.scope ?? "render";
+  const scope = rawScope === "memory" ? "render" : rawScope;
+  const rKey = scopedKey(key, scope);
+  const existing = getRegistered(rKey);
+  if (existing && !existing.isDestroyed) {
+    if (config.warnOnDuplicate) {
+      log("warn", `Duplicate state("${key}") with scope "${scope}". Returning cached instance.`);
+    }
+    return existing;
+  }
+  if (scope === "render" && !options.ssr && !config.ssr) {
+    if (options.sync) {
+      log(
+        "warn",
+        `sync: true is ignored for scope "render". Only "local" and "bucket" scopes support cross-tab sync.`
+      );
+    }
+    const instance = createRenderState(key, rKey, options, config);
+    registerByKey(rKey, key, scope, instance, config);
+    return instance;
+  }
+  return createBase(key, options);
+}
+
+// src/shortcuts.ts
+function extractEntry(entry) {
+  const keys = Object.keys(entry);
+  if (keys.length !== 1) {
+    throw new Error(
+      `[gjendje] Shortcut expects exactly one key, got ${keys.length}: ${keys.join(", ")}`
+    );
+  }
+  const key = keys[0];
+  return [key, entry[key]];
+}
+function state(keyOrEntry, optionsOrDefault, extraOptions) {
+  let key;
+  let options;
+  if (typeof keyOrEntry === "object") {
+    const [entryKey, defaultValue] = extractEntry(keyOrEntry);
+    key = entryKey;
+    options = { ...optionsOrDefault, default: defaultValue };
+  } else {
+    key = keyOrEntry;
+    options = extraOptions ? { ...extraOptions, default: optionsOrDefault } : optionsOrDefault !== null && typeof optionsOrDefault === "object" && "default" in optionsOrDefault ? optionsOrDefault : { default: optionsOrDefault };
+  }
+  return createState(key, options);
+}
+function local(entry, options) {
+  const [key, defaultValue] = extractEntry(entry);
+  return createState(key, { ...options, default: defaultValue, scope: "local" });
+}
+function session(entry, options) {
+  const [key, defaultValue] = extractEntry(entry);
+  return createState(key, { ...options, default: defaultValue, scope: "tab" });
+}
+function url(entry, options) {
+  const [key, defaultValue] = extractEntry(entry);
+  return createState(key, { ...options, default: defaultValue, scope: "url" });
+}
+function server(entry, options) {
+  const [key, defaultValue] = extractEntry(entry);
+  return createState(key, { ...options, default: defaultValue, scope: "server" });
+}
+function bucket(entry, options) {
+  const [key, defaultValue] = extractEntry(entry);
+  return createState(key, { ...options, default: defaultValue, scope: "bucket" });
+}
+
+export { bucket, collection, computed, effect, local, previous, readonly, select, server, session, snapshot, state, url, withHistory, withWatch };

package/dist/server.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkSCIDKAI5_cjs = require('./chunk-SCIDKAI5.cjs');
+var chunkIC7SQVDX_cjs = require('./chunk-IC7SQVDX.cjs');
 var async_hooks = require('async_hooks');
 
 var als = new async_hooks.AsyncLocalStorage();
@@ -9,7 +9,7 @@ async function withServerSession(fn) {
   return als.run(store, fn);
 }
 function createServerAdapter(key, defaultValue) {
-  const listeners = chunkSCIDKAI5_cjs.createListeners();
+  const listeners = chunkIC7SQVDX_cjs.createListeners();
   function getStore() {
     return als.getStore();
   }
@@ -31,7 +31,7 @@ function createServerAdapter(key, defaultValue) {
       }
       store.set(key, value);
       lastNotifiedValue = value;
-      chunkSCIDKAI5_cjs.notify(notifyListeners);
+      chunkIC7SQVDX_cjs.notify(notifyListeners);
     },
     subscribe: listeners.subscribe,
     destroy() {
@@ -39,7 +39,7 @@ function createServerAdapter(key, defaultValue) {
     }
   };
 }
-chunkSCIDKAI5_cjs.registerServerAdapter(createServerAdapter);
+chunkIC7SQVDX_cjs.registerServerAdapter(createServerAdapter);
 
 exports.createServerAdapter = createServerAdapter;
 exports.withServerSession = withServerSession;

package/dist/server.d.cts

@@ -1,4 +1,4 @@
-import { A as Adapter } from './types-BQb8Z14O.cjs';
+import { A as Adapter } from './types-CmmPImmo.cjs';
 
 declare function withServerSession<T>(fn: () => T): Promise<T>;
 declare function createServerAdapter<T>(key: string, defaultValue: T): Adapter<T>;

package/dist/server.d.ts

@@ -1,4 +1,4 @@
-import { A as Adapter } from './types-BQb8Z14O.js';
+import { A as Adapter } from './types-CmmPImmo.js';
 
 declare function withServerSession<T>(fn: () => T): Promise<T>;
 declare function createServerAdapter<T>(key: string, defaultValue: T): Adapter<T>;

package/dist/server.js

@@ -1,4 +1,4 @@
-import { registerServerAdapter, createListeners, notify } from './chunk-Z32544QA.js';
+import { registerServerAdapter, createListeners, notify } from './chunk-5J2W34MR.js';
 import { AsyncLocalStorage } from 'async_hooks';
 
 var als = new AsyncLocalStorage();

package/dist/{types-BQb8Z14O.d.cts → types-CmmPImmo.d.cts}

@@ -1,4 +1,4 @@
-type Scope = 'render' | 'tab' | 'local' | 'url' | 'server' | 'bucket';
+type Scope = 'memory' | 'render' | 'tab' | 'local' | 'url' | 'server' | 'bucket';
 interface Adapter<T> {
     get(): T;
     set(value: T): void;

package/dist/{types-BQb8Z14O.d.ts → types-CmmPImmo.d.ts}

@@ -1,4 +1,4 @@
-type Scope = 'render' | 'tab' | 'local' | 'url' | 'server' | 'bucket';
+type Scope = 'memory' | 'render' | 'tab' | 'local' | 'url' | 'server' | 'bucket';
 interface Adapter<T> {
     get(): T;
     set(value: T): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gjendje",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "TypeScript state management",
   "keywords": [
     "state",