eslint-plugin-supabase-services-layer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephentraiforos
+
+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

@@ -0,0 +1,316 @@
+# eslint-plugin-supabase-services-layer
+
+ESLint plugin to enforce services layer architecture pattern in Supabase projects by restricting direct Supabase client imports to configured service directories.
+
+## Why This Plugin?
+
+In Supabase projects using Next.js (or other frameworks), it's a best practice to encapsulate database access and business logic in a services layer. This plugin enforces that pattern by preventing direct imports of Supabase clients outside of designated service directories.
+
+**Benefits:**
+- Centralized business logic
+- Easier testing and mocking
+- Consistent error handling
+- Clear separation of concerns
+- Better code organization
+
+## Installation
+
+```bash
+npm install eslint-plugin-supabase-services-layer --save-dev
+# or
+pnpm add -D eslint-plugin-supabase-services-layer
+# or
+yarn add -D eslint-plugin-supabase-services-layer
+```
+
+## Configuration
+
+Add the plugin to your ESLint configuration:
+
+### Flat Config (eslint.config.js)
+
+```javascript
+import supabaseServicesLayer from 'eslint-plugin-supabase-services-layer';
+
+export default [
+  {
+    plugins: {
+      'supabase-services-layer': supabaseServicesLayer,
+    },
+    rules: {
+      'supabase-services-layer/no-direct-supabase-import': [
+        'error',
+        {
+          allowedPaths: ['lib/services/**', 'supabase/functions/_shared/**'],
+          restrictedImports: ['@/lib/supabase/*', '**/supabase-client'],
+        },
+      ],
+    },
+  },
+];
+```
+
+### Legacy Config (.eslintrc.js)
+
+```javascript
+module.exports = {
+  plugins: ['supabase-services-layer'],
+  rules: {
+    'supabase-services-layer/no-direct-supabase-import': [
+      'error',
+      {
+        allowedPaths: ['lib/services/**', 'supabase/functions/_shared/**'],
+        restrictedImports: ['@/lib/supabase/*', '**/supabase-client'],
+      },
+    ],
+  },
+};
+```
+
+## Rule Options
+
+### `allowedPaths` (array of glob patterns)
+
+Default: `['lib/services/**', 'src/services/**', 'supabase/functions/_shared/**']`
+
+Glob patterns for directories where Supabase client imports are allowed.
+
+**Examples:**
+```javascript
+allowedPaths: [
+  'lib/services/**',      // Allow in lib/services/ and subdirectories
+  'src/db/**',           // Allow in src/db/ and subdirectories
+  'supabase/functions/_shared/**',  // Allow edge function services
+]
+```
+
+### `restrictedImports` (array of glob patterns)
+
+Default: `['@/lib/supabase/*', '**/supabase-client']`
+
+Import patterns to restrict. Supports glob patterns.
+
+**Examples:**
+```javascript
+restrictedImports: [
+  '@/lib/supabase/*',      // Restricts @/lib/supabase/server, client, middleware
+  '**/supabase-client',     // Restricts relative imports to supabase-client files
+  '@supabase/supabase-js', // Restricts direct @supabase/supabase-js imports
+]
+```
+
+### `errorMessage` (string)
+
+Default: `"Supabase client imports are only allowed in services layer. Use service classes instead."`
+
+Custom error message to display when violations are found.
+
+## Examples
+
+### ❌ Incorrect - Direct Import in API Route
+
+```typescript
+// app/api/assessments/route.ts
+import { createClient } from '@/lib/supabase/server'; // ❌ ESLint Error
+
+export async function GET() {
+  const supabase = await createClient();
+  const { data } = await supabase.from('assessments').select('*');
+  return Response.json(data);
+}
+```
+
+### ✅ Correct - Using Service Factory
+
+```typescript
+// app/api/assessments/route.ts
+import { createAssessmentService } from '@/lib/services/server'; // ✅ OK
+
+export async function GET() {
+  const assessmentService = await createAssessmentService();
+  const assessments = await assessmentService.listAssessments();
+  return Response.json(assessments);
+}
+```
+
+### ❌ Incorrect - Direct Import in Edge Function
+
+```typescript
+// supabase/functions/worker/index.ts
+import { createClient } from '../_shared/supabase-client'; // ❌ ESLint Error
+
+Deno.serve(async (req) => {
+  const supabase = createClient();
+  const { data } = await supabase.from('queue').select('*');
+  // ...
+});
+```
+
+### ✅ Correct - Using Edge Function Service
+
+```typescript
+// supabase/functions/worker/index.ts
+import { QueueService } from '../_shared/queue-service'; // ✅ OK
+
+Deno.serve(async (req) => {
+  const queueService = new QueueService(this.supabaseFactory);
+  const jobs = await queueService.getPendingJobs();
+  // ...
+});
+```
+
+### ✅ Allowed - Import in Service File
+
+```typescript
+// lib/services/server/assessment-service.ts
+import { createClient } from '@/lib/supabase/server'; // ✅ OK - in allowed path
+
+export async function createAssessmentService() {
+  const supabase = await createClient();
+  return {
+    async listAssessments() {
+      const { data } = await supabase.from('assessments').select('*');
+      return data;
+    },
+  };
+}
+```
+
+## Common Project Structures
+
+### Next.js with App Router
+
+```javascript
+// eslint.config.js
+export default [
+  {
+    rules: {
+      'supabase-services-layer/no-direct-supabase-import': [
+        'error',
+        {
+          allowedPaths: [
+            'lib/services/**',
+            'supabase/functions/_shared/**',
+          ],
+          restrictedImports: [
+            '@/lib/supabase/*',
+            '**/supabase-client',
+          ],
+        },
+      ],
+    },
+  },
+];
+```
+
+### Monorepo with Multiple Packages
+
+```javascript
+// eslint.config.js
+export default [
+  {
+    rules: {
+      'supabase-services-layer/no-direct-supabase-import': [
+        'error',
+        {
+          allowedPaths: [
+            'packages/api/src/services/**',
+            'packages/shared/src/db/**',
+          ],
+          restrictedImports: [
+            '@my-org/supabase/*',
+            '~/lib/supabase/*',
+          ],
+        },
+      ],
+    },
+  },
+];
+```
+
+### Custom Services Directory
+
+```javascript
+// eslint.config.js
+export default [
+  {
+    rules: {
+      'supabase-services-layer/no-direct-supabase-import': [
+        'error',
+        {
+          allowedPaths: ['src/data-access/**', 'src/api/services/**'],
+          restrictedImports: ['~/supabase-clients/*'],
+        },
+      ],
+    },
+  },
+];
+```
+
+## Troubleshooting
+
+### False Positives in Allowed Paths
+
+If you're getting errors in files that should be allowed:
+
+1. Check your glob patterns match the file path
+2. Use `**` to match subdirectories: `lib/services/**`
+3. Verify the path separator matches your OS (use `/` for cross-platform)
+
+```javascript
+// ❌ Wrong - won't match subdirectories
+allowedPaths: ['lib/services']
+
+// ✅ Correct - matches all subdirectories
+allowedPaths: ['lib/services/**']
+```
+
+### Need to Temporarily Disable
+
+If you need to temporarily allow a violation (not recommended):
+
+```typescript
+// eslint-disable-next-line supabase-services-layer/no-direct-supabase-import
+import { createClient } from '@/lib/supabase/server';
+```
+
+Better approach: Create a service method instead!
+
+### Pattern Not Matching
+
+If your custom patterns aren't working:
+
+1. Ensure patterns use forward slashes: `src/services/**`
+2. Use `*` for single-level matching: `*.ts`
+3. Use `**` for multi-level matching: `lib/**`
+4. Test patterns with [minimatch](https://github.com/isaacs/minimatch#testing)
+
+## Migration Guide
+
+If you're adding this plugin to an existing codebase:
+
+1. Install the plugin
+2. Run ESLint to find all violations
+3. Create service classes for common operations
+4. Refactor code to use services
+5. Re-run ESLint to verify
+
+**Common refactoring patterns:**
+
+- API Routes → Use factory functions from `lib/services/server`
+- Edge Functions → Use service classes with `ISupabaseClientFactory`
+- Components → Use client services from `lib/services/client`
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR.
+
+## Related
+
+- [Supabase Documentation](https://supabase.com/docs)
+- [Next.js App Router](https://nextjs.org/docs/app)
+- [ESLint Plugin Documentation](https://eslint.org/docs/latest/extend/plugins)

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ESLint plugin to enforce services layer architecture in Supabase projects
+ */
+declare const plugin: {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: {
+        'no-direct-supabase-import': import("eslint").Rule.RuleModule;
+    };
+    configs: {
+        recommended: {
+            plugins: string[];
+            rules: {
+                'supabase-services-layer/no-direct-supabase-import': string;
+            };
+        };
+    };
+};
+export default plugin;
+export type { RuleOptions } from './rules/no-direct-supabase-import';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;CAgBX,CAAC;AAEF,eAAe,MAAM,CAAC;AAGtB,YAAY,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const no_direct_supabase_import_1 = __importDefault(require("./rules/no-direct-supabase-import"));
+/**
+ * ESLint plugin to enforce services layer architecture in Supabase projects
+ */
+const plugin = {
+    meta: {
+        name: 'eslint-plugin-supabase-services-layer',
+        version: '1.0.0',
+    },
+    rules: {
+        'no-direct-supabase-import': no_direct_supabase_import_1.default,
+    },
+    configs: {
+        recommended: {
+            plugins: ['supabase-services-layer'],
+            rules: {
+                'supabase-services-layer/no-direct-supabase-import': 'error',
+            },
+        },
+    },
+};
+exports.default = plugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;AAAA,kGAAuE;AAEvE;;GAEG;AACH,MAAM,MAAM,GAAG;IACb,IAAI,EAAE;QACJ,IAAI,EAAE,uCAAuC;QAC7C,OAAO,EAAE,OAAO;KACjB;IACD,KAAK,EAAE;QACL,2BAA2B,EAAE,mCAAsB;KACpD;IACD,OAAO,EAAE;QACP,WAAW,EAAE;YACX,OAAO,EAAE,CAAC,yBAAyB,CAAC;YACpC,KAAK,EAAE;gBACL,mDAAmD,EAAE,OAAO;aAC7D;SACF;KACF;CACF,CAAC;AAEF,kBAAe,MAAM,CAAC"}

package/dist/rules/no-direct-supabase-import.d.ts

@@ -0,0 +1,28 @@
+import { Rule } from 'eslint';
+/**
+ * Rule configuration options
+ */
+export interface RuleOptions {
+    /**
+     * Glob patterns for paths where Supabase client imports are allowed
+     * @default ["lib/services/**", "src/services/**", "supabase/functions/_shared/**"]
+     */
+    allowedPaths?: string[];
+    /**
+     * Import patterns to restrict (supports glob patterns)
+     * @default - See DEFAULT_RESTRICTED_PATTERNS in source
+     */
+    restrictedImports?: string[];
+    /**
+     * Custom error message
+     * @default "Supabase client imports are only allowed in services layer. Use service classes instead."
+     */
+    errorMessage?: string;
+}
+/**
+ * ESLint rule to enforce services layer architecture
+ * Prevents direct Supabase client imports outside configured service directories
+ */
+declare const rule: Rule.RuleModule;
+export default rule;
+//# sourceMappingURL=no-direct-supabase-import.d.ts.map

package/dist/rules/no-direct-supabase-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-direct-supabase-import.d.ts","sourceRoot":"","sources":["../../src/rules/no-direct-supabase-import.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAG9B;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE7B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAgBD;;;GAGG;AACH,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,UAuFhB,CAAC;AAEF,eAAe,IAAI,CAAC"}

package/dist/rules/no-direct-supabase-import.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const minimatch_1 = require("minimatch");
+const DEFAULT_ALLOWED_PATTERNS = [
+    'lib/services/**',
+    'src/services/**',
+    'supabase/functions/_shared/**',
+];
+const DEFAULT_RESTRICTED_PATTERNS = [
+    '@/lib/supabase/*',
+    '**/supabase-client',
+];
+const DEFAULT_ERROR_MESSAGE = 'Supabase client imports are only allowed in services layer. Use service classes instead.';
+/**
+ * ESLint rule to enforce services layer architecture
+ * Prevents direct Supabase client imports outside configured service directories
+ */
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Restrict Supabase client imports to services layer only to enforce layered architecture',
+            recommended: true,
+        },
+        messages: {
+            restrictedImport: '{{errorMessage}}',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    allowedPaths: {
+                        type: 'array',
+                        items: {
+                            type: 'string',
+                        },
+                    },
+                    restrictedImports: {
+                        type: 'array',
+                        items: {
+                            type: 'string',
+                        },
+                    },
+                    errorMessage: {
+                        type: 'string',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    create(context) {
+        const options = context.options[0] || {};
+        const ruleOptions = {
+            allowedPaths: options.allowedPaths || DEFAULT_ALLOWED_PATTERNS,
+            restrictedImports: options.restrictedImports || DEFAULT_RESTRICTED_PATTERNS,
+            errorMessage: options.errorMessage || DEFAULT_ERROR_MESSAGE,
+        };
+        const filename = context.filename;
+        // If no filename provided (e.g., in RuleTester), check if test case
+        // RuleTester passes test cases with filename in the test object
+        if (!filename) {
+            // For RuleTester without explicit filename, allow the check
+            // This handles edge cases in testing
+            return {};
+        }
+        // Check if current file is in an allowed path
+        const isAllowedPath = ruleOptions.allowedPaths.some((pattern) => {
+            const matcher = new minimatch_1.Minimatch(pattern, { dot: true });
+            return matcher.match(filename);
+        });
+        // Skip checking if file is in allowed path
+        if (isAllowedPath) {
+            return {};
+        }
+        return {
+            ImportDeclaration(node) {
+                const importPath = String(node.source.value);
+                // Check if import matches any restricted pattern
+                const isRestricted = ruleOptions.restrictedImports.some((pattern) => {
+                    const matcher = new minimatch_1.Minimatch(pattern);
+                    return matcher.match(importPath);
+                });
+                if (isRestricted) {
+                    context.report({
+                        node,
+                        messageId: 'restrictedImport',
+                        data: {
+                            errorMessage: ruleOptions.errorMessage,
+                        },
+                    });
+                }
+            },
+        };
+    },
+};
+exports.default = rule;
+//# sourceMappingURL=no-direct-supabase-import.js.map

package/dist/rules/no-direct-supabase-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-direct-supabase-import.js","sourceRoot":"","sources":["../../src/rules/no-direct-supabase-import.ts"],"names":[],"mappings":";;AACA,yCAAsC;AAyBtC,MAAM,wBAAwB,GAAG;IAC/B,iBAAiB;IACjB,iBAAiB;IACjB,+BAA+B;CAChC,CAAC;AAEF,MAAM,2BAA2B,GAAG;IAClC,kBAAkB;IAClB,oBAAoB;CACrB,CAAC;AAEF,MAAM,qBAAqB,GACzB,0FAA0F,CAAC;AAE7F;;;GAGG;AACH,MAAM,IAAI,GAAoB;IAC5B,IAAI,EAAE;QACJ,IAAI,EAAE,SAAS;QACf,IAAI,EAAE;YACJ,WAAW,EACT,yFAAyF;YAC3F,WAAW,EAAE,IAAI;SAClB;QACD,QAAQ,EAAE;YACR,gBAAgB,EAAE,kBAAkB;SACrC;QACD,MAAM,EAAE;YACN;gBACE,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,YAAY,EAAE;wBACZ,IAAI,EAAE,OAAO;wBACb,KAAK,EAAE;4BACL,IAAI,EAAE,QAAQ;yBACf;qBACF;oBACD,iBAAiB,EAAE;wBACjB,IAAI,EAAE,OAAO;wBACb,KAAK,EAAE;4BACL,IAAI,EAAE,QAAQ;yBACf;qBACF;oBACD,YAAY,EAAE;wBACZ,IAAI,EAAE,QAAQ;qBACf;iBACF;gBACD,oBAAoB,EAAE,KAAK;aAC5B;SACF;KACF;IAED,MAAM,CAAC,OAAO;QACZ,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACzC,MAAM,WAAW,GAAgB;YAC/B,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,wBAAwB;YAC9D,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,IAAI,2BAA2B;YAC3E,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,qBAAqB;SAC5D,CAAC;QAEF,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QAElC,oEAAoE;QACpE,gEAAgE;QAChE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,4DAA4D;YAC5D,qCAAqC;YACrC,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,8CAA8C;QAC9C,MAAM,aAAa,GAAG,WAAW,CAAC,YAAa,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;YAC/D,MAAM,OAAO,GAAG,IAAI,qBAAS,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;YACtD,OAAO,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;QAEH,2CAA2C;QAC3C,IAAI,aAAa,EAAE,CAAC;YAClB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,OAAO;YACL,iBAAiB,CAAC,IAAI;gBACpB,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAE7C,iDAAiD;gBACjD,MAAM,YAAY,GAAG,WAAW,CAAC,iBAAkB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;oBACnE,MAAM,OAAO,GAAG,IAAI,qBAAS,CAAC,OAAO,CAAC,CAAC;oBACvC,OAAO,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;gBACnC,CAAC,CAAC,CAAC;gBAEH,IAAI,YAAY,EAAE,CAAC;oBACjB,OAAO,CAAC,MAAM,CAAC;wBACb,IAAI;wBACJ,SAAS,EAAE,kBAAkB;wBAC7B,IAAI,EAAE;4BACJ,YAAY,EAAE,WAAW,CAAC,YAAY;yBACvC;qBACF,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;SACF,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,kBAAe,IAAI,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "eslint-plugin-supabase-services-layer",
+  "version": "1.0.0",
+  "description": "ESLint plugin to enforce services layer architecture pattern in Supabase projects by restricting direct Supabase client imports to configured service directories",
+  "keywords": [
+    "eslint",
+    "eslint-plugin",
+    "supabase",
+    "services-layer",
+    "architecture",
+    "layered-architecture",
+    "code-organization",
+    "database",
+    "react",
+    "nextjs"
+  ],
+  "homepage": "https://github.com/itz4blitz/mimir#readme",
+  "bugs": {
+    "url": "https://github.com/itz4blitz/mimir/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itz4blitz/mimir.git",
+    "directory": "packages/eslint-plugin-supabase-services-layer"
+  },
+  "license": "MIT",
+  "author": "Stephentraiforos",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "eslint": ">=9"
+  },
+  "dependencies": {
+    "minimatch": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/minimatch": "^5.1.2",
+    "@typescript-eslint/parser": "^8.55.0",
+    "@typescript-eslint/rule-tester": "^8.55.0",
+    "typescript": "^5",
+    "vitest": "^4.0.14"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint . --config ../../eslint.config.cjs"
+  }
+}