howone 0.1.10 → 0.1.12

package/templates/vite/.howone/skills/howone-sdk/references/02-entity-operations.md

@@ -0,0 +1,379 @@
+# Entity Operations
+
+## Core Concepts
+
+- `client.entity<TRecord, TCreate, TUpdate>(entityName)` creates a typed entity client.
+- `defineEntities({ ... })` groups entity clients.
+- `withEntities(client, entities)` merges them onto the composed client as `howone.entities.*`.
+- All entity calls are **plain async functions** — no hooks, no subscriptions.
+
+---
+
+## Type Definitions
+
+### EntityRecord (base type)
+
+```ts
+type EntityRecord = {
+  id: string
+  createdDate?: string
+  updatedDate?: string
+  createdById?: string
+  isSample?: boolean
+  [key: string]: unknown   // index signature — important for typing
+}
+```
+
+### Defining entity types
+
+Always define all three types explicitly. **Do not** use `Omit<EntityRecord & ...>` for create types — the index signature widens the payload.
+
+```ts
+import { type EntityRecord } from '@howone/sdk'
+
+// ── Story entity ──────────────────────────────────────────────
+export type StoryRecord = EntityRecord & {
+  title: string
+  content: string
+  authorId: string
+  status: 'draft' | 'published' | 'archived'
+  wordCount: number
+  tags: string[]
+  coverUrl?: string
+}
+
+export type StoryCreate = {
+  title: string
+  content: string
+  authorId: string
+  status: 'draft' | 'published' | 'archived'
+  wordCount: number
+  tags?: string[]
+  coverUrl?: string
+}
+
+export type StoryUpdate = Partial<StoryCreate>
+```
+
+### Binding entities
+
+```ts
+import { createClient, defineEntities, withEntities } from '@howone/sdk'
+
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+})
+
+export const entities = defineEntities({
+  Story: client.entity<StoryRecord, StoryCreate, StoryUpdate>('Story'),
+  Comment: client.entity<CommentRecord, CommentCreate, CommentUpdate>('Comment'),
+})
+
+const howone = withEntities(client, entities)
+export default howone
+```
+
+---
+
+## EntityClient API
+
+```ts
+type EntityClient<TRecord, TCreate, TUpdate> = {
+  name: string
+
+  // ── Read ──────────────────────────────────────────────────
+  list(options?: ListOptions): Promise<TRecord[]>
+  query(options?: QueryOptions<TRecord>): Promise<QueryResult<TRecord>>
+  query.mine(options?: QueryOptions<TRecord>): Promise<QueryResult<TRecord>>
+  get(id: string): Promise<TRecord | null>
+  getOrThrow(id: string): Promise<TRecord>
+  aggregate<TResult = unknown>(pipeline: unknown[]): Promise<TResult[]>
+
+  // ── Write ─────────────────────────────────────────────────
+  create(data: TCreate): Promise<TRecord>
+  update(id: string, data: TUpdate): Promise<TRecord>
+  delete(id: string): Promise<DeleteResult>
+  bulkCreate(records: TCreate[], options?: BulkCreateOptions): Promise<TRecord[]>
+}
+
+type DeleteResult = {
+  deleted: boolean
+  id: string
+  message?: string
+  traceId?: string | number
+}
+```
+
+---
+
+## CRUD Examples
+
+### Create
+
+```ts
+const story = await howone.entities.Story.create({
+  title: 'My First Story',
+  content: 'Once upon a time...',
+  authorId: user.id,
+  status: 'draft',
+  wordCount: 4,
+  tags: ['fantasy'],
+})
+// story is fully typed as StoryRecord
+```
+
+### Read — get by ID
+
+```ts
+const story = await howone.entities.Story.get(storyId)
+// Returns StoryRecord | null
+
+const story = await howone.entities.Story.getOrThrow(storyId)
+// Returns StoryRecord, throws if not found
+```
+
+### Update
+
+```ts
+const updated = await howone.entities.Story.update(storyId, {
+  status: 'published',
+  wordCount: 320,
+})
+```
+
+### Delete
+
+```ts
+const result = await howone.entities.Story.delete(storyId)
+// result.deleted === true on success
+```
+
+---
+
+## Querying
+
+### QueryOptions type
+
+```ts
+type QueryOptions<TRecord> = {
+  where?: WhereInput<TRecord>   // field filters
+  search?: string               // full-text search
+  page?: PageInput              // pagination
+  orderBy?: OrderByInput<TRecord> // sorting
+}
+
+type PageInput = { number?: number; size?: number }
+type OrderByInput<TRecord> = Partial<Record<keyof TRecord | string, 'asc' | 'desc'>>
+```
+
+### QueryResult type
+
+```ts
+type QueryResult<TRecord> = {
+  items: TRecord[]
+  page: {
+    number: number
+    size: number
+    total: number
+    totalPages: number
+    hasNext: boolean
+    hasPrev: boolean
+  }
+  traceId?: string | number
+}
+```
+
+### Basic query
+
+```ts
+const result = await howone.entities.Story.query({
+  page: { number: 1, size: 20 },
+  orderBy: { createdDate: 'desc' },
+})
+
+const { items, page } = result
+// items: StoryRecord[]
+// page.total, page.hasNext, etc.
+```
+
+### Search + filter
+
+```ts
+const result = await howone.entities.Story.query({
+  search: 'dragon',
+  where: { status: 'published' },
+  page: { number: 1, size: 10 },
+  orderBy: { wordCount: 'desc' },
+})
+```
+
+### query.mine — only current user's records
+
+```ts
+const myStories = await howone.entities.Story.query.mine({
+  page: { number: 1, size: 20 },
+  orderBy: { updatedDate: 'desc' },
+})
+```
+
+### WhereInput — field operators
+
+```ts
+type FieldOperator<T> = {
+  eq?: T           // exact match (same as plain value)
+  ne?: T           // not equal
+  gt?: T           // greater than
+  gte?: T          // greater than or equal
+  lt?: T           // less than
+  lte?: T          // less than or equal
+  contains?: string // substring (string fields)
+  like?: string     // SQL LIKE pattern
+  startsWith?: string
+  endsWith?: string
+  in?: T[]          // value in array
+  notIn?: T[]       // value not in array
+}
+
+// Examples
+const result = await howone.entities.Story.query({
+  where: {
+    status: 'published',               // plain value = eq
+    wordCount: { gte: 100, lte: 5000 },
+    title: { contains: 'magic' },
+    tags: { in: ['fantasy', 'sci-fi'] },
+  },
+})
+```
+
+---
+
+## list() — Simple Array Read
+
+Use `list()` only for simple reads that don't need pagination metadata.
+
+```ts
+// ListOptions type
+type ListOptions = {
+  page?: number
+  limit?: number
+  sort?: string
+  order?: 'asc' | 'desc'
+  [key: string]: unknown  // pass extra filters as top-level keys
+}
+
+const stories = await howone.entities.Story.list({ limit: 50, sort: 'title' })
+// Returns StoryRecord[]  (no pagination metadata)
+```
+
+---
+
+## Bulk Create
+
+```ts
+const sampleStories = await howone.entities.Story.bulkCreate(
+  [
+    { title: 'Sample 1', content: 'Content 1', authorId: 'sys', status: 'published', wordCount: 10 },
+    { title: 'Sample 2', content: 'Content 2', authorId: 'sys', status: 'published', wordCount: 15 },
+  ],
+  { sample: true }, // mark as sample data
+)
+```
+
+---
+
+## Aggregation
+
+```ts
+// MongoDB-style aggregation pipeline
+const stats = await howone.entities.Story.aggregate<{ _id: string; count: number }>([
+  { $match: { status: 'published' } },
+  { $group: { _id: '$authorId', count: { $sum: 1 } } },
+  { $sort: { count: -1 } },
+  { $limit: 10 },
+])
+```
+
+---
+
+## React Patterns
+
+React integration provides no hooks — use `useEffect` + `useState` or a library like TanStack Query.
+
+### Simple useEffect pattern
+
+```tsx
+import { useEffect, useState } from 'react'
+import howone, { type StoryRecord } from '@/lib/sdk'
+
+function StoryList() {
+  const [stories, setStories] = useState<StoryRecord[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<Error | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    howone.entities.Story.query({ page: { number: 1, size: 20 } })
+      .then(result => { if (!cancelled) setStories(result.items) })
+      .catch(err => { if (!cancelled) setError(err) })
+      .finally(() => { if (!cancelled) setLoading(false) })
+    return () => { cancelled = true }
+  }, [])
+
+  if (loading) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
+  return (
+    <ul>
+      {stories.map(s => <li key={s.id}>{s.title}</li>)}
+    </ul>
+  )
+}
+```
+
+### TanStack Query pattern
+
+```tsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import howone, { type StoryCreate } from '@/lib/sdk'
+
+function useStories(page = 1) {
+  return useQuery({
+    queryKey: ['stories', page],
+    queryFn: () => howone.entities.Story.query({
+      page: { number: page, size: 20 },
+      orderBy: { createdDate: 'desc' },
+    }),
+  })
+}
+
+function useCreateStory() {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (data: StoryCreate) => howone.entities.Story.create(data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['stories'] })
+    },
+  })
+}
+
+function useDeleteStory() {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (id: string) => howone.entities.Story.delete(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['stories'] })
+    },
+  })
+}
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Correct Pattern |
+|---|---|
+| `type StoryCreate = Omit<StoryRecord, 'id' \| 'createdDate'>` | Define `StoryCreate` explicitly with exact fields |
+| `client.entity('Story')` without generics | `client.entity<StoryRecord, StoryCreate, StoryUpdate>('Story')` |
+| Using `list()` when you need pagination | Use `query()` for paginated UIs |
+| Calling `query()` inside render without guarding re-runs | Wrap in `useEffect` with cancellation or use TanStack Query |