@classytic/mongokit 3.11.1 → 3.13.0

package/dist/field-selection-Br3WPOEb.mjs

@@ -0,0 +1,99 @@
+//#region src/utils/field-selection.ts
+/**
+* Get allowed fields for a user based on their context
+*
+* @param user - User object from request.user (or null for public)
+* @param preset - Field preset configuration
+* @returns Array of allowed field names
+*
+* @example
+* const fields = getFieldsForUser(request.user, {
+*   public: ['id', 'name', 'price'],
+*   authenticated: ['description', 'features'],
+*   admin: ['createdAt', 'internalNotes']
+* });
+*/
+function getFieldsForUser(user, preset) {
+	if (!preset) throw new Error("Field preset is required");
+	const fields = [...preset.public || []];
+	if (user) {
+		fields.push(...preset.authenticated || []);
+		const roles = Array.isArray(user.roles) ? user.roles : user.roles ? [user.roles] : [];
+		if (roles.includes("admin") || roles.includes("superadmin")) fields.push(...preset.admin || []);
+	}
+	return [...new Set(fields)];
+}
+/**
+* Get Mongoose projection string for query .select()
+*
+* @param user - User object from request.user
+* @param preset - Field preset configuration
+* @returns Space-separated field names for Mongoose .select()
+*
+* @example
+* const projection = getMongooseProjection(request.user, fieldPresets.gymPlans);
+* const plans = await GymPlan.find({ organizationId }).select(projection).lean();
+*/
+function getMongooseProjection(user, preset) {
+	return getFieldsForUser(user, preset).join(" ");
+}
+/**
+* Filter a single object to include only allowed fields
+*/
+function filterObject(obj, allowedFields) {
+	if (!obj || typeof obj !== "object" || Array.isArray(obj)) return obj;
+	const filtered = {};
+	for (const field of allowedFields) if (field in obj) filtered[field] = obj[field];
+	return filtered;
+}
+/**
+* Filter response data to include only allowed fields
+*
+* Use this for complex responses where Mongoose projections aren't applicable:
+* - Aggregation pipeline results
+* - Data from multiple sources
+* - Custom computed fields
+*
+* For simple DB queries, prefer getMongooseProjection() (10x faster)
+*
+* @param data - Data to filter
+* @param preset - Field preset configuration
+* @param user - User object from request.user
+* @returns Filtered data
+*
+* @example
+* const stats = await calculateComplexStats();
+* const filtered = filterResponseData(stats, fieldPresets.dashboard, request.user);
+* return reply.send(filtered);
+*/
+function filterResponseData(data, preset, user = null) {
+	const allowedFields = getFieldsForUser(user, preset);
+	if (Array.isArray(data)) return data.map((item) => filterObject(item, allowedFields));
+	return filterObject(data, allowedFields);
+}
+/**
+* Helper to create field presets (module-level)
+*
+* Each module should define its own field preset in its own directory.
+* This keeps modules independent and self-contained.
+*
+* @param config - Field configuration
+* @returns Field preset
+*
+* @example
+* // In modules/gym-plan/gym-plan.fields.ts
+* export const gymPlanFieldPreset = createFieldPreset({
+*   public: ['id', 'name', 'price'],
+*   authenticated: ['features', 'description'],
+*   admin: ['createdAt', 'updatedAt', 'internalNotes']
+* });
+*/
+function createFieldPreset(config) {
+	return {
+		public: config.public || [],
+		authenticated: config.authenticated || [],
+		admin: config.admin || []
+	};
+}
+//#endregion
+export { getMongooseProjection as i, filterResponseData as n, getFieldsForUser as r, createFieldPreset as t };

package/dist/{index-dNTmpgK8.d.mts → index-BbHaKwi5.d.mts}

@@ -1,4 +1,4 @@
-import { $ as ReadPreferenceType, B as ObjectId, D as GroupResult, E as FindOneAndUpdateOptions, R as MinMaxResult, U as OperationOptions, X as PopulateSpec, a as AnyDocument, b as DeleteResult, ft as SortSpec, g as CreateOptions, gt as UpdateOptions, ht as UpdateManyResult, kt as LookupOptions, ot as SelectSpec, vt as UpdateWithValidationResult } from "./types-Dc2aDVUi.mjs";
+import { B as ObjectId, Dt as LookupOptions, H as OperationOptions, I as MinMaxResult, J as PopulateSpec, T as GroupResult, Z as ReadPreferenceType, ft as UpdateManyResult, ht as UpdateWithValidationResult, i as AnyDocument, it as SelectSpec, p as CreateOptions, pt as UpdateOptions, ut as SortSpec, v as DeleteResult, w as FindOneAndUpdateOptions } from "./types-BbaPZleN.mjs";
 import { Model, PipelineStage } from "mongoose";
 
 //#region src/actions/aggregate.d.ts
@@ -21,7 +21,7 @@ declare function aggregatePaginate<TDoc = AnyDocument>(Model: Model<TDoc>, pipel
   limit?: number;
   session?: unknown;
 }): Promise<{
-  docs: TDoc[];
+  data: TDoc[];
   total: number;
   page: number;
   limit: number;
@@ -116,38 +116,43 @@ declare namespace delete_d_exports {
   export { deleteById, deleteByQuery, deleteMany, restore, softDelete };
 }
 /**
- * Delete by ID
+ * Delete by ID. Returns `null` on miss (matches `update()` convention) —
+ * a second delete on the same id is a no-op, not an error.
  */
 declare function deleteById<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, options?: {
   session?: unknown;
   query?: Record<string, unknown>;
-}): Promise<DeleteResult>;
+}): Promise<DeleteResult | null>;
 /**
- * Delete many documents
+ * Delete many documents. Always returns a {@link DeleteResult} (never
+ * null) — a deleteMany with zero matches is a successful op with
+ * `count: 0`, not a miss.
  */
 declare function deleteMany<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, options?: {
   session?: unknown;
 }): Promise<DeleteResult>;
 /**
- * Delete by query
+ * Delete by query. Returns `null` on miss unless `throwOnNotFound: true`.
  */
 declare function deleteByQuery(Model: Model<any>, query: Record<string, unknown>, options?: {
   session?: unknown;
   throwOnNotFound?: boolean;
-}): Promise<DeleteResult>;
+}): Promise<DeleteResult | null>;
 /**
- * Soft delete (set deleted flag)
+ * Soft delete (set deleted flag). Returns `null` on miss for parity with
+ * `deleteById`; callers that prefer a throw can wrap or use `throwOnNotFound`
+ * pattern at the call site.
  */
 declare function softDelete<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, options?: {
   session?: unknown;
   userId?: string;
-}): Promise<DeleteResult>;
+}): Promise<DeleteResult | null>;
 /**
- * Restore soft deleted document
+ * Restore soft-deleted document. Returns `null` on miss.
  */
 declare function restore<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, options?: {
   session?: unknown;
-}): Promise<DeleteResult>;
+}): Promise<DeleteResult | null>;
 declare namespace read_d_exports {
   export { count, exists, getAll, getById, getByQuery, getOrCreate, tryGetByQuery };
 }
@@ -190,12 +195,27 @@ declare function getAll<TDoc = AnyDocument>(Model: Model<TDoc>, query?: Record<s
   readPreference?: ReadPreferenceType;
 }): Promise<TDoc[]>;
 /**
- * Get or create document (upsert)
+ * Get or create document (atomic upsert).
+ *
+ * Returns `{ doc, created }` so callers can disambiguate the two
+ * outcomes without a follow-up read — load-bearing for race-detection
+ * in idempotency stores, lock acquisition, and "ensure-exists" flows.
+ *
+ * `created: true` ⇔ this caller's `createData` won the race and was
+ * just inserted; `created: false` ⇔ a doc matching `query` already
+ * existed and was returned unchanged.
+ *
+ * Mongo: `includeResultMetadata: true` returns the raw `ModifyResult`
+ * (`{ value, lastErrorObject, ok }`). `lastErrorObject.upserted` is
+ * the `_id` of a freshly-inserted row — present iff this call inserted.
  */
 declare function getOrCreate<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, createData: Record<string, unknown>, options?: {
   session?: unknown;
   updatePipeline?: boolean;
-}): Promise<TDoc | null>;
+}): Promise<{
+  doc: TDoc;
+  created: boolean;
+}>;
 /**
  * Count documents matching query
  */