eslint-plugin-saltids

ESLint plugin for prisma-extension-saltids to enforce the transparency principle.

Why This Plugin?

The prisma-extension-saltids plugin is designed to be completely transparent to application code. Application developers should never need to manually handle salt fields (*Salt).

However, it's easy to accidentally break this principle by:

1. Manually setting salt fields when creating records
2. Destructuring salt fields from query results
3. Using salt fields in business logic

This ESLint plugin catches these mistakes at development time.

Installation

npm install --save-dev eslint-plugin-saltids
# or
pnpm add -D eslint-plugin-saltids
# or
yarn add -D eslint-plugin-saltids

Usage

Flat Config (ESLint 9+)

// eslint.config.js
const saltidsPlugin = require('eslint-plugin-saltids');

module.exports = [
  {
    plugins: {
      saltids: saltidsPlugin,
    },
    rules: {
      'saltids/no-manual-salt-assignment': 'error',
    },
  },
];

Legacy Config (.eslintrc)

{
  "plugins": ["saltids"],
  "rules": {
    "saltids/no-manual-salt-assignment": "error"
  }
}

Rules

no-manual-salt-assignment

Disallow manual assignment of salt fields.

❌ Incorrect

// Creating records with manual salt assignment
const newUser = await prisma.user.create({
  data: {
    name: 'John',
    tenantId: tenant.id,
    tenantIdSalt: tenant.idSalt, // ❌ Error!
  },
});

// Destructuring salt fields
const { id, idSalt } = await prisma.tenant.findFirst(); // ❌ Error!

// Assigning to salt fields
user.tenantIdSalt = tenant.idSalt; // ❌ Error!

✅ Correct

// Creating records - only pass virtual ID
const newUser = await prisma.user.create({
  data: {
    name: 'John',
    tenantId: tenant.id, // ✅ Plugin handles the rest
  },
});

// Destructuring without salt fields
const { id, name } = await prisma.tenant.findFirst(); // ✅ Correct

// Salt fields are managed by the plugin
// No manual assignment needed

Options

{
  "saltids/no-manual-salt-assignment": [
    "error",
    {
      // Additional field names to treat as salt fields
      "additionalSaltFields": ["customSaltField"],
      
      // Patterns to ignore (regex strings)
      "ignorePatterns": ["^test.*Salt$"]
    }
  ]
}

additionalSaltFields

Array of additional field names to treat as salt fields. By default, any field ending with Salt is considered a salt field.

ignorePatterns

Array of regex patterns. Field names matching these patterns will not be flagged.

Standalone CLI Tool

This package also includes a standalone CLI tool for scanning projects:

# Scan current directory
npx check-saltids-usage

# Scan specific directory
npx check-saltids-usage ./src

# Or run directly
node node_modules/eslint-plugin-saltids/check-saltids-usage.js ./src

How It Works

The plugin detects:

1. Object literal properties: { tenantIdSalt: value }
2. Member assignment: obj.tenantIdSalt = value
3. Destructuring: const { idSalt } = obj

Any field name ending with Salt is considered a salt field.

Background

When using prisma-extension-saltids:

1. Virtual IDs (saltids) are encoded from physical ID + salt
2. The plugin automatically decodes virtual IDs when writing to the database
3. The plugin automatically encodes physical IDs when reading from the database
4. Application code should only use virtual IDs

Manually setting salt fields bypasses this mechanism and breaks data consistency.

Common Mistakes

Mistake 1: Manually Setting Salt Fields

// ❌ WRONG - This breaks data consistency
const newUser = await prisma.user.create({
  data: {
    name: 'John',
    tenantId: tenant.id,
    tenantIdSalt: tenant.idSalt, // ❌ Don't do this!
  },
});

Result: The database stores the virtual ID (98211) instead of the physical ID (1), breaking foreign key relationships.

Correct Approach

// ✅ CORRECT - Let the plugin handle it
const newUser = await prisma.user.create({
  data: {
    name: 'John',
    tenantId: tenant.id, // Only pass virtual ID
  },
});

Result: The plugin automatically decodes the virtual ID and sets both tenantId = 1 and tenantIdSalt = 9821 in the database.

Related

• prisma-extension-saltids - The Prisma extension this plugin supports
• Prisma - Modern database toolkit

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Ogentx Team