autoworkflow 3.1.5 → 3.5.0

package/.claude/skills/sequelize.md

@@ -0,0 +1,395 @@
+# Sequelize Skill
+
+## Configuration
+\`\`\`typescript
+import { Sequelize } from 'sequelize';
+
+const sequelize = new Sequelize(process.env.DATABASE_URL!, {
+  dialect: 'postgres',
+  logging: process.env.NODE_ENV === 'development' ? console.log : false,
+  pool: {
+    max: 10,
+    min: 0,
+    acquire: 30000,
+    idle: 10000,
+  },
+  define: {
+    timestamps: true, // Adds createdAt, updatedAt
+    underscored: true, // Uses snake_case column names
+    paranoid: true, // Soft deletes (deletedAt)
+  },
+});
+
+// Test connection
+await sequelize.authenticate();
+\`\`\`
+
+## Model Definition (TypeScript)
+\`\`\`typescript
+import {
+  Model, DataTypes, InferAttributes, InferCreationAttributes,
+  CreationOptional, ForeignKey, NonAttribute, Association
+} from 'sequelize';
+
+class User extends Model<InferAttributes<User>, InferCreationAttributes<User>> {
+  declare id: CreationOptional<number>;
+  declare email: string;
+  declare name: string;
+  declare password: string;
+  declare role: 'user' | 'admin';
+  declare createdAt: CreationOptional<Date>;
+  declare updatedAt: CreationOptional<Date>;
+  declare deletedAt: CreationOptional<Date | null>;
+
+  // Associations
+  declare posts?: NonAttribute<Post[]>;
+  declare static associations: {
+    posts: Association<User, Post>;
+  };
+
+  // Instance methods
+  async comparePassword(candidate: string): Promise<boolean> {
+    return bcrypt.compare(candidate, this.password);
+  }
+}
+
+User.init({
+  id: {
+    type: DataTypes.INTEGER,
+    autoIncrement: true,
+    primaryKey: true,
+  },
+  email: {
+    type: DataTypes.STRING(255),
+    allowNull: false,
+    unique: true,
+    validate: {
+      isEmail: true,
+      notEmpty: true,
+    },
+  },
+  name: {
+    type: DataTypes.STRING(100),
+    allowNull: false,
+  },
+  password: {
+    type: DataTypes.STRING,
+    allowNull: false,
+  },
+  role: {
+    type: DataTypes.ENUM('user', 'admin'),
+    defaultValue: 'user',
+  },
+  createdAt: DataTypes.DATE,
+  updatedAt: DataTypes.DATE,
+  deletedAt: DataTypes.DATE,
+}, {
+  sequelize,
+  tableName: 'users',
+  indexes: [
+    { fields: ['email'] },
+    { fields: ['role', 'created_at'] },
+  ],
+});
+
+class Post extends Model<InferAttributes<Post>, InferCreationAttributes<Post>> {
+  declare id: CreationOptional<number>;
+  declare title: string;
+  declare content: string | null;
+  declare published: boolean;
+  declare authorId: ForeignKey<User['id']>;
+  declare author?: NonAttribute<User>;
+}
+
+Post.init({
+  id: {
+    type: DataTypes.INTEGER,
+    autoIncrement: true,
+    primaryKey: true,
+  },
+  title: {
+    type: DataTypes.STRING,
+    allowNull: false,
+  },
+  content: DataTypes.TEXT,
+  published: {
+    type: DataTypes.BOOLEAN,
+    defaultValue: false,
+  },
+}, { sequelize, tableName: 'posts' });
+\`\`\`
+
+## Associations
+\`\`\`typescript
+// One-to-Many
+User.hasMany(Post, {
+  foreignKey: 'authorId',
+  as: 'posts',
+  onDelete: 'CASCADE',
+});
+Post.belongsTo(User, {
+  foreignKey: 'authorId',
+  as: 'author',
+});
+
+// Many-to-Many
+User.belongsToMany(Role, {
+  through: 'user_roles',
+  as: 'roles',
+});
+Role.belongsToMany(User, {
+  through: 'user_roles',
+  as: 'users',
+});
+
+// One-to-One
+User.hasOne(Profile, {
+  foreignKey: 'userId',
+  as: 'profile',
+});
+Profile.belongsTo(User, {
+  foreignKey: 'userId',
+  as: 'user',
+});
+\`\`\`
+
+## Query Patterns
+\`\`\`typescript
+import { Op } from 'sequelize';
+
+// Find operations
+const user = await User.findByPk(id);
+const user = await User.findOne({ where: { email } });
+const users = await User.findAll({ where: { role: 'user' } });
+
+// With eager loading
+const users = await User.findAll({
+  where: { role: 'user' },
+  include: [{
+    model: Post,
+    as: 'posts',
+    where: { published: true },
+    required: false, // LEFT JOIN
+  }],
+  order: [['createdAt', 'DESC']],
+  limit: 20,
+  offset: 0,
+});
+
+// Complex conditions with operators
+const users = await User.findAll({
+  where: {
+    [Op.and]: [
+      { role: 'user' },
+      { createdAt: { [Op.gte]: new Date('2024-01-01') } },
+      {
+        [Op.or]: [
+          { email: { [Op.like]: '%@company.com' } },
+          { name: { [Op.startsWith]: 'Admin' } },
+        ],
+      },
+    ],
+  },
+});
+
+// Count and exists
+const count = await User.count({ where: { role: 'user' } });
+const exists = await User.findOne({ where: { email } }) !== null;
+
+// Select specific attributes
+const users = await User.findAll({
+  attributes: ['id', 'email', 'name'],
+  // Or exclude: attributes: { exclude: ['password'] }
+});
+
+// Aggregations
+const stats = await User.findAll({
+  attributes: [
+    'role',
+    [sequelize.fn('COUNT', sequelize.col('id')), 'count'],
+  ],
+  group: ['role'],
+});
+\`\`\`
+
+## Create, Update, Delete
+\`\`\`typescript
+// Create
+const user = await User.create({
+  email: 'user@example.com',
+  name: 'John',
+  password: await bcrypt.hash('password', 10),
+});
+
+// Bulk create
+const users = await User.bulkCreate([
+  { email: 'user1@example.com', name: 'User 1' },
+  { email: 'user2@example.com', name: 'User 2' },
+], { validate: true });
+
+// Update
+await user.update({ name: 'Jane' });
+
+// Or bulk update
+const [affectedCount] = await User.update(
+  { role: 'admin' },
+  { where: { id: userId } }
+);
+
+// Upsert
+const [user, created] = await User.upsert({
+  email: 'user@example.com',
+  name: 'Updated Name',
+});
+
+// Delete (soft delete if paranoid: true)
+await user.destroy();
+
+// Hard delete
+await user.destroy({ force: true });
+
+// Restore soft-deleted
+await user.restore();
+\`\`\`
+
+## Scopes
+\`\`\`typescript
+class User extends Model {
+  static associate(models) {
+    // Define associations
+  }
+}
+
+User.init({ /* ... */ }, {
+  sequelize,
+  scopes: {
+    active: {
+      where: { deletedAt: null },
+    },
+    admins: {
+      where: { role: 'admin' },
+    },
+    withPosts: {
+      include: [{ model: Post, as: 'posts' }],
+    },
+    recent(days: number) {
+      return {
+        where: {
+          createdAt: {
+            [Op.gte]: new Date(Date.now() - days * 24 * 60 * 60 * 1000),
+          },
+        },
+      };
+    },
+  },
+});
+
+// Usage
+const activeAdmins = await User.scope(['active', 'admins']).findAll();
+const recentUsers = await User.scope({ method: ['recent', 7] }).findAll();
+\`\`\`
+
+## Transactions
+\`\`\`typescript
+// Managed transaction (auto commit/rollback)
+const result = await sequelize.transaction(async (t) => {
+  const user = await User.create({ email, name }, { transaction: t });
+
+  await Post.create({
+    title: 'Welcome Post',
+    authorId: user.id,
+  }, { transaction: t });
+
+  return user;
+});
+
+// Unmanaged transaction
+const t = await sequelize.transaction();
+try {
+  const user = await User.create({ email, name }, { transaction: t });
+  await Post.create({ title, authorId: user.id }, { transaction: t });
+  await t.commit();
+} catch (error) {
+  await t.rollback();
+  throw error;
+}
+
+// Transaction isolation levels
+await sequelize.transaction({
+  isolationLevel: Transaction.ISOLATION_LEVELS.SERIALIZABLE,
+}, async (t) => {
+  // ...
+});
+\`\`\`
+
+## Hooks
+\`\`\`typescript
+User.init({ /* ... */ }, {
+  sequelize,
+  hooks: {
+    beforeCreate: async (user) => {
+      if (user.password) {
+        user.password = await bcrypt.hash(user.password, 10);
+      }
+    },
+    beforeUpdate: async (user) => {
+      if (user.changed('password')) {
+        user.password = await bcrypt.hash(user.password, 10);
+      }
+    },
+    afterDestroy: async (user) => {
+      await Post.destroy({ where: { authorId: user.id } });
+    },
+  },
+});
+
+// Or add hooks after
+User.addHook('beforeValidate', 'trimFields', (user) => {
+  if (user.email) user.email = user.email.trim().toLowerCase();
+});
+\`\`\`
+
+## Migrations
+\`\`\`bash
+# Create migration
+npx sequelize-cli migration:generate --name add-user-role
+
+# Run migrations
+npx sequelize-cli db:migrate
+
+# Rollback
+npx sequelize-cli db:migrate:undo
+\`\`\`
+
+\`\`\`typescript
+// migrations/20240101000000-add-user-role.js
+module.exports = {
+  async up(queryInterface, Sequelize) {
+    await queryInterface.addColumn('users', 'role', {
+      type: Sequelize.ENUM('user', 'admin'),
+      defaultValue: 'user',
+    });
+    await queryInterface.addIndex('users', ['role']);
+  },
+
+  async down(queryInterface) {
+    await queryInterface.removeColumn('users', 'role');
+  },
+};
+\`\`\`
+
+## ❌ DON'T
+- Use \`sync({ force: true })\` in production
+- Forget to handle N+1 queries (use include/eager loading)
+- Use \`findAll()\` without pagination on large tables
+- Put business logic in models
+- Skip transactions for multi-model operations
+
+## ✅ DO
+- Use migrations for schema changes
+- Use TypeScript with proper typing
+- Use scopes for reusable query logic
+- Use transactions for related operations
+- Use paranoid mode for soft deletes
+- Define proper associations with aliases
+- Use hooks for side effects