# State Management Standards for Deno

This document outlines the coding standards for state management in Deno applications. It aims to provide a clear and consistent approach to managing application state, data flow, and reactivity, ensuring maintainability, performance, and security.

## 1. Introduction to State Management in Deno

State management is a crucial aspect of any application, especially as complexity grows. In Deno, choosing the right strategy and tools can significantly impact performance, scalability, and developer experience. Unlike the browser environment, Deno gives developers more control over the runtime and access to lower-level APIs. Because of this, the state management solutions often need to be re-evaluated.

This document covers several acceptable approaches, ranging from simple component-level state to more comprehensive solutions for large applications. We advocate for clarity, predictability, and maintainability in managing state.

## 2. Core Principles

* **Single Source of Truth:** Each piece of state should have a single, authoritative source. This avoids inconsistencies and makes debugging easier.

* **Immutability:** Treat state as immutable whenever possible. Modifying state by creating new objects, rather than mutating existing ones, simplifies reasoning about state changes and enables efficient change detection.

* **Explicit Data Flow:** Make data dependencies and state changes explicit and predictable. Avoid implicit or hidden state mutations.

* **Separation of Concerns:** Keep state management logic separate from UI rendering and business logic to improve maintainability and testability.

* **Minimization:** Only store the necessary state. Avoid storing derived or computed values directly, instead calculating them on demand.

## 3. Approaches to State Management

### 3.1. Simple Component-Level State

For smaller components or applications, simple state management techniques can suffice. This involves using variables within a component or module to hold the state.

**Do This:**

* Use "let" or "const" to declare state variables within a component or module.

* Employ simple event handlers or functions to update the state directly.

* Consider using "useState" if integrating with a frontend framework like React (via Fresh).

* For simple data dependencies, consider using computed properties if your framework allows (e.g., Fresh).

**Don't Do This:**

* Avoid creating global variables to store application state directly. This makes the state difficult to track and manage.

* Don't mutate state directly without triggering updates in your UI framework (if applicable). Direct mutation can lead to stale data and unexpected behavior.

* Avoid deeply nested or complex state objects if simpler alternatives exist.

**Example (Vanilla Deno - No Framework Usage):**

"""typescript

// counter.ts

let count = 0;

export function increment() {

count++;

console.log("Count:", count);

// Notify any UI components that are tracking this state (if applicable)

}

export function getCount() {

return count;

}

// main.ts

import { increment, getCount } from "./counter.ts";

increment();

console.log("Current count:", getCount());

"""

**Why:**

Using local variables encapsulates the state within a module, preventing unintended modifications from other parts of the application. Functions like "increment" provide a controlled way to update the state, offering an opportunity to trigger UI updates or other side effects.

**Common Mistakes:**

* Forgetting to export state update functions.

* Modifying state outside its defining module.

### 3.2. Using Signals (Preact Signals, Effector, etc.)

Signals offer a reactive approach to state management where changes to a signal automatically trigger updates in components or other reactive expressions. They are efficient and granular, only updating when the signal's value changes.

**Do This:**

* Choose a signals library suitable for your needs (Preact Signals, Effector, etc.). Preact Signals is well-suited for fine-grained component updates within a Preact/Fresh application.

* Create signals to hold your state values.

* Use computed signals to derive values from other signals.

* Update signals using the ".value" property.

* Utilize effects to perform side effects in response to signal changes.

**Don't Do This:**

* Overuse signals. Not every variable needs to be a signal. Focus on data that requires reactive updates.

* Mutate signal values directly without using the ".value" property.

* Create circular dependencies between computed signals.

**Example (Preact Signals with Deno Fresh):**

"""tsx

// app.tsx (Deno Fresh component)

import { signal, computed } from "@preact/signals";

import { useState } from "preact/hooks";

const count = signal(0);

const doubledCount = computed(() => count.value * 2);

export default function Counter() {

const [localState, setLocalState] = useState(0);

const increment = () => {

count.value++;

};

const incrementLocal = () => {

setLocalState(localState + 1);

}

return (

Count: {count.value}

Doubled Count: {doubledCount.value}

Increment Count

Local State: {localState}

Increment Local State

);

}

"""

**Why:**

Signals provide a more efficient way to update components than traditional virtual DOM diffing. Only components that depend on a changed signal will re-render. Computed signals automatically update when their dependencies change, ensuring values are always consistent.

**Common Mistakes:**

* Forgetting to include "@preact/signals" in your Fresh project. "deno add @preact/signals" solves this.

* Trying to directly modify signal values (e.g. "count = 5;" instead of "count.value = 5;").

* Over-relying on signals for values that don't genuinely need to be reactive, which can lead to unnecessary performance overhead.

### 3.3. Context API (React-like Approach)

The Context API allows you to share state between components without explicitly passing props through every level of the component tree. This is useful for themes, user authentication, or other global state.

**Do This:**

* Create a context using "React.createContext()" (if using React/Preact through Fresh/Islands architecture)

* Create a provider component using "context.Provider" to wrap the part of the application that needs access to the context.

* Access the context value using "React.useContext(context)". (if using React/Preact through Fresh/Islands architecture)

**Don't Do This:**

* Overuse the Context API. It's best suited for data that is used by many components, not for isolated component state.

* Mutate the context value directly within components. Use a separate state management solution (e.g., "useState", signals, or a more robust library) to manage the context value.

**Example (Deno Fresh Context API - note the requirement for React/Preact dependencies):**

"""tsx

// context.ts

import React, { createContext, useState, useContext } from "preact/compat";

interface AuthContextType {

user: string | null;

logout: () => void;

}

const AuthContext = createContext({

user: null,

logout: () => {},

});

export function AuthProvider({ children }: { children: React.ReactNode }) {

const [user, setUser] = useState(null);

const login = (user: string) => {

setUser(user);

};

const logout = () => {

setUser(null);

};

const value: AuthContextType = {

user,

logout,

};

return (

{children}

);

}

export function useAuth() {

return useContext(AuthContext);

}

// _layout.tsx (wrapping the app)

/** @jsx h */

import { h } from 'preact';

import { AuthProvider } from "./context.ts";

export default function Layout({ children }: { children: React.ReactNode }) {

return (

{children}

);

}

// profile.tsx (using the context)

/** @jsx h */

import { h } from 'preact';

import { useAuth } from "./context.ts";

export default function Profile() {

const { user, logout } = useAuth();

if (!user) {

return Please log in.;

}

return (

Logged in as: {user}

Logout

);

}

"""

**Why:**

The Context API simplifies prop drilling and avoids passing props through intermediate components that don't need them. It's also useful for global state that is shared across the entire application.

**Common Mistakes:**

* Creating too many contexts. It's better to group related state into a single context than to create a separate context for each piece of state.

* Not providing a default value for the context. This can lead to errors if a component tries to access the context outside of a provider.

### 3.4. Redux/Flux-like Architectures (with Deno)

For complex applications, consider a Redux/Flux-like architecture, which offers a centralized store, predictable state updates, and unidirectional data flow. There are Deno-specific implementations and libraries built for this.

**Do This:**

* Define a clear and concise state schema for your application.

* Create actions to represent state changes.

* Implement pure reducers to handle actions and update the state immutably.

* Use a middleware system to handle side effects (e.g., API calls).

* Consider using libraries like "deno-redux" or "zustand" (though "zustand" does not follow the Redux pattern strictly, it provides a simplified central store). Evaluate if a full Redux pattern is needed, or if "zustand" is a better, less verbose solution.

**Don't Do This:**

* Mutate the state directly within reducers.

* Perform side effects directly within reducers.

* Create excessively complex reducers. Break them down into smaller, more manageable functions.

**Example (Redux-like Architecture using "zustand"):**

"""typescript

// store.ts

import { create } from 'zustand';

interface BearState {

bears: number;

increase: (by: number) => void;

}

export const useBearStore = create()((set) => ({

bears: 0,

increase: (by) => set((state) => ({ bears: state.bears + by })),

}));

// component.tsx (demonstrating usage - adapted for Deno/Fresh)

import { useBearStore } from "./store.ts";

function MyComponent() {

const bears = useBearStore((state) => state.bears);

const increase = useBearStore((state) => state.increase);

return (

Number of bears: {bears}

increase(1)}>Add a bear

);

}

"""

**Why:**

Redux-like architectures offer a predictable and manageable way to handle complex application state. They promote testability, maintainability, and scalability.

**Common Mistakes:**

* Overcomplicating the store setup and structure.

* Not using TypeScript interfaces for state and actions, leading to type errors.

* Ignoring the unidirectional data flow principle and causing unintended side effects.

### 3.5. Server-Side State Management

Deno also offers the possibility to perform state management on the server. This is essential if you are working with user sessions, database interactions, or caching strategies.

**Do This:**

* Leverage Deno's built-in modules like "Deno.KV". "Deno.KV" provides a durable, low-latency key-value database.

* Utilize caching strategies for frequently accessed data to minimize database queries.

* Consider using libraries like Redis or Memcached for more advanced caching needs.

* Implement proper security measures to protect sensitive data stored on the server.

**Don't Do This:**

* Expose sensitive server-side state directly to the client.

* Store large amounts of data in memory without proper caching and garbage collection.

* Ignore security vulnerabilities related to data storage and retrieval.

**Example (Server-Side State Management with Deno.KV):**

"""typescript

// server.ts

const kv = await Deno.openKv();

async function incrementCounter(key: string) {

const atomicOp = kv.atomic();

const counter = await kv.get([key]);

const currentValue = counter.value || 0;

atomicOp.set([key], currentValue + 1);

const { ok } = await atomicOp.commit();

return ok;

}

// Example Usage

incrementCounter("page_views")

.then((success) => {

if (success) {

console.log("Counter incremented successfully.");

} else {

console.error("Failed to increment counter.");

}

});

// Get the key value

const res = await kv.get(["page_views"])

console.log(res);

//Close the KV store when done

//await kv.close()

"""

**Why:**

Server-side state management allows centralized and secure data storage, reducing client-side dependencies and improving performance by caching frequently accessed data. "Deno.KV" provides a built-in solution, simplifying setup and reducing external dependencies.

**Common Mistakes:**

* Storing sensitive data in plain text.

* Not implementing proper error handling for database operations.

* Ignoring potential race conditions when updating server-side state concurrently.

## 4. Advanced Patterns and Techniques

### 4.1. Functional Reactive Programming (FRP)

FRP combines functional programming with reactive programming to create declarative and composable state management solutions. This can be accomplished via RxJS or similar libraries.

**Do This:**

* Use observables to represent streams of data over time.

* Transform data streams using operators like "map", "filter", and "reduce".

* Combine multiple data streams using operators like "merge", "combineLatest", and "concat".

* Handle side effects using subscriptions.

**Don't Do This:**

* Create excessively complex observable chains that are difficult to understand and debug.

* Ignore potential memory leaks by not unsubscribing from observables when they are no longer needed.

### 4.2. Event Sourcing

Event sourcing involves persisting the state of an application as a sequence of events. The current state can be derived by replaying these events. This provides an audit trail and enables time-travel debugging. This approach often works very well with "Deno.KV" for persisting the events.

**Do This:**

* Define a clear and concise event schema for your application.

* Store events in an append-only log (e.g., a database table).

* Replay events to derive the current state.

* Use snapshots to optimize the replay process for long event streams.

**Don't Do This:**

* Mutate existing events.

* Store derived state directly in the event log.

## 5. Specific Considerations for Deno

* **Permissions:** Deno's permission system should be explicitly considered when dealing with server-side state. Ensure the necessary permissions are granted for accessing databases, the file system, or other resources.

* **Module Resolution:** Be mindful of Deno's module resolution when organizing state management logic. Use explicit imports and exports to clearly define dependencies and avoid naming conflicts.

* **Top-Level Await:** Use top-level "await" with caution. Ensure that any asynchronous initializations of state or connections to data sources are handled correctly to avoid blocking the application's startup.

* **ESM (ECMAScript Modules):** Deno is designed around ESM, so ensure your state management code is fully compatible and takes advantage of ESM's benefits.

## 6. Conclusion

Choosing the right state management approach in Deno depends on the complexity of your application. Start with simple techniques for smaller projects and consider more robust solutions like Redux or FRP for larger, more complex applications. By following the principles and standards outlined in this document, you can ensure that your Deno applications are maintainable, performant, and secure. Always remember clarity, predictability, and immutability as cornerstones of effective state management.

Cline

This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.

Overview

The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.

Key Concepts

Purpose of .clinerules

Defines project-specific guidelines and requirements
Enforces consistent coding standards
Establishes documentation practices
Sets testing and quality requirements
Configures error handling preferences

File Location

Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.

Rule Structure

1. Project Overview

# Project Overview
project:
  name: 'Your Project Name'
  description: 'Brief project description'
  stack:
    - technology: 'Framework/Language'
      version: 'X.Y.Z'
    - technology: 'Database'
      version: 'X.Y.Z'

2. Code Standards

# Code Standards
standards:
  style:
    - 'Use consistent indentation (2 spaces)'
    - 'Follow language-specific naming conventions'
  documentation:
    - 'Include JSDoc comments for all functions'
    - 'Maintain up-to-date README files'
  testing:
    - 'Write unit tests for all new features'
    - 'Maintain minimum 80% code coverage'

3. Security Rules

# Security Guidelines
security:
  authentication:
    - 'Implement proper token validation'
    - 'Use environment variables for secrets'
  dataProtection:
    - 'Sanitize all user inputs'
    - 'Implement proper error handling'

Best Practices

Writing Effective Rules

Be Specific
- Use clear, actionable language
- Provide examples where helpful
- Define measurable criteria
Maintain Organization
- Group related rules together
- Use consistent formatting
- Keep critical rules at the top
Regular Updates
- Review rules periodically
- Update based on team feedback
- Document changes in version control

Common Patterns

# Common Patterns Example
patterns:
  components:
    - pattern: 'Use functional components by default'
    - pattern: 'Implement error boundaries for component trees'
  stateManagement:
    - pattern: 'Use React Query for server state'
    - pattern: 'Implement proper loading states'

Integration with Development Workflow

Using with Version Control

Commit the Rules
- Include .clinerules in version control
- Document rule changes in commit messages
- Review rule changes as part of PR process
Team Collaboration
- Discuss rule changes with team
- Maintain changelog for rule updates
- Ensure all team members understand rules

Troubleshooting

Common Issues

Rules Not Being Applied
- Verify file location (must be in root directory)
- Check file formatting
- Ensure Cline has access to the file
Conflicting Rules
- Review rule hierarchy
- Resolve conflicts explicitly
- Document rule precedence
Performance Considerations
- Keep rules concise and focused
- Avoid overly complex rule structures
- Regular cleanup of obsolete rules

Examples

Basic Project Setup

# Basic .clinerules Example
project:
  name: 'Web Application'
  type: 'Next.js Frontend'
  standards:
    - 'Use TypeScript for all new code'
    - 'Follow React best practices'
    - 'Implement proper error handling'

testing:
  unit:
    - 'Jest for unit tests'
    - 'React Testing Library for components'
  e2e:
    - 'Cypress for end-to-end testing'

documentation:
  required:
    - 'README.md in each major directory'
    - 'JSDoc comments for public APIs'
    - 'Changelog updates for all changes'

Advanced Configuration

# Advanced .clinerules Example
project:
  name: 'Enterprise Application'
  compliance:
    - 'GDPR requirements'
    - 'WCAG 2.1 AA accessibility'

architecture:
  patterns:
    - 'Clean Architecture principles'
    - 'Domain-Driven Design concepts'

security:
  requirements:
    - 'OAuth 2.0 authentication'
    - 'Rate limiting on all APIs'
    - 'Input validation with Zod'

State Management Standards for Deno

Cline

Overview

Key Concepts

Purpose of .clinerules

File Location

Rule Structure

1. Project Overview

2. Code Standards

3. Security Rules

Best Practices

Writing Effective Rules

Common Patterns

Integration with Development Workflow

Using with Version Control

Troubleshooting

Common Issues

Examples

Basic Project Setup

Advanced Configuration

Related Rules

Security Best Practices Standards for Deno

Code Style and Conventions Standards for Deno

Performance Optimization Standards for Deno

Component Design Standards for Deno

API Integration Standards for Deno