nuxt-auto-crud 2.1.3 → 2.2.0

package/README.md

@@ -13,6 +13,13 @@
 
 ## Installation Guide
 
+### Option A: Starter Template
+```bash
+npx nuxi init -t gh:clifordpereira/nac-starter my-app
+```
+
+### Option B: Manual Installation
+
 ```bash
 bun create nuxt@latest my-app
 npx nuxi module add hub
@@ -21,7 +28,7 @@ bun add -D drizzle-kit@beta
 
 ```
 
-### Configuration
+#### Configuration
 
 Update `nuxt.config.ts`:
 
@@ -38,7 +45,7 @@ export default defineNuxtConfig({
 
 ```
 
-### Schema Definition
+#### Schema Definition
 
 Define your schema in `server/db/schema.ts`:
 
@@ -57,23 +64,25 @@ export const users = sqliteTable('users', {
 ```
 
 ### Generate Migrations and Start Dev Server
+After installing (either option), run the following commands:
 
 ```bash
+cd my-app
 nuxt db generate
 nuxt dev
 
 ```
-> If you encounter `Error: Cannot find module 'typescript'`, run `bun add -D typescript`.
+> If you encounter `Error: Cannot find module 'typescript'`, install it using `bun add -D typescript`.
 
 ---
 
-## 🌐 Dynamic RESTful CRUD endpoints
+## 🌐 Exposed Dynamic RESTful CRUD endpoints
 
 Nb: Endpoints follow the pattern `/api/_nac/:model`.
 
 | Method | Endpoint | Action |
 | --- | --- | --- |
-| **GET** | `/:model` | List records (supports filtering & pagination) |
+| **GET** | `/:model` | List records |
 | **POST** | `/:model` | Create record with Zod validation |
 | **GET** | `/:model/:id` | Fetch single record |
 | **PATCH** | `/:model/:id` | Partial update with validation |
@@ -83,7 +92,7 @@ Nb: Endpoints follow the pattern `/api/_nac/:model`.
 
 | Action | HTTP Method | Endpoint | Example Result |
 | --- | --- | --- | --- |
-| **Fetch All** | `GET` | `/api/_nac/users` | List of all users (paginated) |
+| **Fetch All** | `GET` | `/api/_nac/users` | List of all users |
 | **Create** | `POST` | `/api/_nac/users` | New user record added |
 | **Fetch One** | `GET` | `/api/_nac/users/1` | Details of user with `id: 1` |
 | **Update** | `PATCH` | `/api/_nac/users/1` | Partial update to user `1` |
@@ -154,10 +163,11 @@ Enabling `authentication` in the `autoCrud` config protects all **nac** routes (
 
 | Key | Default | Description |
 | --- | --- | --- |
+| `statusFiltering` | `false` | Enables/disables automatic filtering of records based on the `status` column. |
 | `realtime` | `false` | Enables/disables real-time capabilities. |
 | `auth.authentication` | `true` | Requires a valid session for all NAC routes. |
 | `auth.authorization` | `true` | Enables role/owner-based access checks. |
-| `auth.ownerKey` | `'ownerId'` | The column name used to identify the record creator. |
+| `auth.ownerKey` | `'createdBy'` | The column name used to identify the record creator. |
 | `publicResources` | `{}` | Defines tables and specific columns accessible without auth. |
 | `nacEndpointPrefix` | `'/api/_nac'` | The base path for NAC routes. Access via `useRuntimeConfig().public.autoCrud`. |
 | `schemaPath` | `'server/db/schema'` | Location of your Drizzle schema files. |
@@ -166,11 +176,12 @@ Enabling `authentication` in the `autoCrud` config protects all **nac** routes (
 
 ```typescript
 autoCrud: {
+  statusFiltering: false,
   realtime: false,
   auth: {
     authentication: true,
     authorization: true,
-    ownerKey: 'ownerId', 
+    ownerKey: 'createdBy', 
   },
   publicResources: {
     users: ['id', 'name', 'email'],
@@ -191,16 +202,18 @@ autoCrud: {
 
 ### Automatic Status Filtering
 
-To align with standard application behavior, **nac** automatically filters records if a `status` column exists. By default, it will only return **active** records, reducing boilerplate for soft-state management.
+If `statusFiltering` is enabled, **nac** applies global visibility constraints. When a status column exists, queries are automatically restricted to `active` records. This logic integrates with the authorization layer, allowing users to see their own records (regardless of status) if they possess the `list_active` permission.
 
 ### Ownership & Permissions
 
-While the implementing app handles the authentication layer, **nac** provides a standardized way to enforce record ownership and granular access.
+While the implementing app handles the authentication & authorization layer, **nac** provides a standardized way to enforce record ownership and granular access.
 
 If your middleware populates `event.context.nac` with `resourcePermissions`, **nac** automatically injects the necessary SQL filters.
 
 **Example: Restricting users to their own records**
-If the permissions array includes `'list_own'`, **nac** appends a filter where `ownerCol === userId`.
+If the permissions array includes `'list_own'`, **nac** appends a filter where `ownerKey` (defaulting to `createdBy`) matches the `userId`.
+
+If `list_active` is present, it applies a hybrid OR logic: users can see all active records OR any record they own, regardless of its status.
 
 ```typescript
 // Example: Setting context in your Auth Middleware

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-auto-crud",
   "configKey": "autoCrud",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -8,7 +8,7 @@ const module$1 = defineNuxtModule({
   },
   defaults: {
     // Private config
-    statusFiltering: true,
+    statusFiltering: false,
     realtime: false,
     auth: {
       authentication: false,

package/dist/runtime/server/utils/queries.d.ts

@@ -1,6 +1,7 @@
 import { type Table } from 'drizzle-orm';
 import type { QueryContext } from '../../types/index.js';
 import type { TableWithId } from '../types.js';
+export declare function getVisibilityFilters(table: TableWithId, context?: QueryContext): (import("drizzle-orm").SQL<unknown> | undefined)[];
 /**
  * Fetches rows from the database based on the provided table and context.
  * @param table - The table to query.

package/dist/runtime/server/utils/queries.js

@@ -2,30 +2,49 @@ import { useRuntimeConfig } from "#imports";
 import { db } from "@nuxthub/db";
 import { eq, desc, and, or, getColumns } from "drizzle-orm";
 import { getSelectableFields } from "./modelMapper.js";
-import { DeletionFailedError, InsertionFailedError, RecordNotFoundError, UpdateFailedError } from "../exceptions.js";
+import { DeletionFailedError, InsertionFailedError, RecordNotFoundError, UnauthorizedAccessError, UpdateFailedError } from "../exceptions.js";
 import { pick } from "#nac/shared/utils/helpers";
-export async function nacGetRows(table, context = {}) {
-  const { userId, resourcePermissions } = context;
+export function getVisibilityFilters(table, context = {}) {
+  const isAuthorizationEnabled = useRuntimeConfig().autoCrud.auth?.authorization;
+  const isStatusFilteringEnabled = useRuntimeConfig().autoCrud.statusFiltering;
+  if (!isAuthorizationEnabled && !isStatusFilteringEnabled) return [];
+  const { userId, resourcePermissions = [] } = context;
+  if (isAuthorizationEnabled && resourcePermissions?.includes("list_all")) return [];
   const ownerKey = useRuntimeConfig().autoCrud.auth?.ownerKey || "createdBy";
-  const filters = [];
   const ownerCol = table[ownerKey];
   const statusCol = table.status;
-  if (resourcePermissions?.includes("list")) {
-    if (statusCol && ownerCol) {
-      filters.push(
-        or(
-          eq(statusCol, "active"),
-          eq(ownerCol, Number(userId))
-        )
-      );
-    } else if (statusCol) {
-      filters.push(eq(statusCol, "active"));
+  const filters = [];
+  if (isAuthorizationEnabled && isStatusFilteringEnabled) {
+    if (resourcePermissions?.includes("list_active")) {
+      if (statusCol && ownerCol && userId != null) {
+        filters.push(or(eq(statusCol, "active"), eq(ownerCol, Number(userId))));
+      } else if (statusCol) {
+        filters.push(eq(statusCol, "active"));
+      }
+    } else if (resourcePermissions?.includes("list_own") && ownerCol && userId != null) {
+      filters.push(eq(ownerCol, Number(userId)));
+    }
+  } else if (isStatusFilteringEnabled) {
+    if (statusCol) filters.push(eq(statusCol, "active"));
+  } else if (isAuthorizationEnabled) {
+    if (resourcePermissions?.includes("list_own") && ownerCol && userId != null) {
+      filters.push(eq(ownerCol, Number(userId)));
     }
-  } else if (resourcePermissions?.includes("list_own") && userId && ownerCol) {
-    filters.push(eq(ownerCol, Number(userId)));
+  }
+  return filters;
+}
+function hasAnyListPermissions(context = {}) {
+  const { resourcePermissions = [] } = context;
+  return resourcePermissions?.includes("list_all") || resourcePermissions?.includes("list_active") || resourcePermissions?.includes("list_own");
+}
+export async function nacGetRows(table, context = {}) {
+  const isAuthorizationEnabled = useRuntimeConfig().autoCrud.auth?.authorization;
+  if (isAuthorizationEnabled && !context.isPublic && !hasAnyListPermissions(context)) {
+    throw new UnauthorizedAccessError();
   }
   const fields = getSelectableFields(table, context);
   let query = db.select(fields).from(table).$dynamic();
+  const filters = getVisibilityFilters(table, context);
   if (filters.length > 0) query = query.where(and(...filters));
   return await query.orderBy(desc(table.id)).all();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-auto-crud",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "description": "Dynamic RESTful CRUD APIs for Nuxt without code generation, fully schema-driven.",
   "author": "Cliford Pereira",
   "license": "MIT",