@warlock.js/core 4.0.174 → 4.1.2

package/skills/use-model-transformers/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: use-model-transformers
+description: 'Three schema-side helpers — `useHashedPassword()` (bcrypt on save) attaches via `.addTransformer(...)`; `useComputedSlug(field?, scope?)` (auto-slug from another field) and `useComputedModel(callback)` (arbitrary computed-on-save value) attach via `v.computed(...)`. Triggers: `useHashedPassword`, `useComputedSlug`, `useComputedModel`, `.addTransformer`, `v.computed`, `ComputedCallback`; "auto-hash a password field", "auto-slug from title on save", "derive a value at write time", "declarative model transformers"; typical import `import { useHashedPassword, useComputedSlug } from "@warlock.js/core"`. Skip: bcrypt setup details — `@warlock.js/core/hash-password/SKILL.md`; repository writes — `@warlock.js/core/use-repository/SKILL.md`; output filtering — `@warlock.js/core/define-resource/SKILL.md`; competing patterns: manual `await hashPassword(input)` in services, ORM lifecycle hooks.'
+---
+
+# Warlock — declare model transformers
+
+Three helpers in `@warlock.js/core` plug into Seal schemas to compute or mutate a field at write time. They sit between "controllers + services" (the mutable-input layer) and "the database row" (the stored state) — so the value the DB sees is always derived, even if the caller didn't think about it.
+
+| Helper | Job | Attaches via | Behavior |
+| --- | --- | --- | --- |
+| `useHashedPassword()` | bcrypt-hash a password field on save | `.addTransformer(useHashedPassword())` on the field | Hash on new row; hash on change; pass through on no-change |
+| `useComputedSlug(field?, scope?)` | Derive a slug from another field | `v.computed(useComputedSlug("title"))` | Compute on every save where the source field is set |
+| `useComputedModel(callback)` | Any custom derived value | `v.computed(useComputedModel(...))` | Runs your callback with `(data, model, context)` |
+
+All three are imported from `@warlock.js/core` (despite living in `src/database/utils.ts` under the hood).
+
+**Why the split:** `useHashedPassword()` returns a Seal `TransformerCallback` (built via cascade's `useModelTransformer`), so it mutates the field's own value through `.addTransformer(...)`. `useComputedSlug()` / `useComputedModel()` return a Seal `ComputedCallback` (signature `(data, context)`) — those are wired with the `v.computed(...)` field validator, **not** `.addTransformer(...)`. Passing a computed helper to `.addTransformer(...)` is wrong: the second argument shapes differ (`{ options, context }` vs bare `context`), so it misbehaves at runtime.
+
+## The shape
+
+```ts title="src/app/users/models/user/user.model.ts"
+import { useHashedPassword } from "@warlock.js/core";
+import { type Infer, v } from "@warlock.js/seal";
+
+export const userSchema = v.object({
+  email: v.email().unique("User"),
+  password: v.string().requiredIfEmpty("id").addTransformer(useHashedPassword()),
+});
+
+export type UserSchema = Infer<typeof userSchema>;
+```
+
+```ts title="src/app/articles/models/article/article.model.ts"
+import { useComputedSlug } from "@warlock.js/core";
+import { type Infer, v } from "@warlock.js/seal";
+
+export const articleSchema = v.object({
+  title: v.string(),
+  slug: v.computed(useComputedSlug("title")),
+});
+
+export type ArticleSchema = Infer<typeof articleSchema>;
+```
+
+Two attachments, two completely different behaviors — `useHashedPassword()` rides on `.addTransformer(...)` (it mutates the field), while `useComputedSlug()` rides on `v.computed(...)` (it derives the field).
+
+## `useHashedPassword()` — bcrypt on save
+
+```ts
+password: v.string().addTransformer(useHashedPassword()),
+```
+
+What it does at save time:
+
+| Situation                       | Behavior                                    |
+| ------------------------------- | ------------------------------------------- |
+| New row, password set           | Hash the value before insert.               |
+| Existing row, password changed  | Re-hash the new value.                      |
+| Existing row, password unchanged | Pass through (no re-hashing — stored hash preserved). |
+| Empty / undefined value         | Pass through untouched.                     |
+
+Calls `authService.hashPassword(String(value))` under the hood — same bcryptjs path as the standalone `hashPassword()` helper. See [`hash-password/SKILL.md`](../hash-password/SKILL.md) for full bcrypt setup (salt rounds, `yarn add bcryptjs`).
+
+### Why declarative wins
+
+Without the transformer, every code path that writes a password has to remember:
+
+```ts
+await User.create({
+  email: input.email,
+  password: await hashPassword(input.password),  // easy to forget
+});
+```
+
+Forget the hash once — even in a one-off seed or admin tool — and you've stored plaintext. The transformer makes the wrong thing impossible: the field can only end up hashed, no matter who wrote it.
+
+Pass plaintext to `User.create({ password: input.password })` and the transformer handles the rest.
+
+## `useComputedSlug(field?, scope?)` — auto-slug from another field
+
+```ts
+slug: v.computed(useComputedSlug("title")),
+```
+
+- **`field`** *(default `"title"`)* — the source field name to slugify.
+- **`scope`** — `"sibling"` *(default)* or `"global"`. `"sibling"` reads `data[field]` from the same object being saved; `"global"` reads `get(context.allValues, field)` (the root context — useful in nested schemas where the source field lives on a parent).
+
+What it does:
+
+| Situation                          | Behavior                                   |
+| ---------------------------------- | ------------------------------------------ |
+| Source field has a value           | Return `slugify(value)` — overwrite the slug. |
+| Source field is empty / undefined  | Return `model.get(field)` — i.e. the model's existing value for the **source** field (e.g. the stored `title`), not the existing slug. |
+
+So if a caller sets `title: "Hello World"` without touching `slug`, the saved row has `slug: "hello-world"`. If they explicitly set `slug: "custom-handle"` AND leave `title` populated, the computed field **still overwrites** with the slugified title — because the source value is set. (Note the empty-source fallback returns `model.get(field)` keyed by the *source* field name, not the slug — a quirk of the implementation; if `title` is also empty on the model you get whatever the source field holds, which may be `undefined`.)
+
+To allow explicit slug overrides, branch in your service before calling save, or skip the transformer for that one save (model-level mutation).
+
+```ts title="example service — letting the transformer slug"
+await Article.create({
+  title: "Hello World",
+  // slug auto-derived → "hello-world"
+});
+```
+
+```ts title="example service — manual slug, bypassing"
+const article = new Article();
+article.set("title", "Hello World");
+article.set("slug", "my-custom-handle");
+// The transformer still fires and overwrites — to truly bypass,
+// store the slug on a separate non-transformed field instead.
+await article.save();
+```
+
+The slug uses `@mongez/slug` under the hood — sensible defaults (lowercase, hyphenated, ASCII transliteration).
+
+## `useComputedModel(callback)` — arbitrary derived values
+
+The general-purpose computed-value helper. Use it when the value depends on the row in non-trivial ways:
+
+```ts
+import { useComputedModel } from "@warlock.js/core";
+
+slug: v.computed(useComputedModel((data, model, context) => {
+  // data    — the current schema-level input object
+  // model   — the Model instance being saved
+  // context — Seal's SchemaContext (allValues, rootContext, etc.)
+
+  return `${data.category}-${slugify(data.title)}`;
+})),
+```
+
+`useComputedSlug` is implemented on top of `useComputedModel` — they share the same signature. Reach for `useComputedSlug` for the common slug case; reach for `useComputedModel` when you need to combine fields, branch on env, or call out to a service.
+
+### Signature
+
+```ts
+type ComputedCallbackModel = (
+  data: any,         // the schema input being saved
+  model: Model,      // the Cascade model instance
+  context: SchemaContext,
+) => any | Promise<any>;
+```
+
+The callback can be async — return a `Promise<T>` and the schema layer awaits it.
+
+## Patterns
+
+### Hash + computed slug on the same model
+
+```ts
+export const userSchema = v.object({
+  email: v.email().unique("User"),
+  password: v.string().requiredIfEmpty("id").addTransformer(useHashedPassword()),
+  display_name: v.string(),
+  handle: v.computed(useComputedSlug("display_name")),
+});
+```
+
+The two attachment kinds coexist — `password` mutates via `.addTransformer(...)`, `handle` derives via `v.computed(...)`. Each fires at save time, independent of the other.
+
+### Derived total from line items
+
+```ts
+total: v.computed(useComputedModel((data) => {
+  const items = (data.items as Array<{ price: number; quantity: number }>) ?? [];
+  return items.reduce((sum, it) => sum + it.price * it.quantity, 0);
+})),
+```
+
+Whenever `items` is part of the save payload, `total` is overwritten with the computed sum. Callers literally can't set `total` to a wrong value.
+
+### Conditional compute
+
+```ts
+status: v.computed(useComputedModel((data, model) => {
+  // First save → "draft"
+  if (!model.id) return "draft";
+  // Subsequent saves → leave the existing status alone
+  return model.get("status");
+})),
+```
+
+Use the `model` argument to branch on "is this a new row or an update."
+
+### Multi-locale slugs
+
+```ts
+slug_en: v.computed(useComputedSlug("title_en")),
+slug_ar: v.computed(useComputedSlug("title_ar")),
+```
+
+One computed field per locale. Cleaner than juggling multi-locale logic in `useComputedModel`.
+
+## When NOT to use a transformer
+
+Transformers live at the **schema layer** — they fire on every `create()` / `save()`. They're not the right tool when:
+
+- **The derived value depends on side effects** (an API call, external lookup, time-bounded data). Do that in a service; service code is testable and observable. A transformer that calls an external API on every save is hard to reason about.
+- **You need conditional skipping by caller intent.** Transformers run unconditionally based on the schema. A service-side mutation lets the caller opt in / out per call.
+- **The "compute" requires reading other rows.** Possible (await DB lookups), but it puts query latency on the save path. Often better to compute upstream and pass the value in.
+
+Rule of thumb: transformers are for **pure, deterministic** transforms of the row's own fields. Hashing, slugifying, summing, normalizing — yes. Cross-row lookups, network calls, audit-side effects — no.
+
+## Gotchas
+
+- **All three are imported from `@warlock.js/core`.** They live in `src/database/utils.ts` internally, but the public surface is the core package. `.addTransformer(...)` and `v.computed(...)` are Seal's APIs, but these helpers are Warlock's — don't reach into `@warlock.js/cascade` or `@warlock.js/seal` for them.
+- **Match the attachment to the helper.** `useHashedPassword()` → `.addTransformer(...)` (it's a `TransformerCallback`). `useComputedSlug()` / `useComputedModel()` → `v.computed(...)` (they're `ComputedCallback`s). Cross-wiring them is a runtime bug, not just a type error.
+- **`useHashedPassword` only re-hashes on actual change.** It returns the value unchanged when `!isNew && !isChanged`, where `isChanged` comes from the model's dirty tracking (`model.isDirty(column)`). Save an already-stored hash and the field isn't marked dirty, so it isn't re-hashed.
+- **`useComputedSlug` overwrites unconditionally when the source field is present.** Set both `title` and `slug` in one save — the slug derived from `title` wins. When the source is empty it falls back to `model.get(field)` keyed by the **source** field name (not the slug field). To allow user-customized slugs, keep them on a separate field that isn't computed.
+- **Computed callbacks run through the save pipeline.** A slow callback (an external API call) blocks every save. Keep them fast and deterministic. They may be async — `v.computed`'s validator awaits the result.
+- **`v.computed(...)` is the write-time computed field.** The value is computed during validation and persisted on the row. There is no separate `.compute()` method on a field — `useComputedSlug` / `useComputedModel` produce the `ComputedCallback` you hand to `v.computed(...)`.
+
+## See also
+
+- [`hash-password/SKILL.md`](../hash-password/SKILL.md) — the bcrypt setup that `useHashedPassword` calls under the hood; salt rounds, `yarn add bcryptjs`.
+- [`use-repository/SKILL.md`](../use-repository/SKILL.md) — where `create` / `save` calls happen that trigger the transformers.
+- [`define-resource/SKILL.md`](../define-resource/SKILL.md) — filtering transformed fields (`password`) out of API responses.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — schema files live in `src/app/<module>/models/<entity>/<entity>.model.ts`.

package/skills/use-repository/SKILL.md

@@ -0,0 +1,393 @@
+---
+name: use-repository
+description: 'Subclass `RepositoryManager` for data access — declare `source`, `filterBy`, `defaultOptions`, then call `list()`/`listCached()`/`find()`/`create()`/`update()`/`delete()` (and the active/cached/cursor variants). Triggers: `RepositoryManager`, `FilterRules`, `RepositoryOptions`, `.list`, `.listCached`, `.find`, `.findCached`, `.create`, `.update`, `.delete`, `simpleSelectColumns`; "create a repository", "filter rules for a list endpoint", "cursor vs page pagination", "cached vs uncached read"; typical import `import { RepositoryManager } from "@warlock.js/core"`. Skip: cache singleton — `@warlock.js/cache/cache-basics/SKILL.md`; use-case pipelines — `@warlock.js/core/write-use-case/SKILL.md`; wire mapping — `@warlock.js/core/define-resource/SKILL.md`; competing libs `typeorm` Repository, `prisma.client.<model>`, `@nestjs/typeorm`.'
+---
+
+# Warlock — use a repository
+
+A repository is a thin wrapper around a Cascade model that centralizes filtering, pagination, and caching. You subclass `RepositoryManager<TModel, TFilter>`, declare `source`/`filterBy`/`defaultOptions`, export a singleton, and call its methods from services. Controllers never touch repositories directly.
+
+## The shape
+
+```ts title="src/app/faqs/repositories/faqs.repository.ts"
+import type { FilterRules, RepositoryOptions } from "@warlock.js/core";
+import { RepositoryManager } from "@warlock.js/core";
+import { Faq } from "../models/faq";
+
+type FaqListFilter = {
+  ids?: string[];
+  id?: string;
+  organization_id?: string;
+  project_id?: string;
+  status?: string;
+};
+
+export type FaqListOptions = RepositoryOptions & FaqListFilter;
+
+class FaqsRepository extends RepositoryManager<Faq, FaqListOptions> {
+  public source = Faq;
+
+  public simpleSelectColumns: string[] = ["id"];
+
+  public filterBy: FilterRules = {
+    id: "=",
+    ids: ["in", "id"],
+    organization_id: "=",
+    project_id: "=",
+    status: "=",
+  };
+
+  public defaultOptions: RepositoryOptions = {
+    orderBy: { id: "desc" },
+  };
+}
+
+export const faqsRepository = new FaqsRepository();
+```
+
+Five lines do the heavy lifting:
+
+1. **`source = Faq`** — Cascade model the repo wraps; auto-instantiates a `CascadeAdapter`.
+2. **`simpleSelectColumns`** — projection used when callers pass `simpleSelect: true`.
+3. **`filterBy`** — filter-key → operator map; powers the auto-applied WHERE clauses.
+4. **`defaultOptions`** — applied to every call (`orderBy`, default `limit`, etc.).
+5. **`new FaqsRepository()`** singleton — import this everywhere; never instantiate again.
+
+The class is intentionally private — only the singleton escapes the module. Scaffold with `yarn warlock generate.repository <module>/<entity>`.
+
+## The `filterBy` rules
+
+A `FilterRules` map. Keys are filter input names; values are operators or `[operator, column]` tuples (when the input name differs from the column):
+
+```ts
+public filterBy: FilterRules = {
+  // input "id" → WHERE id = ?
+  id: "=",
+
+  // input "ids" → WHERE id IN (?)
+  ids: ["in", "id"],
+
+  // input "name" → WHERE name LIKE %?%
+  name: "like",
+
+  // input "price_min" → WHERE price >= ?
+  price_min: ["int>=", "price"],
+
+  // input "createdBetween" → WHERE created_at BETWEEN ? AND ?
+  createdBetween: ["dateBetween", "created_at"],
+
+  // custom — full control
+  search: (value, query, ctx) => {
+    query.where((qb) => {
+      qb.where("name", "like", value).orWhere("description", "like", value);
+    });
+  },
+};
+```
+
+Operators (from `@warlock.js/core/src/repositories/contracts/types.ts`, `FilterOperator`):
+
+- SQL-style: `=`, `!=`, `<>`, `>`, `>=`, `<`, `<=`, `like`, `not like`, `in`, `not in`, `between`, `not between`
+- Typed coercion: `int`, `int>`, `int>=`, `int<`, `int<=`, `inInt`, `!int`, `integer`, `float`, `double`, `inFloat`, `number`, `inNumber`, `bool`, `boolean`, `null`, `notNull`, `!null`
+- Dates: `date`, `date>`, `date>=`, `date<`, `date<=`, `dateBetween`, `inDate`, `dateTime`, `dateTime>`, `dateTime>=`, `dateTime<`, `dateTime<=`, `dateTimeBetween`, `inDateTime`
+- Special: `location`, `scope`, `with`, `joinWith`, `similarTo`
+
+For custom logic, pass a function: `(value, query, context) => void` — mutate `query` directly with the query-builder API.
+
+## Method surface
+
+From `@warlock.js/core/src/repositories/repository.manager.ts`. Every method has an `…Active` counterpart that adds the active-record filter (`isActive = true`), and most have a `…Cached` counterpart that reads/writes through the cache layer.
+
+### Finding
+
+```ts
+await repo.find(id);                       // by primary key (or model instance)
+await repo.findBy(column, value);
+await repo.first(options?);                // first matching `options`
+await repo.firstId(options?);              // → id only
+await repo.exists(options?);               // → boolean
+await repo.idExists(id);                   // → boolean
+await repo.last(options?);                 // orderBy id desc
+
+await repo.findCached(id);                 // alias of getCached
+await repo.getCached(id);
+await repo.getCachedBy(column, value);
+await repo.firstCached(options?);
+
+await repo.findActive(id);
+await repo.firstActive(options?);
+await repo.firstActiveCached(options?);
+```
+
+### Listing
+
+```ts
+// Page-based (default)
+const { data, pagination } = await repo.list({ page: 2, limit: 10, status: "active" });
+
+// Cursor-based
+const { data, pagination } = await repo.list({
+  paginationMode: "cursor",
+  limit: 20,
+  cursor: lastSeenId,
+  direction: "next",
+});
+
+await repo.all(options?);                  // unpaginated array
+await repo.listActive(options?);
+await repo.listCached(options?);           // page-based + cache
+await repo.allCached(options?);
+await repo.latest(options?);               // orderBy id desc + paginate
+await repo.oldest(options?);
+```
+
+### Pagination shape
+
+```ts
+// page-based — repo.list({ page, limit })
+type PaginationResult<T> = {
+  data: T[];
+  pagination: {
+    limit: number;
+    result: number; // count in this page
+    page: number; // 1-indexed
+    total: number; // total rows
+    pages: number; // total pages
+  };
+};
+
+// cursor-based — repo.list({ paginationMode: "cursor", cursor, limit })
+type CursorPaginationResult<T> = {
+  data: T[];
+  pagination: {
+    limit: number;
+    result: number;
+    hasMore: boolean;
+    nextCursor?: string | number;
+    prevCursor?: string | number;
+  };
+};
+```
+
+### CRUD
+
+```ts
+await repo.create(data); // → created model
+await repo.update(id, data); // → updated model
+await repo.delete(id); // → void
+
+await repo.updateMany(filter, data); // → number affected
+await repo.deleteMany(filter); // → number affected
+
+await repo.findOrCreate(where, data);
+await repo.updateOrCreate(where, data);
+```
+
+### Counting
+
+```ts
+await repo.count(options?);                // → number
+await repo.countActive(options?);
+await repo.countCached(options?);
+```
+
+### Chunking
+
+```ts
+await repo.chunk(500, async (rows, index) => {
+  // process 500 at a time; return false to stop early
+});
+
+await repo.chunkActive(500, async (rows, index) => {});
+```
+
+### Cache control
+
+```ts
+await repo.clearCache(); // wipe all repo cache
+await repo.clearCache({ id: 5 });
+await repo.clearModelCache(model);
+await repo.cacheModel(model); // manual cache write
+```
+
+## Cached vs uncached
+
+`listCached` / `firstCached` / `getCached` etc. hit the cache layer (`@warlock.js/cache`) first; on miss, they execute and cache. Cache invalidation is automatic on `create`/`update`/`delete` events that the adapter listens to.
+
+Use cached methods by default. Drop to uncached when:
+
+- The data changes too fast for the cache TTL to be useful.
+- You need transactional consistency with a write you just made (cache invalidation runs after the event fires; a read in the same tick may still hit stale).
+- Diagnosing a cache-related bug.
+
+```ts
+// Default — go through cache
+await faqsRepository.listCached({ organization_id, status: "published" });
+
+// Diagnostic / write-then-read flow — bypass cache
+await faqsRepository.list({ organization_id, status: "published" });
+```
+
+## Calling from a service
+
+```ts title="src/app/faqs/services/list-faqs.service.ts"
+import { faqsRepository, type FaqListOptions } from "../repositories/faqs.repository";
+
+export async function listFaqsService(filters: FaqListOptions) {
+  return faqsRepository.listCached(filters);
+}
+```
+
+```ts title="src/app/faqs/controllers/list-faqs.controller.ts"
+import type { RequestHandler, Response } from "@warlock.js/core";
+import { listFaqsService } from "../services/list-faqs.service";
+
+export const listFaqsController: RequestHandler = async (request, response: Response) => {
+  const { data, pagination } = await listFaqsService({
+    ...request.all(),
+    organization_id: request.user.organizationId,
+  });
+
+  return response.success({ data, pagination });
+};
+```
+
+## When to drop to `Model.query()`
+
+Repositories are for the 90% case: filter, paginate, cache. For anything beyond — joins, aggregates, raw expressions, complex `OR` trees — drop to the model's query builder inside a service:
+
+```ts title="src/app/orders/services/order-stats.service.ts"
+import { Order } from "../models/order";
+
+export async function orderStatsByMonth(organizationId: string) {
+  return Order.query()
+    .where("organization_id", organizationId)
+    .groupBy(Order.query().raw("DATE_TRUNC('month', created_at)"))
+    .select([
+      Order.query().raw("DATE_TRUNC('month', created_at) as month"),
+      Order.query().raw("COUNT(*) as count"),
+      Order.query().raw("SUM(total) as revenue"),
+    ])
+    .get();
+}
+```
+
+A repository method exposing `query()` is also fine for service-level shaping:
+
+```ts
+class OrdersRepository extends RepositoryManager<Order> {
+  public source = Order;
+
+  public async paidLastWeek(organizationId: string) {
+    return this.newQuery()
+      .where({ organization_id: organizationId, status: "paid" })
+      .where("created_at", ">", new Date(Date.now() - 7 * 86_400_000))
+      .get();
+  }
+}
+```
+
+`this.newQuery()` returns a fresh `QueryBuilderContract` for the underlying source — no cache, no filter rules, just SQL.
+
+## Repository lifecycle hooks
+
+Override in the subclass for cross-cutting behavior:
+
+```ts
+class ProductsRepository extends RepositoryManager<Product> {
+  public source = Product;
+
+  protected async onCreate(product: Product, data: any) {
+    await searchIndex.add(product);
+  }
+
+  protected async onUpdate(product: Product, data: any) {
+    await searchIndex.update(product);
+  }
+
+  protected async onDelete(id: string | number) {
+    await searchIndex.remove(id);
+  }
+}
+```
+
+Available hooks: `beforeListing`, `onList`, `onCreating`, `onCreate`, `onUpdating`, `onUpdate`, `onSaving`, `onSave`, `onDeleting`, `onDelete`. They run inside the repository's adapter — no need to wire events manually.
+
+## Common patterns
+
+### Typed list filter
+
+The second generic on `RepositoryManager` makes `options.<filter>` autocomplete from the caller side:
+
+```ts
+type ProductListFilter = {
+  category_id?: string;
+  price_min?: number;
+  price_max?: number;
+  in_stock?: boolean;
+};
+
+export type ProductListOptions = RepositoryOptions & ProductListFilter;
+
+class ProductsRepository extends RepositoryManager<Product, ProductListOptions> {
+  public source = Product;
+
+  public filterBy: FilterRules = {
+    category_id: "=",
+    price_min: ["int>=", "price"],
+    price_max: ["int<=", "price"],
+    in_stock: ["bool", "is_in_stock"],
+  };
+}
+
+// Caller side — typed
+await productsRepository.list({ category_id, price_min: 10, in_stock: true });
+```
+
+### `simpleSelect` for lightweight payloads
+
+```ts
+class UsersRepository extends RepositoryManager<User> {
+  public source = User;
+  public simpleSelectColumns = ["id", "name", "email"];
+}
+
+await usersRepository.list({ simpleSelect: true });
+// only id, name, email selected
+```
+
+### Custom filter function
+
+```ts
+public filterBy: FilterRules = {
+  search: (value, query) => {
+    query.where((qb) => {
+      qb.where("name", "like", `%${value}%`)
+        .orWhere("description", "like", `%${value}%`)
+        .orWhere("sku", "=", value);
+    });
+  },
+};
+```
+
+The third arg is a context object — `{ allValues, dateFormat, ... }` — for filters that compose with other inputs.
+
+## Gotchas
+
+- **One singleton per repository.** Module-export `new FaqsRepository()` at the bottom; everyone imports that. Event listeners are wired on construction — instantiating twice double-registers them.
+- **Don't access protected members from outside.** `defaultOptions`, `filterBy`, `cacheDriver`, `name` are `protected` for a reason. Configure via subclass; never reach in.
+- **`cursor` pagination owns its sort key.** If you pass `paginationMode: "cursor"` _and_ an `orderBy: { id: "asc" }` that conflicts with the cursor column, the framework warns and ignores your `orderBy`. Use cursor pagination's `direction` and `cursorColumn` options instead.
+- **`listCached` only supports page-based pagination.** Cursor mode bypasses the cache.
+- **`findCached` is an alias of `getCached`.** Both look up by `id` through the cache. There is no `findCachedBy` — use `getCachedBy(column, value)`.
+- **`create`/`update`/`delete` clear cache on every write.** That's why `listCached` is usually safe. If you write outside the repository (raw query, bulk insert), the cache won't invalidate — call `repo.clearCache()` manually.
+- **The repository owns `clearCache` per repo + per model.** It doesn't reach into other repositories. If a write in one module affects another's cache, invalidate explicitly from a service.
+- **Adapter init is `setTimeout(0)` delayed.** Don't call repository methods synchronously inside the constructor — they'll fire before the adapter is ready.
+
+## See also
+
+- [`create-module/SKILL.md`](../create-module/SKILL.md) — `warlock generate.repository` and where the file lives.
+- [`@warlock.js/cache/cache-basics/SKILL.md`](../../../cache/skills/cache-basics/SKILL.md) — the cache singleton behind `listCached` / `getCached`. See sibling skills (`pick-cache-driver`, `use-swr`) for related tasks.
+- [`write-use-case/SKILL.md`](../write-use-case/SKILL.md) — calling repositories from a use-case handler.
+- [`define-resource/SKILL.md`](../define-resource/SKILL.md) — mapping repository output to the wire format.
+- [`create-controller/SKILL.md`](../create-controller/SKILL.md) — services that consume repositories from the controller edge.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — controller → service → repository → model layering.