@owlmeans/state 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OwlMeans Common — Fullstack typescript framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,456 @@
+# @owlmeans/state
+
+A reactive state management library for OwlMeans Common applications. This package provides a comprehensive state management system with subscription-based reactivity, resource integration, and real-time data synchronization for building responsive fullstack applications.
+
+## Overview
+
+The `@owlmeans/state` package is a reactive state management library in the OwlMeans Common ecosystem that provides:
+
+- **Reactive State Management**: Subscribe to state changes with automatic updates
+- **Resource Integration**: Built on top of OwlMeans Resource system for data persistence
+- **Real-time Synchronization**: Live updates across multiple subscribers
+- **Model-Based Architecture**: Type-safe state models with built-in update methods
+- **Query Subscriptions**: Subscribe to filtered data sets with criteria
+- **Memory Management**: Automatic cleanup and unsubscription handling
+- **Context Integration**: Seamless integration with OwlMeans context system
+
+## Installation
+
+```bash
+npm install @owlmeans/state
+```
+
+## Core Concepts
+
+### State Resource
+
+The `StateResource` extends the standard OwlMeans Resource interface with reactive capabilities, allowing components to subscribe to data changes and receive automatic updates.
+
+### State Model
+
+A `StateModel` wraps resource records with reactive capabilities, providing methods to update data and automatically notify subscribers of changes.
+
+### Subscriptions
+
+Subscriptions connect components to state changes, automatically triggering updates when subscribed data changes.
+
+### Listeners
+
+Functions that handle state change notifications, receiving updated state models when data changes.
+
+## API Reference
+
+### Types
+
+#### `StateResource<T extends ResourceRecord>`
+Extended resource interface with subscription capabilities.
+
+```typescript
+interface StateResource<T extends ResourceRecord> extends Resource<T> {
+  subscribe: (params: StateSubscriptionOption<T>) => [() => void, StateModel<T>[]]
+  listen: (listener: StateListener<T>) => () => void
+  erase: () => Promise<void>
+}
+```
+
+#### `StateModel<T extends ResourceRecord>`
+Reactive wrapper for resource records.
+
+```typescript
+interface StateModel<T extends ResourceRecord> {
+  record: T
+  commit: (force?: boolean) => void
+  update: (data?: Partial<T>) => void
+  clear: () => void
+}
+```
+
+#### `StateSubscriptionOption<T>`
+Configuration for state subscriptions.
+
+```typescript
+interface StateSubscriptionOption<T extends ResourceRecord> {
+  id?: string | string[]        // Specific record IDs to subscribe to
+  _systemId?: string           // System-level subscription identifier
+  query?: ListCriteria         // Query criteria for filtered subscriptions
+  default?: Partial<T>         // Default data for new records
+  listener: StateListener<T>   // Callback function for updates
+}
+```
+
+#### `StateListener<T>`
+Function type for handling state changes.
+
+```typescript
+interface StateListener<T extends ResourceRecord> {
+  (record: StateModel<T>[]): void | Promise<void>
+}
+```
+
+### Factory Functions
+
+#### `createStateResource<R>(alias?: string): StateResource<R>`
+Creates a new state resource with reactive capabilities.
+
+**Parameters:**
+- `alias`: Optional resource alias (defaults to 'state')
+
+**Returns:** StateResource instance with subscription support
+
+#### `appendStateResource<C, T>(ctx: T, alias?: string): T & StateResourceAppend`
+Appends a state resource to an existing context.
+
+**Parameters:**
+- `ctx`: OwlMeans context instance
+- `alias`: Optional resource alias
+
+**Returns:** Context with state resource capabilities
+
+### Core Methods
+
+#### `subscribe(params: StateSubscriptionOption<T>): [() => void, StateModel<T>[]]`
+Subscribes to state changes for specific records or queries.
+
+**Parameters:**
+- `params`: Subscription configuration with listener and criteria
+
+**Returns:** Tuple of [unsubscribe function, current state models]
+
+#### `listen(listener: StateListener<T>): () => void`
+Adds a global listener for all state changes.
+
+**Parameters:**
+- `listener`: Function to handle state changes
+
+**Returns:** Unsubscribe function
+
+#### `erase(): Promise<void>`
+Clears all state data and notifies subscribers.
+
+### State Model Methods
+
+#### `commit(force?: boolean): void`
+Persists model changes to the underlying resource.
+
+#### `update(data?: Partial<T>): void`
+Updates model data and notifies subscribers.
+
+#### `clear(): void`
+Clears model data while maintaining subscription.
+
+### Error Types
+
+#### `StateToolingError`
+Base error for state management tooling issues.
+
+#### `StateListenerError`
+Error related to listener management and execution.
+
+## Usage Examples
+
+### Basic State Subscription
+
+```typescript
+import { createStateResource } from '@owlmeans/state'
+
+interface User extends ResourceRecord {
+  id?: string
+  name: string
+  email: string
+  status: 'active' | 'inactive'
+}
+
+// Create state resource
+const userState = createStateResource<User>('users')
+
+// Subscribe to a specific user
+const [unsubscribe, models] = userState.subscribe({
+  id: 'user123',
+  listener: (models) => {
+    const user = models[0]
+    console.log('User updated:', user.record)
+  }
+})
+
+// Get current state immediately
+if (models.length > 0) {
+  console.log('Current user:', models[0].record)
+}
+
+// Update user data
+models[0].update({ status: 'inactive' })
+models[0].commit()
+
+// Cleanup
+unsubscribe()
+```
+
+### Multiple Record Subscription
+
+```typescript
+// Subscribe to multiple users
+const [unsubscribe, models] = userState.subscribe({
+  id: ['user1', 'user2', 'user3'],
+  listener: (models) => {
+    console.log(`Received updates for ${models.length} users`)
+    models.forEach(model => {
+      console.log(`User ${model.record.id}: ${model.record.name}`)
+    })
+  }
+})
+```
+
+### Query-Based Subscription
+
+```typescript
+// Subscribe to active users
+const [unsubscribe, models] = userState.subscribe({
+  query: {
+    status: 'active',
+    role: ['admin', 'moderator']
+  },
+  listener: (models) => {
+    console.log(`Active admin/moderator users: ${models.length}`)
+  }
+})
+```
+
+### Global State Listening
+
+```typescript
+// Listen to all state changes
+const unsubscribe = userState.listen((models) => {
+  console.log('Global state change detected')
+  // Handle any user state changes
+})
+```
+
+### React Integration Example
+
+```typescript
+import React, { useEffect, useState } from 'react'
+
+const UserProfile: React.FC<{ userId: string }> = ({ userId }) => {
+  const [user, setUser] = useState<StateModel<User> | null>(null)
+
+  useEffect(() => {
+    const [unsubscribe, models] = userState.subscribe({
+      id: userId,
+      default: { name: '', email: '', status: 'active' },
+      listener: (models) => {
+        setUser(models[0] || null)
+      }
+    })
+
+    // Set initial state
+    if (models.length > 0) {
+      setUser(models[0])
+    }
+
+    return unsubscribe
+  }, [userId])
+
+  const handleUpdate = (data: Partial<User>) => {
+    if (user) {
+      user.update(data)
+      user.commit()
+    }
+  }
+
+  if (!user) {
+    return <div>Loading...</div>
+  }
+
+  return (
+    <div>
+      <h2>{user.record.name}</h2>
+      <p>Email: {user.record.email}</p>
+      <p>Status: {user.record.status}</p>
+      <button onClick={() => handleUpdate({ status: 'inactive' })}>
+        Deactivate User
+      </button>
+    </div>
+  )
+}
+```
+
+### Context Integration
+
+```typescript
+import { createBasicContext } from '@owlmeans/context'
+import { appendStateResource } from '@owlmeans/state'
+
+// Create context with state capabilities
+const context = createBasicContext()
+appendStateResource(context, 'user-state')
+
+// Access state resource from context
+const stateResource = context.getStateResource<User>('user-state')
+```
+
+### Bulk Operations
+
+```typescript
+// Subscribe to system-level changes
+const [unsubscribe, models] = userState.subscribe({
+  _systemId: 'bulk-operations',
+  listener: async (models) => {
+    // Handle bulk updates
+    console.log(`Processing ${models.length} records`)
+    
+    // Batch commit changes
+    models.forEach(model => model.commit())
+  }
+})
+
+// Perform bulk updates
+await userState.create({ name: 'User 1', email: 'user1@example.com' })
+await userState.create({ name: 'User 2', email: 'user2@example.com' })
+```
+
+### Default Data Handling
+
+```typescript
+// Subscribe with default data for new records
+const [unsubscribe, models] = userState.subscribe({
+  id: 'new-user',
+  default: {
+    name: 'New User',
+    email: '',
+    status: 'active'
+  },
+  listener: (models) => {
+    const user = models[0]
+    if (!user.record.email) {
+      // User still needs email
+      console.log('User needs email address')
+    }
+  }
+})
+```
+
+### Error Handling
+
+```typescript
+import { StateListenerError } from '@owlmeans/state'
+
+try {
+  const [unsubscribe, models] = userState.subscribe({
+    id: 'user123',
+    listener: async (models) => {
+      // Async listener that might throw
+      await processUserData(models[0].record)
+    }
+  })
+} catch (error) {
+  if (error instanceof StateListenerError) {
+    console.error('Listener error:', error.message)
+  }
+}
+```
+
+## Advanced Features
+
+### Custom Subscription Patterns
+
+```typescript
+// Conditional subscriptions
+const subscribeToUser = (userId: string, condition: (user: User) => boolean) => {
+  return userState.subscribe({
+    id: userId,
+    listener: (models) => {
+      const user = models[0]
+      if (user && condition(user.record)) {
+        // Handle conditional updates
+        console.log('Condition met for user:', user.record.id)
+      }
+    }
+  })
+}
+
+// Subscribe only to active users
+const [unsubscribe] = subscribeToUser('user123', user => user.status === 'active')
+```
+
+### Memory Management
+
+```typescript
+class UserManager {
+  private subscriptions: (() => void)[] = []
+
+  subscribeToUser(userId: string) {
+    const [unsubscribe] = userState.subscribe({
+      id: userId,
+      listener: this.handleUserUpdate.bind(this)
+    })
+    
+    this.subscriptions.push(unsubscribe)
+  }
+
+  cleanup() {
+    // Clean up all subscriptions
+    this.subscriptions.forEach(unsubscribe => unsubscribe())
+    this.subscriptions = []
+  }
+
+  private handleUserUpdate(models: StateModel<User>[]) {
+    // Handle updates
+  }
+}
+```
+
+### Performance Optimization
+
+```typescript
+// Debounced updates
+let updateTimeout: NodeJS.Timeout
+
+const [unsubscribe] = userState.subscribe({
+  id: 'user123',
+  listener: (models) => {
+    clearTimeout(updateTimeout)
+    updateTimeout = setTimeout(() => {
+      // Process updates after debounce
+      console.log('Processing debounced update')
+    }, 100)
+  }
+})
+```
+
+## Integration with OwlMeans Ecosystem
+
+The `@owlmeans/state` package integrates with:
+
+- **@owlmeans/resource**: Built on the resource system for data persistence
+- **@owlmeans/context**: Context-based service registration and access
+- **@owlmeans/client**: React hooks and component integration
+- **@owlmeans/error**: Error handling and reporting
+- **@owlmeans/client-resource**: Client-side resource management
+
+## Best Practices
+
+### Subscription Management
+- Always store unsubscribe functions and call them during cleanup
+- Use specific IDs when possible instead of broad queries
+- Implement proper error handling in listeners
+- Avoid creating subscriptions in render loops
+
+### Performance
+- Use query-based subscriptions for filtered data sets
+- Implement debouncing for high-frequency updates
+- Clean up unused subscriptions promptly
+- Use default data to avoid loading states
+
+### Memory Management
+- Implement proper cleanup in component unmount
+- Use weak references for large object graphs
+- Monitor subscription count in development
+- Clean up system subscriptions when no longer needed
+
+### Error Handling
+- Wrap async listeners in try-catch blocks
+- Implement fallback UI for failed state updates
+- Log subscription errors for debugging
+- Use defensive programming for model access
+
+Fixes #32.

package/build/consts.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_ID = "_default";
+export declare const DEFAULT_ALIAS = "state";
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,UAAU,aAAa,CAAA;AACpC,eAAO,MAAM,aAAa,UAAU,CAAA"}

package/build/consts.js

@@ -0,0 +1,3 @@
+export const DEFAULT_ID = '_default';
+export const DEFAULT_ALIAS = 'state';
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAA;AACpC,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAA"}

package/build/errors.d.ts

@@ -0,0 +1,10 @@
+import { ResourceError } from '@owlmeans/resource';
+export declare class StateToolingError extends ResourceError {
+    static typeName: string;
+    constructor(msg: string);
+}
+export declare class StateListenerError extends StateToolingError {
+    static typeName: string;
+    constructor(msg: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/build/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,qBAAa,iBAAkB,SAAQ,aAAa;IAClD,OAAuB,QAAQ,SAAqC;gBAExD,GAAG,EAAE,MAAM;CAIxB;AAED,qBAAa,kBAAmB,SAAQ,iBAAiB;IACvD,OAAuB,QAAQ,SAA0C;gBAE7D,GAAG,EAAE,MAAM;CAIxB"}

package/build/errors.js

@@ -0,0 +1,18 @@
+import { ResourceError } from '@owlmeans/resource';
+export class StateToolingError extends ResourceError {
+    static typeName = `${ResourceError.typeName}Tooling`;
+    constructor(msg) {
+        super(`tooling:${msg}`);
+        this.type = StateToolingError.typeName;
+    }
+}
+export class StateListenerError extends StateToolingError {
+    static typeName = `${StateToolingError.typeName}Listener`;
+    constructor(msg) {
+        super(`listener:${msg}`);
+        this.type = StateListenerError.typeName;
+    }
+}
+ResourceError.registerErrorClass(StateToolingError);
+ResourceError.registerErrorClass(StateListenerError);
+//# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAC3C,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,SAAS,CAAA;IAEpE,YAAY,GAAW;QACrB,KAAK,CAAC,WAAW,GAAG,EAAE,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC,QAAQ,CAAA;IACxC,CAAC;;AAGH,MAAM,OAAO,kBAAmB,SAAQ,iBAAiB;IAChD,MAAM,CAAU,QAAQ,GAAG,GAAG,iBAAiB,CAAC,QAAQ,UAAU,CAAA;IAEzE,YAAY,GAAW;QACrB,KAAK,CAAC,YAAY,GAAG,EAAE,CAAC,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAA;IACzC,CAAC;;AAGH,aAAa,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,CAAA;AACnD,aAAa,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,5 @@
+export type * from './types.js';
+export * from './consts.js';
+export * from './errors.js';
+export * from './resource.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAE/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/build/index.js

@@ -0,0 +1,4 @@
+export * from './consts.js';
+export * from './errors.js';
+export * from './resource.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/build/resource.d.ts

@@ -0,0 +1,6 @@
+import type { ResourceRecord } from '@owlmeans/resource';
+import type { StateResource, StateResourceAppend } from './types.js';
+import type { BasicContext as Context, BasicConfig as Config } from '@owlmeans/context';
+export declare const createStateResource: <R extends ResourceRecord>(alias?: string) => StateResource<R>;
+export declare const appendStateResource: <C extends Config, T extends Context<C>>(ctx: T, alias?: string) => T & StateResourceAppend;
+//# sourceMappingURL=resource.d.ts.map

package/build/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAgC,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACtF,OAAO,KAAK,EAAiB,aAAa,EAAE,mBAAmB,EAA2B,MAAM,YAAY,CAAA;AAI5G,OAAO,KAAK,EAAE,YAAY,IAAI,OAAO,EAAE,WAAW,IAAI,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAEvF,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,cAAc,UAAS,MAAM,KAAmB,aAAa,CAAC,CAAC,CAuO5G,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,OACnE,CAAC,UAAS,MAAM,KACpB,CAAC,GAAG,mBAWN,CAAA"}