https://github.com/humanspeak/svelte-keyed
A powerful writable derived store for Svelte that enables deep object and array manipulation with TypeScript support
https://github.com/humanspeak/svelte-keyed
array-store derived nested-store object-store reactive rxjs state-management store svelte svelte5 sveltekit typescript
Last synced: 3 months ago
JSON representation
A powerful writable derived store for Svelte that enables deep object and array manipulation with TypeScript support
- Host: GitHub
- URL: https://github.com/humanspeak/svelte-keyed
- Owner: humanspeak
- License: mit
- Created: 2024-11-10T22:25:01.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-21T04:17:56.000Z (about 1 year ago)
- Last Synced: 2025-10-25T21:34:57.194Z (7 months ago)
- Topics: array-store, derived, nested-store, object-store, reactive, rxjs, state-management, store, svelte, svelte5, sveltekit, typescript
- Language: TypeScript
- Homepage:
- Size: 997 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# @humanspeak/svelte-keyed
> A powerful TypeScript-first derived store for Svelte 5 that enables deep object and array manipulation with full reactivity.
[](https://www.npmjs.com/package/humanspeak/svelte-keyed)
[](https://coveralls.io/github/humanspeak/svelte-keyed?branch=main)
[](https://www.npmjs.com/package/@humanspeak/svelte-keyed)
[](https://github.com/humanspeak/svelte-keyed/blob/main/LICENSE)
[](https://github.com/humanspeak/svelte-keyed/actions/workflows/codeql.yml)
[](https://packagephobia.com/result?p=@humanspeak/svelte-keyed)
[](https://trunk.io)
## Features
- ðŊ **Type-Safe**: Full TypeScript support with automatic type inference
- ð **Reactive**: Deep object and array manipulation with automatic updates
- ðĻ **Svelte 5 Ready**: Built for the latest Svelte features
- ðŠķ **Lightweight**: Zero dependencies, tiny bundle size
- ð **Null-Safe**: Built-in handling for nullable types
- ðŪ **Easy API**: Simple dot notation for deep object access
## Quick Start
```js
const user = writable({ name: { first: 'Rich', last: 'Harris' } })
const firstName = keyed(user, 'name.first')
$firstName = 'Bryan'
console.log($user) // { name: { first: 'Bryan', last: 'Harris' } };
```
## Installation
```bash
npm i -D svelte-keyed
```
Since Svelte automatically bundles all required dependencies, you only need to install this package as a dev dependency with the `-D` flag.
## Why svelte-keyed?
While Svelte's built-in stores are powerful, they don't provide an elegant way to work with nested properties. svelte-keyed solves this by:
- Enabling direct manipulation of nested properties
- Maintaining full TypeScript support
- Providing a clean API for complex state management
- Supporting both object and array access patterns
## API
`keyed` takes a writable object store and a **keypath**, and returns a writable store whose _changes are reflected on the original store_.
Properties are accessed with dot notation, and arrays can be indexed with bracket notation.
```js
const email = keyed(settings, 'profiles[0].email')
```
### Nullable parents
If the parent store is nullable, then the child store will also be nullable.
```ts
type User = {
name: {
first: string
last: string
}
relations: {
partner?: User
}
}
const maybeUser = writable(undefined)
// Writable
const firstName = keyed(maybeUser, 'name.first')
```
### Nullable properties
Nullable properties are accessed with [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) behaviour.
```ts
const user = writable(initUser)
// Writable
const partnerName = keyed(user, 'relations.partner.name')
```
### TypeScript
`keyed` infers the return type of the keyed store from the keypath.
```ts
const user = writable(initUser)
// Writable
const firstName = keyed(user, 'name.first')
```
`keyed` will also try to guess all possible keypaths up to a depth limit of 3.
```ts
keyed(user, '...');
âââââââââââââââââââââââââââââââââ
â âĒ name â
â âĒ name.first â
â âĒ name.last â
â âĒ relations â
â âĒ relations.partner â
â âĒ relations.partner.name â
âââââââââââââââââââââââââââââââââ
```
_This limit is due to a TypeScript limitation where structured types must be generated statically. Increasing the depth limit slows down type compilation._
Type hints will not be provided for keypaths with a depth greater than 3 but this does not affect the return type.
```ts
const user = writable(user)
// Writable
const firstName = keyed(user, 'relations.partner.name.first')
```
## Motivations
We usually read and write properties of an object store with [auto-subscriptions](https://svelte.dev/tutorial/auto-subscriptions).
```svelte
```
However, auto-subscriptions are isolated to a Svelte component. `svelte-keyed` aims to solve several common limitations listed below.
### Context stores
Often, we want to set a property or element of a store into component context, then allow child components to read / write to the property.
```svelte
setContext('profileSettings', keyed(settings, 'profile'))
```
```svelte
const profileSettings = getContext('profileSettings')
```
### Helper functions
One important method to reduce clutter on your component is to extract functionality into external helper functions. `svelte-keyed` allows you to create derived `Writable` stores that can be passed into or returned from helper functions.
```svelte
const stats = writable({ userClicks: 0, userTaps: 0 })
const clicks = keyed(stats, 'userClicks')
```
```js
export const trackClicks = (node, clicks) => {
const listen = () => {
clicks.update(($clicks) => $clicks + 1)
}
node.addEventListener('click', listen)
return {
destroy() {
node.removeEventListener('click', listen)
}
}
}
```
## License
MIT ÂĐ [Humanspeak, Inc.](LICENSE)
## Credits
Made with âĨ by [Humanspeak](https://humanspeak.com)