@cyberskill/shared 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE CHANGED
@@ -1,7 +1,7 @@
1
1
 
2
2
  MIT License
3
3
 
4
- Copyright (c) 2025 Stephen Cheng <https://github.com/zintaen>
4
+ Copyright (c) 2025 CyberSkill JSC <https://github.com/cyberskill-world/shared>
5
5
 
6
6
  Permission is hereby granted, free of charge, to any person obtaining a copy
7
7
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -8,7 +8,7 @@
8
8
  [![📦 npm version](https://img.shields.io/npm/v/@cyberskill/shared?style=for-the-badge&logo=npm)](https://npmjs.com/package/@cyberskill/shared)
9
9
  [![📥 npm downloads](https://img.shields.io/npm/dm/@cyberskill/shared?style=for-the-badge&logo=npm)](https://npmjs.com/package/@cyberskill/shared)
10
10
  [![📚 JSDoc Documentation](https://img.shields.io/badge/JSDoc-Documentation-blue?style=for-the-badge&logo=javascript)](https://www.jsdocs.io/package/@cyberskill/shared)
11
- [![📄 License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge&logo=opensourceinitiative)](https://opensource.org/licenses/MIT)
11
+ [![📄 License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge&logo=opensourceinitiative)](LICENSE)
12
12
 
13
13
  </div>
14
14
 
@@ -1 +1 @@
1
- "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("@vitejs/plugin-react-swc"),i=require("lodash-es"),o=require("../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.0_js_54cc41e7146dfcdf3e05180c4f422c31/node_modules/vitest/dist/config.cjs");function s(e){const r={plugins:[t()],test:{include:["**/*.test.e2e.?(c|m)[jt]s?(x)"],browser:{enabled:!0,provider:"playwright",instances:[{browser:"chromium"},{browser:"firefox"},{browser:"webkit"}]}}};return o.defineConfig(i.merge(r,e))}exports.vitestE2E=s;
1
+ "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("@vitejs/plugin-react-swc"),i=require("lodash-es"),o=require("../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.1_js_7b82ece51006a4f428642448fb1b082c/node_modules/vitest/dist/config.cjs");function s(e){const r={plugins:[t()],test:{include:["**/*.test.e2e.?(c|m)[jt]s?(x)"],browser:{enabled:!0,provider:"playwright",instances:[{browser:"chromium"},{browser:"firefox"},{browser:"webkit"}]}}};return o.defineConfig(i.merge(r,e))}exports.vitestE2E=s;
@@ -1,6 +1,6 @@
1
1
  import t from "@vitejs/plugin-react-swc";
2
2
  import { merge as o } from "lodash-es";
3
- import { defineConfig as i } from "../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.0_js_54cc41e7146dfcdf3e05180c4f422c31/node_modules/vitest/dist/config.js";
3
+ import { defineConfig as i } from "../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.1_js_7b82ece51006a4f428642448fb1b082c/node_modules/vitest/dist/config.js";
4
4
  function f(r) {
5
5
  const e = {
6
6
  plugins: [t()],
@@ -1 +1 @@
1
- "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("@vitejs/plugin-react-swc"),n=require("lodash-es"),s=require("../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.0_js_54cc41e7146dfcdf3e05180c4f422c31/node_modules/vitest/dist/config.cjs");function r(e){const t={plugins:[i()],test:{globals:!0,environment:"jsdom",pool:"vmThreads",include:["**/*.test.unit.?(c|m)[jt]s?(x)"],setupFiles:["./vitest.unit.setup.ts"]}};return s.defineConfig(n.merge(t,e))}exports.vitestUnit=r;
1
+ "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("@vitejs/plugin-react-swc"),n=require("lodash-es"),s=require("../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.1_js_7b82ece51006a4f428642448fb1b082c/node_modules/vitest/dist/config.cjs");function r(e){const t={plugins:[i()],test:{globals:!0,environment:"jsdom",pool:"vmThreads",include:["**/*.test.unit.?(c|m)[jt]s?(x)"],setupFiles:["./vitest.unit.setup.ts"]}};return s.defineConfig(n.merge(t,e))}exports.vitestUnit=r;
@@ -1,6 +1,6 @@
1
1
  import i from "@vitejs/plugin-react-swc";
2
2
  import { merge as o } from "lodash-es";
3
- import { defineConfig as n } from "../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.0_js_54cc41e7146dfcdf3e05180c4f422c31/node_modules/vitest/dist/config.js";
3
+ import { defineConfig as n } from "../../node_modules/.pnpm/vitest@3.2.4_@types_debug@4.1.12_@types_node@24.1.0_@vitest_browser@3.2.4_jiti@2.5.1_js_7b82ece51006a4f428642448fb1b082c/node_modules/vitest/dist/config.js";
4
4
  function u(t) {
5
5
  const e = {
6
6
  plugins: [i()],
@@ -100,9 +100,9 @@ export interface I_MongooseModelMiddleware<T extends Partial<C_Document>> {
100
100
  export interface I_CreateModelOptions<T extends Partial<C_Document>, R extends string = string> extends I_MongooseOptions<T, R> {
101
101
  schema: T_Input_MongooseSchema<T>;
102
102
  name: string;
103
+ pagination?: boolean;
103
104
  aggregate?: boolean;
104
105
  middlewares?: I_MongooseModelMiddleware<T>[];
105
- pagination?: boolean;
106
106
  }
107
107
  export type T_Input_Populate = string | string[] | T_PopulateOptions | T_PopulateOptions[];
108
108
  export interface I_PaginateOptionsWithPopulate extends T_PaginateOptions, Omit<T_PopulateOption, 'populate'> {
@@ -118,12 +118,10 @@ export interface I_Input_FindAll<T> extends T_PopulateOption {
118
118
  projection?: T_ProjectionType<T>;
119
119
  options?: T_QueryOptions<T>;
120
120
  }
121
- export type I_Input_FindPaging<T = undefined> = T extends undefined ? {
122
- options?: I_PaginateOptionsWithPopulate;
123
- } : {
121
+ export interface I_Input_FindPaging<T = undefined> {
124
122
  filter?: T_FilterQuery<T>;
125
123
  options?: I_PaginateOptionsWithPopulate;
126
- };
124
+ }
127
125
  export interface I_Input_FindPagingAggregate {
128
126
  pipeline: T_PipelineStage[];
129
127
  options?: I_PaginateOptionsWithPopulate;
@@ -1,4 +1,4 @@
1
- "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const j=require("lodash-es"),B=require("migrate-mongo"),k=require("mongoose"),H=require("mongoose-aggregate-paginate-v2"),K=require("mongoose-paginate-v2"),U=require("uuid"),$=require("../../util/object/object.util.cjs"),W=require("../../util/common/common.util.cjs"),P=require("../fs/fs.util.cjs"),A=require("../path/path.constant.cjs"),Q=require("../../util/validate/validate.util.cjs"),I=require("../../util/string/string.util.cjs"),v=require("../../constant/response-status.cjs"),f=require("../log/log.util.cjs");var z=Object.defineProperty,J=Object.defineProperties,X=Object.getOwnPropertyDescriptors,G=Object.getOwnPropertySymbols,Y=Object.prototype.hasOwnProperty,Z=Object.prototype.propertyIsEnumerable,F=(n,t,e)=>t in n?z(n,t,{enumerable:!0,configurable:!0,writable:!0,value:e}):n[t]=e,O=(n,t)=>{for(var e in t||(t={}))Y.call(t,e)&&F(n,e,t[e]);if(G)for(var e of G(t))Z.call(t,e)&&F(n,e,t[e]);return n},V=(n,t)=>J(n,X(t)),ee=(n,t,e)=>F(n,typeof t!="symbol"?t+"":t,e),a=(n,t,e)=>new Promise((r,s)=>{var c=i=>{try{o(e.next(i))}catch(l){s(l)}},u=i=>{try{o(e.throw(i))}catch(l){s(l)}},o=i=>i.done?r(i.value):Promise.resolve(i.value).then(c,u);o((e=e.apply(n,t)).next())});function te(n){return n===n.toUpperCase()?n.charAt(0).toUpperCase()+n.slice(1).toLowerCase():n}const T={createGenericFields(){return{id:U.v4(),isDel:!1,createdAt:new Date,updatedAt:new Date}},applyPlugins(n,t){t.filter(e=>typeof e=="function").forEach(e=>n.plugin(e))},applyMiddlewares(n,t){t.forEach(({method:e,pre:r,post:s})=>{e&&r&&n.pre(e,r),e&&s&&n.post(e,s)})},createGenericSchema(n){return new n.Schema({id:{type:String,default:U.v4,unique:!0},isDel:{type:Boolean,default:!1}},{timestamps:!0})},createSchema({mongoose:n,schema:t,virtuals:e=[],standalone:r=!1}){const s=new n.Schema(t);return e.forEach(({name:c,options:u,get:o})=>{if(T.isDynamicVirtual(u)){const i=s.statics;i._dynamicVirtuals||(i._dynamicVirtuals=[]),i._dynamicVirtuals.push({name:c,options:u});const l=s.virtual(c);o?l.get(o):l.get(function(){var d;return((d=this._populated)==null?void 0:d[c])||(u!=null&&u.count?0:u!=null&&u.justOne?null:[])})}else{const i=s.virtual(c,u);o&&i.get(o)}}),r||s.add(T.createGenericSchema(n)),s},createModel({mongoose:n,name:t,schema:e,pagination:r=!1,aggregate:s=!1,virtuals:c=[],middlewares:u=[]}){if(!t)throw new Error("Model name is required.");if(n.models[t])return n.models[t];const o=T.createSchema({mongoose:n,schema:e,virtuals:c});return T.applyPlugins(o,[r&&K,s&&H]),T.applyMiddlewares(o,u),n.model(t,o)},validator:{isRequired(){return function(n){return a(this,null,function*(){return!Q.validate.isEmpty(n)})}},isUnique(n){return function(t){return a(this,null,function*(){if(!Array.isArray(n)||n.length===0)throw new Error("Fields must be a non-empty array of strings.");const e={$or:n.map(s=>({[s]:t}))};return!(yield this.constructor.exists(e))})}},matchesRegex(n){return function(t){return a(this,null,function*(){if(!Array.isArray(n)||n.some(e=>!(e instanceof RegExp)))throw new Error("regexArray must be an array of valid RegExp objects.");return n.every(e=>e.test(t))})}}},migrate:V(O({},B),{setConfig:n=>{const t=`// This file is automatically generated by the Cyberskill CLI.
1
+ "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const j=require("lodash-es"),B=require("migrate-mongo"),k=require("mongoose"),H=require("mongoose-aggregate-paginate-v2"),K=require("mongoose-paginate-v2"),U=require("uuid"),$=require("../../util/object/object.util.cjs"),W=require("../../util/common/common.util.cjs"),P=require("../fs/fs.util.cjs"),A=require("../path/path.constant.cjs"),Q=require("../../util/validate/validate.util.cjs"),I=require("../../util/string/string.util.cjs"),v=require("../../constant/response-status.cjs"),f=require("../log/log.util.cjs");var J=Object.defineProperty,z=Object.defineProperties,X=Object.getOwnPropertyDescriptors,G=Object.getOwnPropertySymbols,Y=Object.prototype.hasOwnProperty,Z=Object.prototype.propertyIsEnumerable,F=(n,t,e)=>t in n?J(n,t,{enumerable:!0,configurable:!0,writable:!0,value:e}):n[t]=e,O=(n,t)=>{for(var e in t||(t={}))Y.call(t,e)&&F(n,e,t[e]);if(G)for(var e of G(t))Z.call(t,e)&&F(n,e,t[e]);return n},V=(n,t)=>z(n,X(t)),ee=(n,t,e)=>F(n,typeof t!="symbol"?t+"":t,e),a=(n,t,e)=>new Promise((r,s)=>{var c=i=>{try{o(e.next(i))}catch(l){s(l)}},u=i=>{try{o(e.throw(i))}catch(l){s(l)}},o=i=>i.done?r(i.value):Promise.resolve(i.value).then(c,u);o((e=e.apply(n,t)).next())});function te(n){return n===n.toUpperCase()?n.charAt(0).toUpperCase()+n.slice(1).toLowerCase():n}const T={createGenericFields(){return{id:U.v4(),isDel:!1,createdAt:new Date,updatedAt:new Date}},applyPlugins(n,t){t.filter(e=>typeof e=="function").forEach(e=>n.plugin(e))},applyMiddlewares(n,t){t.forEach(({method:e,pre:r,post:s})=>{e&&r&&n.pre(e,r),e&&s&&n.post(e,s)})},createGenericSchema(n){return new n.Schema({id:{type:String,default:U.v4,unique:!0},isDel:{type:Boolean,default:!1}},{timestamps:!0})},createSchema({mongoose:n,schema:t,virtuals:e=[],standalone:r=!1}){const s=new n.Schema(t);return e.forEach(({name:c,options:u,get:o})=>{if(T.isDynamicVirtual(u)){const i=s.statics;i._dynamicVirtuals||(i._dynamicVirtuals=[]),i._dynamicVirtuals.push({name:c,options:u});const l=s.virtual(c);o?l.get(o):l.get(function(){var d;return((d=this._populated)==null?void 0:d[c])||(u!=null&&u.count?0:u!=null&&u.justOne?null:[])})}else{const i=s.virtual(c,u);o&&i.get(o)}}),r||s.add(T.createGenericSchema(n)),s},createModel({mongoose:n,name:t,schema:e,virtuals:r=[],pagination:s=!0,aggregate:c=!0,middlewares:u=[]}){if(!t)throw new Error("Model name is required.");if(n.models[t])return n.models[t];const o=T.createSchema({mongoose:n,schema:e,virtuals:r});return(s||c)&&T.applyPlugins(o,[s&&K,c&&H]),T.applyMiddlewares(o,u),n.model(t,o)},validator:{isRequired(){return function(n){return a(this,null,function*(){return!Q.validate.isEmpty(n)})}},isUnique(n){return function(t){return a(this,null,function*(){if(!Array.isArray(n)||n.length===0)throw new Error("Fields must be a non-empty array of strings.");const e={$or:n.map(s=>({[s]:t}))};return!(yield this.constructor.exists(e))})}},matchesRegex(n){return function(t){return a(this,null,function*(){if(!Array.isArray(n)||n.some(e=>!(e instanceof RegExp)))throw new Error("regexArray must be an array of valid RegExp objects.");return n.every(e=>e.test(t))})}}},migrate:V(O({},B),{setConfig:n=>{const t=`// This file is automatically generated by the Cyberskill CLI.
2
2
  module.exports = ${JSON.stringify(n,null,4)}`;P.writeFileSync(A.PATH.MIGRATE_MONGO_CONFIG,t);const e=`
3
3
  ${A.MIGRATE_MONGO_CONFIG}
4
4
  `;P.pathExistsSync(A.PATH.GIT_IGNORE)?P.readFileSync(A.PATH.GIT_IGNORE,"utf-8").split(`
@@ -79,7 +79,7 @@ export declare const mongo: {
79
79
  * @returns A configured Mongoose model with extended functionality.
80
80
  * @throws {Error} When the model name is not provided.
81
81
  */
82
- createModel<T extends Partial<C_Document>, R extends string = string>({ mongoose: currentMongooseInstance, name, schema, pagination, aggregate, virtuals, middlewares, }: I_CreateModelOptions<T, R>): I_ExtendedModel<T>;
82
+ createModel<T extends Partial<C_Document>, R extends string = string>({ mongoose: currentMongooseInstance, name, schema, virtuals, pagination, aggregate, middlewares, }: I_CreateModelOptions<T, R>): I_ExtendedModel<T>;
83
83
  /**
84
84
  * Validation utilities for Mongoose schemas.
85
85
  * This object provides common validation functions that can be used in Mongoose schema definitions.
@@ -132,7 +132,9 @@ export declare const mongo: {
132
132
  *
133
133
  * @param options - Migration configuration options to write to the config file.
134
134
  */
135
- setConfig: (options: Partial<migrate.config.Config>) => void;
135
+ setConfig: (options: Partial<migrate.config.Config> & {
136
+ moduleSystem?: "commonjs" | "esm";
137
+ }) => void;
136
138
  init(): Promise<void>;
137
139
  create(description: string): Promise<string>;
138
140
  up(db: import('mongodb').Db, client: import('mongodb').MongoClient): Promise<string[]>;
@@ -4,8 +4,8 @@ import { Document as K } from "mongoose";
4
4
  import W from "mongoose-aggregate-paginate-v2";
5
5
  import Q from "mongoose-paginate-v2";
6
6
  import { v4 as F } from "uuid";
7
- import { getNestedValue as H, setNestedValue as z } from "../../util/object/object.util.js";
8
- import { regexSearchMapper as J } from "../../util/common/common.util.js";
7
+ import { getNestedValue as H, setNestedValue as J } from "../../util/object/object.util.js";
8
+ import { regexSearchMapper as z } from "../../util/common/common.util.js";
9
9
  import { writeFileSync as G, pathExistsSync as X, readFileSync as Y, appendFileSync as Z } from "../fs/fs.util.js";
10
10
  import { PATH as x, MIGRATE_MONGO_CONFIG as q } from "../path/path.constant.js";
11
11
  import { validate as ee } from "../../util/validate/validate.util.js";
@@ -151,19 +151,19 @@ const b = {
151
151
  mongoose: n,
152
152
  name: t,
153
153
  schema: e,
154
- pagination: r = !1,
155
- aggregate: s = !1,
156
- virtuals: c = [],
154
+ virtuals: r = [],
155
+ pagination: s = !0,
156
+ aggregate: c = !0,
157
157
  middlewares: u = []
158
158
  }) {
159
159
  if (!t)
160
160
  throw new Error("Model name is required.");
161
161
  if (n.models[t])
162
162
  return n.models[t];
163
- const o = b.createSchema({ mongoose: n, schema: e, virtuals: c });
164
- return b.applyPlugins(o, [
165
- r && Q,
166
- s && W
163
+ const o = b.createSchema({ mongoose: n, schema: e, virtuals: r });
164
+ return (s || c) && b.applyPlugins(o, [
165
+ s && Q,
166
+ c && W
167
167
  ]), b.applyMiddlewares(o, u), n.model(t, o);
168
168
  },
169
169
  /**
@@ -265,10 +265,10 @@ ${q}
265
265
  const s = r.toString().split("."), c = H(e, s);
266
266
  if (typeof c == "string" && c.length > 0) {
267
267
  const u = {
268
- $regex: `.*${J(c)}.*`,
268
+ $regex: `.*${z(c)}.*`,
269
269
  $options: "i"
270
270
  };
271
- e = z(e, s, u);
271
+ e = J(e, s, u);
272
272
  }
273
273
  }
274
274
  return e;
@@ -353,8 +353,8 @@ function P(n, t, e, r, s) {
353
353
  let v = -1;
354
354
  const D = N;
355
355
  D.id !== void 0 ? v = u.findIndex((V) => V.id === D.id) : D._id !== void 0 && (v = u.findIndex((V) => {
356
- var O, g, S, y;
357
- return ((g = (O = V._id) == null ? void 0 : O.toString) == null ? void 0 : g.call(O)) === ((y = (S = D._id) == null ? void 0 : S.toString) == null ? void 0 : y.call(S));
356
+ var O, y, S, g;
357
+ return ((y = (O = V._id) == null ? void 0 : O.toString) == null ? void 0 : y.call(O)) === ((g = (S = D._id) == null ? void 0 : S.toString) == null ? void 0 : g.call(S));
358
358
  })), v !== -1 && (h.docsByLocalValue.has(_) || h.docsByLocalValue.set(_, []), h.docsByLocalValue.get(_).push(v));
359
359
  }
360
360
  });
@@ -375,30 +375,30 @@ function P(n, t, e, r, s) {
375
375
  const C = yield m.find(N, s).lean();
376
376
  for (const _ of d.virtuals) {
377
377
  const { name: v, options: D } = _, V = C.filter((O) => {
378
- const g = O[D.foreignField];
379
- return g != null && p.has(String(g));
378
+ const y = O[D.foreignField];
379
+ return y != null && p.has(String(y));
380
380
  });
381
381
  if (D.count) {
382
382
  const O = /* @__PURE__ */ new Map();
383
- V.forEach((g) => {
383
+ V.forEach((y) => {
384
384
  var S;
385
- const y = (S = g[D.foreignField]) == null ? void 0 : S.toString();
386
- y && O.set(y, (O.get(y) || 0) + 1);
387
- }), d.localValueSets.get(v).forEach((g) => {
388
- const S = d.docsByLocalValue.get(g) || [], y = O.get(g) || 0;
385
+ const g = (S = y[D.foreignField]) == null ? void 0 : S.toString();
386
+ g && O.set(g, (O.get(g) || 0) + 1);
387
+ }), d.localValueSets.get(v).forEach((y) => {
388
+ const S = d.docsByLocalValue.get(y) || [], g = O.get(y) || 0;
389
389
  S.forEach((A) => {
390
390
  const I = u[A];
391
- I[v] === void 0 && (I[v] = y);
391
+ I[v] === void 0 && (I[v] = g);
392
392
  });
393
393
  });
394
394
  } else {
395
395
  const O = /* @__PURE__ */ new Map();
396
- V.forEach((g) => {
396
+ V.forEach((y) => {
397
397
  var S;
398
- const y = (S = g[D.foreignField]) == null ? void 0 : S.toString();
399
- y && (O.has(y) || O.set(y, []), O.get(y).push(g));
400
- }), d.localValueSets.get(v).forEach((g) => {
401
- const S = d.docsByLocalValue.get(g) || [], y = O.get(g) || [], A = D.justOne ? y[0] || null : y;
398
+ const g = (S = y[D.foreignField]) == null ? void 0 : S.toString();
399
+ g && (O.has(g) || O.set(g, []), O.get(g).push(y));
400
+ }), d.localValueSets.get(v).forEach((y) => {
401
+ const S = d.docsByLocalValue.get(y) || [], g = O.get(y) || [], A = D.justOne ? g[0] || null : g;
402
402
  S.forEach((I) => {
403
403
  const B = u[I];
404
404
  B[v] = A;
@@ -22,17 +22,50 @@ export interface I_Log {
22
22
  trace: typeof consola['trace'];
23
23
  verbose: typeof consola['verbose'];
24
24
  }
25
- export interface I_ReturnSuccess<T, E = unknown> {
26
- success: true;
27
- result: T & E;
25
+ /**
26
+ * Base interface for return types with common properties.
27
+ */
28
+ export interface I_ReturnBase {
29
+ success: boolean;
28
30
  message?: string;
29
31
  code?: number | string;
30
32
  }
31
- export interface I_ReturnFailure {
33
+ /**
34
+ * Success return type with result data.
35
+ * @template T - The main result type
36
+ * @template E - Additional properties to merge with the result (defaults to unknown)
37
+ */
38
+ export interface I_ReturnSuccess<T, E = unknown> extends I_ReturnBase {
39
+ success: true;
40
+ result: T & E;
41
+ }
42
+ /**
43
+ * Failure return type with error information.
44
+ */
45
+ export interface I_ReturnFailure extends I_ReturnBase {
32
46
  success: false;
33
47
  message: string;
34
48
  code: number | string;
35
49
  }
50
+ /**
51
+ * Discriminated union type for function return values.
52
+ * Provides type-safe handling of success and failure cases.
53
+ *
54
+ * @template T - The success result type (defaults to void)
55
+ * @template E - Additional properties to merge with the result (defaults to unknown)
56
+ *
57
+ * @example
58
+ * ```typescript
59
+ * function fetchUser(id: string): I_Return<User> {
60
+ * try {
61
+ * const user = await getUser(id);
62
+ * return { success: true, result: user };
63
+ * } catch (error) {
64
+ * return { success: false, message: error.message, code: 'USER_NOT_FOUND' };
65
+ * }
66
+ * }
67
+ * ```
68
+ */
36
69
  export type I_Return<T = void, E = unknown> = I_ReturnSuccess<T, E> | I_ReturnFailure;
37
70
  export declare enum E_Environment {
38
71
  PRODUCTION = "production",
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@cyberskill/shared",
3
3
  "type": "module",
4
- "version": "2.1.0",
4
+ "version": "2.2.0",
5
5
  "description": "CyberSkill Shared",
6
6
  "author": "Stephen Cheng",
7
7
  "license": "MIT",
@@ -207,7 +207,7 @@
207
207
  "test:unit": "tsx src/node/cli/index.ts test:unit"
208
208
  },
209
209
  "dependencies": {
210
- "@antfu/eslint-config": "4.19.0",
210
+ "@antfu/eslint-config": "5.0.0",
211
211
  "@apollo/client": "3.13.8",
212
212
  "@apollo/client-integration-nextjs": "0.12.2",
213
213
  "@apollo/server": "5.0.0",
@@ -271,7 +271,7 @@
271
271
  "@commitlint/cli": "19.8.1",
272
272
  "@commitlint/config-conventional": "19.8.1",
273
273
  "@eslint/config-inspector": "1.1.0",
274
- "@next/eslint-plugin-next": "15.4.3",
274
+ "@next/eslint-plugin-next": "15.4.4",
275
275
  "@testing-library/jest-dom": "6.6.3",
276
276
  "@testing-library/react": "16.3.0",
277
277
  "@types/apollo-upload-client": "18.0.0",
@@ -297,7 +297,7 @@
297
297
  "@types/yargs": "17.0.33",
298
298
  "@vitest/browser": "3.2.4",
299
299
  "eslint": "9.31.0",
300
- "eslint-config-next": "15.4.3",
300
+ "eslint-config-next": "15.4.4",
301
301
  "glob": "11.0.3",
302
302
  "lint-staged": "16.1.2",
303
303
  "node-modules-inspector": "1.0.0",