vibeorm 1.1.5 → 1.1.6

package/README.md

@@ -1063,6 +1063,122 @@ const db = VibeClient({
 
 ---
 
+## Views
+
+Views let you define **named, read-only projections** that restrict which fields are returned per model. They provide:
+
+- **SQL-level restriction** -- only view-defined fields appear in `SELECT` clauses
+- **Zod safety net** -- a derived schema strips any extra fields post-query
+- **`reveal` keyword** -- explicitly opt-in to extra fields that are excluded from `JSON.stringify` by default
+- **Serialization safety** -- revealed fields are accessible as normal properties but excluded from JSON output
+
+### Defining a view
+
+```ts
+const publicApi = db.defineView({
+  name: "public-api",
+  definition: {
+    user: { id: true, name: true, createdAt: true },
+    post: { id: true, title: true, createdAt: true },
+  },
+});
+```
+
+The `definition` is type-safe -- only valid model names and scalar field names are accepted.
+
+### Reading through a view
+
+Views expose only read operations (`findMany`, `findFirst`, `findUnique`, `findUniqueOrThrow`, `findFirstOrThrow`, `count`, `aggregate`, `groupBy`). Write operations (`create`, `update`, `delete`, etc.) are not available -- use the original `db` client for writes.
+
+```ts
+// Only returns { id, name, createdAt } per user
+const users = await publicApi.user.findMany();
+
+// Where, orderBy, pagination all work normally
+const admins = await publicApi.user.findMany({
+  where: { role: "ADMIN" },
+  orderBy: { createdAt: "desc" },
+  take: 10,
+});
+
+// select narrows within view fields
+const names = await publicApi.user.findMany({
+  select: { id: true, name: true },
+});
+// Type: { id: number; name: string | null }[]
+```
+
+### Relations are restricted too
+
+When you `include` a relation, its fields are also restricted by the view definition:
+
+```ts
+const users = await publicApi.user.findMany({
+  include: { posts: true },
+});
+// users[0].posts → [{ id, title, createdAt }] — only post view fields
+```
+
+If a relation's model is **not** in the view definition, it returns all fields as usual.
+
+### Revealing extra fields
+
+Use `reveal` to access fields outside the view. Revealed fields are accessible as normal properties but **excluded from `JSON.stringify()`** -- preventing accidental data leaks in API responses.
+
+```ts
+const user = await publicApi.user.findUniqueOrThrow({
+  where: { id: 1 },
+  reveal: { email: true },
+});
+
+user.id;                    // number (view field)
+user.name;                  // string | null (view field)
+user.email;                 // string (revealed -- accessible)
+
+JSON.stringify(user);       // { "id": 1, "name": "Alice", "createdAt": "..." }
+                            // email is excluded from serialization
+
+user.$unsafe();             // { id, name, createdAt, email } -- escape hatch
+```
+
+The `reveal` keyword also works on nested relations:
+
+```ts
+const users = await publicApi.user.findMany({
+  include: {
+    posts: { reveal: { content: true } },
+  },
+});
+// posts[0].content is accessible but excluded from JSON.stringify
+```
+
+### Type safety
+
+The view system is fully type-safe at compile time:
+
+```ts
+const view = db.defineView({
+  name: "restricted",
+  definition: { user: { id: true, email: true } },
+});
+
+// select only allows view fields
+await view.user.findMany({ select: { id: true } });        // OK
+await view.user.findMany({ select: { role: true } });       // Type error -- role not in view
+
+// reveal only allows non-view fields
+await view.user.findMany({ reveal: { name: true } });       // OK
+await view.user.findMany({ reveal: { id: true } });         // Type error -- id is already in view
+
+// Write operations are not available
+await view.user.create({ data: { email: "x" } });           // Type error -- no create on view
+
+// Models not in the definition are not accessible
+await view.post.findMany();                                  // Type error -- post not in view
+```
+
+---
+
 ## Adapters
 
 ### `@vibeorm/adapter-bun` (recommended)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeorm",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "CLI for VibeORM — generate clients, run migrations, introspect databases",
   "license": "MIT",
   "keywords": [
@@ -41,10 +41,10 @@
     "bun": ">=1.1.0"
   },
   "dependencies": {
-    "@vibeorm/parser": "1.1.3",
-    "@vibeorm/generator": "1.1.4",
-    "@vibeorm/migrate": "1.1.3",
-    "@vibeorm/runtime": "1.1.3",
-    "@vibeorm/adapter-bun": "1.1.3"
+    "@vibeorm/parser": "1.1.4",
+    "@vibeorm/generator": "1.1.5",
+    "@vibeorm/migrate": "1.1.4",
+    "@vibeorm/runtime": "1.1.4",
+    "@vibeorm/adapter-bun": "1.1.4"
   }
 }