npm - comwit - Versions diffs - 0.0.1 → 0.0.2 - Mend

comwit 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025 meursyphus
+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 CHANGED Viewed

@@ -1 +1,297 @@
-TODO
+# comwit
+State management for Next.js.
+> Give this document to Claude Code. It sets up your project.
+## 1. Install
+```bash
+npm i comwit
+```
+## 2. Setup Provider
+Create `app/providers.tsx` and wrap your root layout.
+```tsx
+// app/providers.tsx
+'use client'
+import { useRouter } from 'next/navigation'
+import { keepPreviousData, MuchaProvider } from 'comwit'
+import { ReactNode } from 'react'
+type AppContext = {
+  router: { push: (href: string) => void }
+}
+export function Providers({ children }: { children: ReactNode }) {
+  const router = useRouter()
+  const context: AppContext = { router }
+  return (
+    <MuchaProvider
+      context={context}
+      defaultOptions={{
+        query: {
+          staleTime: 30_000,
+          cacheTime: 120_000,
+          gcTime: 180_000,
+          placeholderData: keepPreviousData,
+        },
+      }}
+    >
+      {children}
+    </MuchaProvider>
+  )
+}
+```
+```tsx
+// app/layout.tsx
+import { Providers } from './providers'
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+```
+## 3. Create `state/.ai.md`
+Create `src/state/.ai.md` (or `state/.ai.md`) with the full content below.
+## 4. Update `CLAUDE.md`
+Add this to your project's `CLAUDE.md`:
+```md
+## State Management
+This project uses comwit. When working on files in state/, always read state/.ai.md first.
+```
+---
+## state/.ai.md Content
+Copy everything between the ````fences into your`state/.ai.md`:
+````md
+## Structure
+```
+state/{domain}/
+  ├── types.ts          # State + Actions types
+  ├── model.ts          # model() with initial state
+  ├── actions/
+  │   ├── crud.ts       # CRUD operations
+  │   ├── load.ts       # Data fetching via query()
+  │   ├── init.ts       # SSR hydration via silent()
+  │   └── ...           # One file per concern
+  └── index.ts          # create() hook + re-exports
+```
+Write order: **types.ts -> model.ts -> actions/\*.ts -> index.ts**
+## Rules
+- Dependencies: pages → state → api (one way)
+- Pass domain objects whole: `<Card post={post} />`
+## File Templates
+### types.ts
+**Read this file first.** JSDoc on each field/method guides the implementation.
+- `Query<Data>` for client-fetched fields — provides `.data` `.isLoading` `.isError` `.error`
+- `Query<Data, Arg>` — second generic = queryFn param type
+- Plain types for SSR-hydrated fields
+```ts
+import { Query } from 'comwit'
+export type Post = { id: string; ... }
+export type PostState = {
+  posts: Query<Post[]>              // client fetch
+  comments: Query<Comment[], string> // client fetch, second generic = queryFn arg
+  current: Post | null               // SSR hydrated
+  // ...
+}
+export type PostActions = {
+  /** @description Fetch posts via query() */
+  loadPosts(): Promise<void>
+  /** @description Toggle like. Optimistic on list + current, toast on error */
+  like(postId: string): Promise<void>
+  // ...
+}
+```
+### model.ts
+`Query<T>` fields use `query()` with `initialData` + `queryFn`. Plain fields get default values.
+```ts
+import { model, query } from 'comwit'
+export const post = model<PostState>({
+  posts: query<Post[]>({ initialData: [], queryFn: () => api.post.findAll() }),
+  comments: query<Comment[], string>({
+    initialData: [],
+    queryFn: (postId) => api.comment.findAll(postId),
+  }),
+  current: null,
+})
+```
+### actions/\*.ts
+Actions are self-contained — resolve state via `state()`, side effects via decorators/context. UI only calls.
+```ts
+import { action, silent, OnError, OnSuccess } from 'comwit'
+import { user } from '@/state/user/model'
+export const postActions = action<Pick<PostActions, '...'>, AppContext>(({ state, context }) => {
+  class PostActions {
+    private model = state(post)
+    private user = state(user) // cross-domain — read other model directly
+    // SSR hydrate — silent() suppresses re-render
+    init(data: Post) {
+      silent(() => {
+        this.model.current = data
+      })
+    }
+    async loadPosts() {
+      await this.model.posts.query()
+    }
+    // guard: check auth from user domain, not from params
+    @OnSuccess(() => context.router.push('/posts'))
+    @OnError((e) => toast.error(e instanceof Error ? e.message : 'Failed'))
+    async create(title: string) {
+      if (!this.user.me) return
+      const created = await api.post.create({ userId: this.user.me.id, title })
+      this.model.posts.data.push(created)
+    }
+  }
+  return new PostActions()
+})
+```
+The pattern above can be automated with `createInterceptor`. See [Decorators](#decorators) below.
+```ts
+// reusable guard — state() must be initialized in the factory body
+const LoginRequired = createInterceptor<AppContext>(({ state, context }) => {
+  const u = state(user)
+  return onAuthorized({
+    when: () => Boolean(u.me),
+    onDeny: () => context.router.push('/login'),
+  })
+})
+// replaces the manual if (!this.user.me) check above:
+@LoginRequired
+@OnSuccess(() => context.router.push('/posts'))
+async create(title: string) { /* ... */ }
+```
+```tsx
+// call init outside useEffect — silent() makes it safe
+function PostDetail({ initialPost }: { initialPost: Post }) {
+  const { actions } = usePost((s) => ({ actions: s.actions }))
+  actions.init(initialPost)
+  return <Article />
+}
+```
+### index.ts
+```ts
+import { create } from 'comwit'
+import type { PostState, PostActions } from './types'
+import { post } from './model'
+import { postActions } from './actions/crud'
+export const usePost = create<PostState, PostActions>(post, {
+  actions: [postActions /* ... */],
+})
+```
+## query() Reference
+Methods: `.query(arg?)` · `.refetch()` · `.set(data)` · `.nextFetch()` · `.previousFetch()`
+Flags: `isLoading` · `isFetching` · `isSuccess` · `isError` · `error`
+Infinite-only flags: `cursor` · `hasMore` (nextFetch is no-op when `hasMore` is false)
+Options: `staleTime` · `cacheTime` · `gcTime` · `placeholderData` · `force`
+`queryFn` receives `(arg, context)` where `context.state` is a readonly snapshot of the current query state (includes `data`, `cursor`, etc.).
+Infinite scroll — use `Query.Infinite<T>` + `query.infinite()`:
+```ts
+// types
+trending: Query.Infinite<Post[]>
+// model — cursor-based pagination
+trending: query.infinite<Post[]>({
+  initialData: [],
+  queryFn: (_, { state }) => api.post.trending(state.cursor),
+})
+// action
+async loadMoreTrending() { await this.model.trending.nextFetch() }
+```
+## Usage
+```tsx
+const { posts, current, actions } = usePost((s) => ({
+  posts: s.posts, // Query<Post[]> — has .data .isLoading .isError
+  current: s.current, // Post | null — plain state
+  actions: s.actions,
+}))
+// query fields — check flags, access data via .data
+if (posts.isLoading) return <Skeleton />
+if (posts.isError) return <p>Error: {posts.error}</p>
+return posts.data.map((post) => <Card key={post.id} post={post} />)
+```
+Selectors use deep equality — only re-renders when selected values change.
+## Decorators
+All from `'comwit'`. Stack on class methods.
+| Decorator                       | Purpose                                               |
+| ------------------------------- | ----------------------------------------------------- |
+| `@OnError(fn)`                  | Error handler. Re-throw to propagate.                 |
+| `@OnSuccess(fn)`                | Success callback.                                     |
+| `@Debounce(ms)`                 | Debounce.                                             |
+| `@Throttle(ms)`                 | Throttle.                                             |
+| `@Authorized({ when, onDeny })` | Auth guard. `when: () => boolean \| Promise<boolean>` |
+`createInterceptor(({ state, context }) => MethodDecorator)` — reusable decorator with `state`/`context` access, like action factories. See [actions](#actionsts) above for usage.
+## Key Concepts
+- `model(initial)` — global reactive store
+- `action(factory)` — factory with `state`/`context` access
+- `create(model, { actions })` — model + actions -> React hook
+- `silent(fn)` — suppress re-renders (SSR)
+- `query()` / `query.infinite()` — client fetch in model
+- `state(model)` — mutable proxy in actions
+````

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "comwit",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "private": false,
   "homepage": "https://comwit.io",
   "repository": {
@@ -14,7 +14,25 @@
     "access": "public"
   },
   "type": "module",
-  "description": "LLM-friendly React state helper library.",
+  "description": "React state management for vibe coding. Less tokens. Built for Claude Code.",
+  "keywords": [
+    "react",
+    "state-management",
+    "vibe-coding",
+    "claude-code",
+    "llm",
+    "next.js",
+    "valtio",
+    "zustand",
+    "tanstack-query",
+    "oop",
+    "proxy"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "meursyphus",
   "main": "dist/comwit.cjs",
   "module": "dist/comwit.js",
   "types": "dist/index.d.ts",
@@ -27,7 +45,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "dev": "vite build --watch",