@slango/mangusta 1.0.0

package/src/middleware/compactId.spec.ts

@@ -0,0 +1,98 @@
+import { setupMongoTestEnvironment } from '@slango.configs/vitest/helpers/mongooseTestEnvironment';
+import mongoose, { Document, model, Schema } from 'mongoose';
+import { describe, expect, it } from 'vitest';
+
+import { PluginFunction } from '../types.js';
+import compactIdMiddleware, { CompactIdMiddlewareOptions, WithCompactId } from './compactId.js';
+
+setupMongoTestEnvironment();
+
+type TestDoc<Field extends string = 'shortId'> = Document & WithCompactId<Field>;
+
+const createTestModel = <Field extends string = 'shortId'>(
+  options?: CompactIdMiddlewareOptions<Field>,
+) => {
+  const modelName = 'TestDoc';
+
+  if (mongoose.models[modelName]) {
+    delete mongoose.models[modelName];
+  }
+
+  const TestSchema = new Schema<TestDoc<Field>>({});
+  if (options) {
+    TestSchema.plugin(
+      compactIdMiddleware as PluginFunction<CompactIdMiddlewareOptions<Field>>,
+      options,
+    );
+  } else {
+    TestSchema.plugin(compactIdMiddleware);
+  }
+
+  return model<TestDoc<Field>>(modelName, TestSchema);
+};
+
+describe('compactIdMiddleware', () => {
+  it('should add a "shortId" field by default with correct options', async () => {
+    const TestModel = createTestModel();
+    const doc = new TestModel();
+
+    await expect(doc.save()).resolves.not.toThrow();
+    const savedDoc = await TestModel.findOne({ _id: doc._id });
+    expect(savedDoc).toBeDefined();
+    expect(savedDoc?.shortId).toBeDefined();
+    expect(savedDoc?.shortId.length).toBe(9);
+  });
+
+  it('should generate a compactId of specified length', async () => {
+    const TestModel = createTestModel({ length: 12 });
+    const doc = new TestModel();
+
+    await expect(doc.save()).resolves.not.toThrow();
+    const savedDoc = await TestModel.findOne({ _id: doc._id });
+    expect(savedDoc?.shortId).toHaveLength(12);
+  });
+
+  it('should allow configuring the field name', async () => {
+    const TestModel = createTestModel<'customId'>({ field: 'customId' });
+    const doc = new TestModel();
+
+    await expect(doc.save()).resolves.not.toThrow();
+    const savedDoc = await TestModel.findOne({ _id: doc._id });
+    expect(savedDoc).toBeDefined();
+    expect(savedDoc?.customId).toBeDefined();
+  });
+
+  it('should not generate "index" if not requested', () => {
+    const TestModel = createTestModel({ index: false });
+    const indexes = TestModel.schema.indexes();
+    const customIdIndex = indexes.find(([fields]) =>
+      Object.prototype.hasOwnProperty.call(fields, 'shortId'),
+    );
+
+    expect(customIdIndex).toBeUndefined();
+  });
+
+  it('should apply "index" and not "unique" options to the field', () => {
+    const TestModel = createTestModel({ index: true, unique: false });
+    const indexes = TestModel.schema.indexes();
+    const customIdIndex = indexes.find(([fields]) =>
+      Object.prototype.hasOwnProperty.call(fields, 'shortId'),
+    );
+
+    expect(customIdIndex).toBeDefined();
+    expect(customIdIndex![0].shortId).toBe(1);
+    expect(customIdIndex![1].unique).toBe(false);
+  });
+
+  it('should apply "unique" and "unique" options to the field', () => {
+    const TestModel = createTestModel({ index: true, unique: true });
+    const indexes = TestModel.schema.indexes();
+    const customIdIndex = indexes.find(([fields]) =>
+      Object.prototype.hasOwnProperty.call(fields, 'shortId'),
+    );
+
+    expect(customIdIndex).toBeDefined();
+    expect(customIdIndex![0].shortId).toBe(1);
+    expect(customIdIndex![1].unique).toBe(true);
+  });
+});

package/src/middleware/compactId.ts

@@ -0,0 +1,42 @@
+import { Document, Model, Schema } from 'mongoose';
+import { nanoid } from 'nanoid';
+
+import { PluginFunction } from '../types.js';
+
+export interface CompactIdMiddlewareOptions<Field extends string = 'shortId'> {
+  field?: Field;
+  index?: boolean;
+  length?: number;
+  unique?: boolean;
+}
+
+export type WithCompactId<Field extends string = 'shortId'> = {
+  [key in Field]: string;
+};
+
+const compactIdMiddleware: PluginFunction<CompactIdMiddlewareOptions> = <
+  Field extends string = 'shortId',
+  DocType extends Document & WithCompactId<Field> = Document & WithCompactId<Field>,
+>(
+  schema: Schema<DocType, Model<DocType>>,
+  {
+    field = 'shortId' as Field,
+    index = true,
+    length = 9,
+    unique = true,
+  }: CompactIdMiddlewareOptions<Field> = {},
+): void => {
+  const fieldDescription = new Schema<WithCompactId<Field>>({
+    [field]: {
+      default: () => nanoid(length),
+      index,
+      required: true,
+      unique: index && unique,
+      type: String,
+    },
+  });
+
+  schema.add(fieldDescription);
+};
+
+export default compactIdMiddleware;

package/src/middleware/email.spec.ts

@@ -0,0 +1,84 @@
+import { setupMongoTestEnvironment } from '@slango.configs/vitest/helpers/mongooseTestEnvironment';
+import mongoose, { Document, model, Schema } from 'mongoose';
+import { describe, expect, it } from 'vitest';
+
+import emailMiddleware from './email.js';
+
+setupMongoTestEnvironment();
+
+interface TestUser extends Document {
+  email: string;
+}
+
+const TestUserSchema = new Schema<TestUser>({});
+TestUserSchema.plugin(emailMiddleware);
+
+const TestUserModel = model<TestUser>('TestUser', TestUserSchema);
+
+const validEmail = 'valid.email@example.com';
+const invalidEmail = 'invalid-email';
+const customErrorMessage = 'Custom error message for invalid email';
+
+describe('emailMiddleware', () => {
+  it('should allow saving a user with a valid email', async () => {
+    const user = new TestUserModel({ email: validEmail });
+
+    await expect(user.save()).resolves.not.toThrow();
+  });
+
+  it('should fail when saving a user with an invalid email', async () => {
+    const user = new TestUserModel({ email: invalidEmail });
+
+    await expect(user.save()).rejects.toThrowError(mongoose.Error.ValidationError);
+  });
+
+  it('should enforce uniqueness for email', async () => {
+    const user1 = new TestUserModel({ email: validEmail });
+    const user2 = new TestUserModel({ email: validEmail });
+
+    await user1.save();
+    await expect(user2.save()).rejects.toThrowError(Error);
+  });
+
+  it('should allow saving a user without an email if "required" is set to false', async () => {
+    const OptionalEmailUserSchema = new Schema<TestUser>({});
+    OptionalEmailUserSchema.plugin(emailMiddleware, { required: false });
+    const OptionalEmailUserModel = model<TestUser>('OptionalEmailUser', OptionalEmailUserSchema);
+
+    const user = new OptionalEmailUserModel({});
+
+    await expect(user.save()).resolves.not.toThrow();
+  });
+
+  it('should display custom error message for invalid email', async () => {
+    const CustomMessageSchema = new Schema<TestUser>({});
+    CustomMessageSchema.plugin(emailMiddleware, { doesNotMatchMessage: customErrorMessage });
+    const CustomMessageUserModel = model<TestUser>('CustomMessageUser', CustomMessageSchema);
+
+    const user = new CustomMessageUserModel({ email: invalidEmail });
+
+    await expect(user.save()).rejects.toThrowError(customErrorMessage);
+  });
+
+  it('should allow saving a user with a non-unique email if "unique" is set to false', async () => {
+    const NonUniqueEmailSchema = new Schema<TestUser>({});
+    NonUniqueEmailSchema.plugin(emailMiddleware, { unique: false });
+    const NonUniqueEmailUserModel = model<TestUser>('NonUniqueEmailUser', NonUniqueEmailSchema);
+
+    const user1 = new NonUniqueEmailUserModel({ email: validEmail });
+    const user2 = new NonUniqueEmailUserModel({ email: validEmail });
+
+    await expect(user1.save()).resolves.not.toThrow();
+    await expect(user2.save()).resolves.not.toThrow(); // Should pass without unique constraint
+  });
+
+  it('should trim email addresses before saving', async () => {
+    const user = new TestUserModel({ email: ` ${validEmail} ` });
+
+    await user.save();
+    const savedUser = await TestUserModel.findOne({ email: validEmail });
+
+    expect(savedUser).toBeDefined();
+    expect(savedUser?.email).toBe(validEmail);
+  });
+});

package/src/middleware/email.ts

@@ -0,0 +1,49 @@
+import { Document, Model, Schema } from 'mongoose';
+
+import { PluginFunction } from '../types.js';
+
+export const emailRegexp = /^[\w.%+-]+@[a-z0-9.-]+\.[a-z]{2,}$/i;
+
+export type WithEmail<
+  Field extends string = 'email',
+  Required extends boolean = true,
+> = Required extends true ? { [key in Field]: string } : { [key in Field]?: string };
+
+interface EmailMiddlewareOptions<Field extends string = 'email'> {
+  doesNotMatchMessage?: string;
+  field?: Field;
+  index?: boolean;
+  regExp?: RegExp;
+  required?: boolean;
+  unique?: boolean;
+}
+
+const emailMiddleware: PluginFunction<EmailMiddlewareOptions> = <
+  Field extends string = 'email',
+  DocType extends Document & WithEmail<Field> = Document & WithEmail<Field>,
+>(
+  schema: Schema<DocType, Model<DocType>>,
+  {
+    doesNotMatchMessage,
+    field = 'email' as Field,
+    index = true,
+    regExp = emailRegexp,
+    required = true,
+    unique = true,
+  }: EmailMiddlewareOptions<Field> = {},
+): void => {
+  const emailSchema = new Schema<WithEmail<Field>>({
+    [field]: {
+      index,
+      match: doesNotMatchMessage ? [regExp, doesNotMatchMessage] : regExp,
+      required,
+      trim: true,
+      type: String,
+      unique,
+    },
+  });
+
+  schema.add(emailSchema);
+};
+
+export default emailMiddleware;

package/src/middleware/owner.spec.ts

@@ -0,0 +1,88 @@
+import { setupMongoTestEnvironment } from '@slango.configs/vitest/helpers/mongooseTestEnvironment';
+import mongoose, { Document, model, Schema, Types } from 'mongoose';
+import { describe, expect, it } from 'vitest';
+
+import { PluginFunction } from '../types.js';
+import ownerMiddleware, { OwnerMiddlewareOptions, WithOwner } from './owner.js';
+
+setupMongoTestEnvironment();
+
+type TestDoc<Field extends string = 'user'> = Document<Types.ObjectId> &
+  WithOwner<Types.ObjectId, Field>;
+
+const createTestModel = <Field extends string = 'user'>(
+  options?: OwnerMiddlewareOptions<Field>,
+) => {
+  const modelName = 'TestDoc';
+
+  if (mongoose.models[modelName]) {
+    delete mongoose.models[modelName];
+  }
+
+  const TestSchema = new Schema<TestDoc<Field>>({});
+  if (options) {
+    TestSchema.plugin(ownerMiddleware as PluginFunction<OwnerMiddlewareOptions<Field>>, options);
+  } else {
+    TestSchema.plugin(ownerMiddleware);
+  }
+
+  return model<TestDoc<Field>>(modelName, TestSchema);
+};
+
+describe('ownerMiddleware', () => {
+  it('should add a "user" field by default with correct options', async () => {
+    const TestModel = createTestModel();
+    const doc = new TestModel({ user: new Types.ObjectId() });
+
+    await expect(doc.save()).resolves.not.toThrow();
+    const savedDoc = await TestModel.findOne({ _id: doc._id });
+    expect(savedDoc).toBeDefined();
+    expect(savedDoc?.user?.toString()).toBe(doc.user.toString());
+  });
+
+  it('should not allow saving without user field if required', async () => {
+    const TestModel = createTestModel();
+    const doc = new TestModel({});
+
+    await expect(doc.save()).rejects.toThrowError(mongoose.Error.ValidationError);
+  });
+
+  it('should allow configuring the field name', async () => {
+    const TestModel = createTestModel<'owner'>({ field: 'owner' });
+    const doc = new TestModel({ owner: new Types.ObjectId() });
+
+    await expect(doc.save()).resolves.not.toThrow();
+    const savedDoc = await TestModel.findOne({ _id: doc._id });
+
+    expect(savedDoc).toBeDefined();
+    expect(savedDoc?.owner?.toString()).toBe(doc.owner.toString());
+  });
+
+  it('should allow optional "user" field if "required" is set to false', async () => {
+    const TestModel = createTestModel({ required: false });
+    const doc = new TestModel({});
+
+    await expect(doc.save()).resolves.not.toThrow();
+    const savedDoc = await TestModel.findOne({ _id: doc._id });
+    expect(savedDoc).toBeDefined();
+    expect(savedDoc?.user).toBeUndefined();
+  });
+
+  it('should apply "index" option to the field', () => {
+    const TestModel = createTestModel({ index: true });
+    const indexes = TestModel.schema.indexes();
+    const userIndex = indexes.find(([fields]) =>
+      Object.prototype.hasOwnProperty.call(fields, 'user'),
+    );
+
+    expect(userIndex).toBeDefined();
+    expect(userIndex![0].user).toBe(1);
+  });
+
+  it('should reference the specified model in "ref"', () => {
+    const TestModel = createTestModel({ ref: 'CustomUser' });
+    const refField = TestModel.schema.path('user');
+
+    expect(refField.options.ref).toBe('CustomUser');
+  });
+});

package/src/middleware/owner.ts

@@ -0,0 +1,39 @@
+import { Document, Schema, Types } from 'mongoose';
+
+import { PluginFunction } from '../types.js';
+
+export interface OwnerMiddlewareOptions<Field extends string = 'user'> {
+  field?: Field;
+  index?: boolean;
+  ref?: string;
+  required?: boolean;
+}
+
+export type WithOwner<T = Types.ObjectId, Field extends string = 'user'> = {
+  [key in Field]: T;
+};
+
+const ownerMiddleware: PluginFunction<OwnerMiddlewareOptions> = <
+  Field extends string = 'user',
+  DocType extends Document & WithOwner<Field> = Document & WithOwner<Field>,
+>(
+  schema: Schema<DocType>,
+  {
+    field = 'user' as Field,
+    index = true,
+    ref = 'User',
+    required = true,
+  }: OwnerMiddlewareOptions<Field> = {},
+): void => {
+  const fieldDescription = new Schema<WithOwner<Field>>({
+    [field]: {
+      index,
+      ref,
+      required,
+      type: Types.ObjectId,
+    },
+  });
+  schema.add(fieldDescription);
+};
+
+export default ownerMiddleware;

package/src/middleware/password.ts

@@ -0,0 +1,84 @@
+import { compare, hash } from 'bcrypt';
+import { Document, Model, Schema } from 'mongoose';
+
+import { PluginFunction } from '../types.js';
+
+export type WithPassword<
+  Field extends string = 'password',
+  ComparisonFunction extends string = 'comparePassword',
+> = {
+  [key in ComparisonFunction]: (password: string) => Promise<boolean>;
+} & {
+  [key in Field]: string;
+};
+
+export const passwordRegExp = /^(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[@#$%^&*)(\][+=.,_-]).{8,}$/;
+
+interface PasswordMiddlewareOptions<
+  Field extends string = 'password',
+  ComparisonFunction extends string = 'comparePassword',
+> {
+  comparisonFunction?: ComparisonFunction;
+  doesNotMatchMessage?: string;
+  field?: Field;
+  regExp?: RegExp;
+  required?: boolean;
+  saltingRounds?: number;
+}
+
+const passwordMiddleware: PluginFunction<PasswordMiddlewareOptions> = <
+  Field extends string = 'password',
+  ComparisonFunction extends string = 'comparePassword',
+  DocType extends Document & WithPassword<Field, ComparisonFunction> = Document &
+    WithPassword<Field, ComparisonFunction>,
+>(
+  schema: Schema<DocType, Model<DocType>>,
+  {
+    comparisonFunction = 'comparePassword' as ComparisonFunction,
+    doesNotMatchMessage,
+    field = 'password' as Field,
+    regExp = passwordRegExp,
+    required = true,
+    saltingRounds = 10,
+  }: PasswordMiddlewareOptions<Field, ComparisonFunction> = {},
+): void => {
+  const fieldDescription = new Schema<WithPassword<Field, ComparisonFunction>>({
+    [field]: {
+      match: doesNotMatchMessage ? [regExp, doesNotMatchMessage] : regExp,
+      required,
+      type: String,
+    },
+  });
+
+  schema.add(fieldDescription);
+
+  schema.pre<DocType>('save', async function schemaWithPasswordPreSave(next) {
+    // only hash the password if it has been modified (or is new)
+    if (!this.isModified(field)) {
+      return next();
+    }
+
+    try {
+      // generate a hash and override the clear text password with the hashed one
+      this.set(field, await hash(this.get(field) as DocType[Field], saltingRounds));
+      next();
+    } catch (err) {
+      if (err instanceof Error) {
+        next(err);
+      }
+    }
+  });
+
+  schema.methods[comparisonFunction] = async function comparePassword(
+    this: DocType & Document,
+    candidate: string,
+  ): Promise<boolean> {
+    try {
+      return await compare(candidate, this.get(field) as DocType[Field]);
+    } catch {
+      return false;
+    }
+  };
+};
+
+export default passwordMiddleware;

package/src/middleware/tags.spec.ts

@@ -0,0 +1,111 @@
+import { setupMongoTestEnvironment } from '@slango.configs/vitest/helpers/mongooseTestEnvironment';
+import mongoose, { Document, model, Schema } from 'mongoose';
+import { describe, expect, it } from 'vitest';
+
+import tagsMiddleware, { TagsMiddlewareOptions, WithTags } from './tags.js';
+
+setupMongoTestEnvironment();
+
+type TestDoc<Field extends string = 'tags'> = Document & WithTags<Field>;
+
+const createTestModel = <Field extends string = 'tags'>(options?: TagsMiddlewareOptions<Field>) => {
+  const modelName = 'TestDoc';
+
+  if (mongoose.models[modelName]) {
+    delete mongoose.models[modelName];
+  }
+
+  const TestSchema = new Schema<TestDoc<Field>>({});
+  if (options) {
+    TestSchema.plugin(tagsMiddleware, options as TagsMiddlewareOptions);
+  } else {
+    TestSchema.plugin(tagsMiddleware);
+  }
+
+  return model<TestDoc<Field>>(modelName, TestSchema);
+};
+
+describe('tagsMiddleware', () => {
+  it('should add a "tags" field with correct content if tags are provided', async () => {
+    const TestModel = createTestModel();
+    const doc = new TestModel({ tags: ['tag1', 'tag2'] });
+
+    await expect(doc.save()).resolves.not.toThrow();
+    const savedDoc = await TestModel.findOne({ _id: doc._id });
+
+    expect(savedDoc).toBeDefined();
+    expect(savedDoc?.tags).toEqual(['tag1', 'tag2']);
+  });
+
+  it('should add a "tags" field with empty array if no tag is provided', async () => {
+    const TestModel = createTestModel();
+    const doc = new TestModel({});
+
+    await expect(doc.save()).resolves.not.toThrow();
+    const savedDoc = await TestModel.findOne({ _id: doc._id });
+
+    expect(savedDoc).toBeDefined();
+    expect(savedDoc?.tags).toEqual([]);
+  });
+
+  it('should ensure uniqueness of tags if "unique" is set to true', async () => {
+    const TestModel = createTestModel({ unique: true });
+    const doc = new TestModel({ tags: ['tag1', 'tag2', 'tag1'] });
+
+    await expect(doc.save()).resolves.not.toThrow();
+    const savedDoc = await TestModel.findOne({ _id: doc._id });
+
+    expect(savedDoc).toBeDefined();
+    expect(savedDoc?.tags).toEqual(['tag1', 'tag2']); // Duplicates removed
+  });
+
+  it('should not enforce uniqueness if "unique" is set to false', async () => {
+    const TestModel = createTestModel({ unique: false });
+    const doc = new TestModel({ tags: ['tag1', 'tag2', 'tag1'] });
+
+    await expect(doc.save()).resolves.not.toThrow();
+    const savedDoc = await TestModel.findOne({ _id: doc._id });
+
+    expect(savedDoc).toBeDefined();
+    expect(savedDoc?.tags).toEqual(['tag1', 'tag2', 'tag1']);
+  });
+
+  it('should validate tags with custom validation function', async () => {
+    const TestModel = createTestModel({
+      validate: (tags) => tags.every((tag) => tag.startsWith('valid')),
+    });
+
+    const validDoc = new TestModel({ tags: ['validTag1', 'validTag2'] });
+    await expect(validDoc.save()).resolves.not.toThrow();
+
+    const invalidDoc = new TestModel({ tags: ['validTag', 'invalidTag'] });
+    await expect(invalidDoc.save()).rejects.toThrowError(mongoose.Error.ValidationError);
+  });
+
+  it('should allow configuring the field name', async () => {
+    const TestModel = createTestModel<'customTags'>({ field: 'customTags' });
+    const doc = new TestModel({ customTags: ['tag1', 'tag2'] });
+
+    await expect(doc.save()).resolves.not.toThrow();
+    const savedDoc = await TestModel.findOne({ _id: doc._id });
+
+    expect(savedDoc).toBeDefined();
+    expect(savedDoc?.customTags).toEqual(['tag1', 'tag2']);
+  });
+
+  it('should add a text index when index is set to "text"', () => {
+    const TestModel = createTestModel({ index: 'text' });
+    const indexes = TestModel.schema.indexes();
+
+    const textIndex = indexes.find(([fields]) => fields.tags === 'text');
+    expect(textIndex).toBeDefined();
+  });
+
+  it('should add a hashed index when index is set to "hashed"', () => {
+    const TestModel = createTestModel({ index: 'hashed' });
+    const indexes = TestModel.schema.indexes();
+
+    const textIndex = indexes.find(([fields]) => fields.tags === 'hashed');
+    expect(textIndex).toBeDefined();
+  });
+});

package/src/middleware/tags.ts

@@ -0,0 +1,56 @@
+import { Document, Model, Schema } from 'mongoose';
+
+import { PluginFunction } from '../types.js';
+
+export interface TagsMiddlewareOptions<Field extends string = 'tags'> {
+  field?: Field;
+  index?: 'hashed' | 'text' | false;
+  unique?: boolean;
+  validate?: (tags: string[]) => boolean;
+}
+
+export type WithTags<Field extends string = 'tags'> = {
+  [key in Field]: string[];
+};
+
+const tagsMiddleware: PluginFunction<TagsMiddlewareOptions> = <
+  Field extends string = 'tags',
+  DocType extends Document & WithTags<Field> = Document & WithTags<Field>,
+>(
+  schema: Schema<DocType, Model<DocType>>,
+  {
+    field = 'tags' as Field,
+    index = false,
+    unique = true,
+    validate,
+  }: TagsMiddlewareOptions<Field> = {},
+): void => {
+  const tagsSchema = new Schema<WithTags<Field>>({
+    [field]: {
+      type: [String],
+      ...(validate && {
+        validate: {
+          message: 'Tags failed custom validation.',
+          validator: (tags: string[]) => validate(tags),
+        },
+      }),
+    },
+  });
+
+  schema.add(tagsSchema);
+
+  if (index) {
+    schema.index({ [field]: index });
+  }
+
+  schema.pre<DocType>('save', function schemaWithTagsPreSave(next) {
+    const tags = this.get(field) as DocType[Field];
+    if (unique && tags) {
+      this.set(field, Array.from(new Set(tags)));
+    }
+
+    next();
+  });
+};
+
+export default tagsMiddleware;