@friendofsvelte/state 0.0.1-dev

package/README.md

@@ -0,0 +1,139 @@
+# Persistent Svelte 5 State
+
+A lightweight, type-safe state management solution for Svelte applications with built-in storage persistence.
+
+## Features
+
+- 🎯 **Type-safe**: Full TypeScript support with automatic type inference
+- 💾 **Persistent Storage**: Automatic state persistence in localStorage or sessionStorage
+- 🪶 **Lightweight**: Zero dependencies beyond Svelte
+- ⚡ **Reactive**: Seamless integration with Svelte's reactivity system
+- 🔄 **Auto-sync**: Automatically syncs state across components
+- 📦 **Simple API**: Just one function to manage all your state needs
+
+## Installation
+
+```bash
+npm install @friendofsvelte/state
+```
+
+## Quick Start
+
+1. Define your types in your `app.d.ts`:
+
+```typescript
+declare global {
+  interface PodTypeRegistry {
+    layout: {
+      bg: string;
+    };
+    userSettings: {
+      theme: 'light' | 'dark';
+      fontSize: number;
+    };
+  }
+}
+
+export {};
+```
+
+2. Use in your components:
+
+```svelte
+<script lang="ts">
+  import { pod } from '@friendofsvelte/state';
+  
+  // Initialize with value
+  let app = pod('layout', 'localStorage', {
+    bg: 'lightblue'
+  });
+  
+  // Or use existing value
+  let settings = pod('userSettings');
+</script>
+
+<div style="background-color: {app.bg}">
+  <!-- Your content -->
+</div>
+```
+
+## API Reference
+
+### `pod<K>(key: K, storage?: StorageType, context?: GetTypeFromRegistry<K>)`
+
+Creates or retrieves a persistent state container.
+
+Parameters:
+- `key`: Unique identifier for the state container
+- `storage`: (Optional) Storage type - 'localStorage' or 'sessionStorage' (default: 'localStorage')
+- `context`: (Optional) Initial state value
+
+Returns:
+- A reactive state object of type `GetTypeFromRegistry<K>`
+
+## Type Safety
+
+Pod State provides complete type safety through TypeScript. The global `PodTypeRegistry` interface allows you to define types for all your state containers in one place:
+
+```typescript
+interface PodTypeRegistry {
+  layout: {
+    bg: string;
+  };
+  userSettings: {
+    theme: 'light' | 'dark';
+    fontSize: number;
+  };
+}
+```
+
+## Examples
+
+### Basic Usage
+
+```svelte
+<script lang="ts">
+  import { pod } from '@friendofsvelte/state';
+  
+  let app = pod('layout', 'localStorage', {
+    bg: 'lightblue'
+  });
+</script>
+
+<button onclick={() => app.bg = 'lightgreen'}>
+  Change Background
+</button>
+```
+
+### Shared State
+
+```svelte
+<!-- ComponentA.svelte -->
+<script>
+  import { pod } from '@friendofsvelte/state';
+  let settings = pod('userSettings');
+</script>
+
+<!-- ComponentB.svelte -->
+<script>
+  import { pod } from '@friendofsvelte/state';
+  let settings = pod('userSettings');
+  // Will automatically sync with ComponentA
+</script>
+```
+
+## Testing
+
+Pod State includes a test suite to ensure reliability. Run tests with:
+
+```bash
+npm test
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see LICENSE file for details

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { pod } from './state.svelte';

package/dist/index.js

@@ -0,0 +1,2 @@
+// Reexport your entry components here
+export { pod } from './state.svelte';

package/dist/state.svelte.d.ts

@@ -0,0 +1,16 @@
+type StorageType = 'localStorage' | 'sessionStorage';
+type TypeRegistry = {
+    [K in PropertyKey]: unknown;
+};
+declare global {
+    type PodTypeRegistry = TypeRegistry;
+}
+type GetTypeFromRegistry<K extends keyof PodTypeRegistry> = PodTypeRegistry[K] extends never ? unknown : PodTypeRegistry[K];
+/**
+ * Get a persistent state from storage, or initialize with an optional context.
+ * @param key - The key to store the state.
+ * @param storage - The storage type to use.
+ * @param context - The initial state or override.
+ */
+export declare function pod<K extends keyof PodTypeRegistry>(key: K, storage?: StorageType, context?: GetTypeFromRegistry<K>): GetTypeFromRegistry<K>;
+export {};

package/dist/state.svelte.js

@@ -0,0 +1,31 @@
+import { untrack } from 'svelte';
+function track(key, storage, context) {
+    let state = $state(context ?? {});
+    if (typeof window !== 'undefined') {
+        if (context === undefined) {
+            const storedValue = untrack(() => window[storage].getItem(String(key)));
+            if (storedValue) {
+                try {
+                    state = JSON.parse(storedValue);
+                }
+                catch {
+                    state = {};
+                }
+            }
+        }
+        $effect.pre(() => {
+            const json = JSON.stringify($state.snapshot(state));
+            window[storage].setItem(String(key), json);
+        });
+    }
+    return state;
+}
+/**
+ * Get a persistent state from storage, or initialize with an optional context.
+ * @param key - The key to store the state.
+ * @param storage - The storage type to use.
+ * @param context - The initial state or override.
+ */
+export function pod(key, storage = 'localStorage', context) {
+    return track(key, storage, context);
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+	"name": "@friendofsvelte/state",
+	"version": "0.0.1-dev",
+	"scripts": {
+		"dev": "vite dev",
+		"build": "vite build && npm run prepack",
+		"preview": "vite preview",
+		"prepare": "svelte-kit sync || echo ''",
+		"prepack": "svelte-kit sync && svelte-package && publint",
+		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+		"format": "prettier --write .",
+		"lint": "prettier --check . && eslint .",
+		"test:unit": "vitest",
+		"test": "npm run test:unit -- --run"
+	},
+	"files": [
+		"dist",
+		"!dist/**/*.test.*",
+		"!dist/**/*.spec.*"
+	],
+	"sideEffects": [
+		"**/*.css"
+	],
+	"svelte": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"svelte": "./dist/index.js"
+		}
+	},
+	"peerDependencies": {
+		"svelte": "^5.0.0"
+	},
+	"devDependencies": {
+		"@eslint/compat": "^1.2.5",
+		"@eslint/js": "^9.18.0",
+		"@sveltejs/adapter-auto": "^4.0.0",
+		"@sveltejs/kit": "^2.16.0",
+		"@sveltejs/package": "^2.0.0",
+		"@sveltejs/vite-plugin-svelte": "^5.0.0",
+		"@tailwindcss/vite": "^4.0.0",
+		"@testing-library/jest-dom": "^6.6.3",
+		"@testing-library/svelte": "^5.2.4",
+		"eslint": "^9.18.0",
+		"eslint-config-prettier": "^10.0.1",
+		"eslint-plugin-svelte": "^2.46.1",
+		"globals": "^15.14.0",
+		"jsdom": "^25.0.1",
+		"prettier": "^3.4.2",
+		"prettier-plugin-svelte": "^3.3.3",
+		"prettier-plugin-tailwindcss": "^0.6.11",
+		"publint": "^0.3.2",
+		"svelte": "^5.0.0",
+		"svelte-check": "^4.0.0",
+		"tailwindcss": "^4.0.0",
+		"typescript": "^5.0.0",
+		"typescript-eslint": "^8.20.0",
+		"vite": "^6.0.0",
+		"vitest": "^3.0.0"
+	}
+}