refactor: renames SpiesGroup to Sandbox

README.md

@@ -20,10 +20,10 @@
     - [spy.called](#spycalled)
     - [spy.callCount](#spycallcount)
     - [spy.restore()](#spyrestore)
-  - [Функция `createSpiesGroup`](#функция-createspiesgroup)
-  - [Методы группы шпионов](#методы-группы-шпионов)
-    - [group.on(...)](#groupon)
-    - [group.restore()](#grouprestore)
+  - [Функция `createSandbox`](#функция-createsandbox)
+  - [Методы песочницы](#методы-песочницы)
+    - [sandbox.on(...)](#sandboxon)
+    - [sandbox.restore()](#sandboxrestore)
 - [Тесты](#тесты)
 - [Лицензия](#лицензия)
 
@@ -38,13 +38,13 @@ npm install @e22m4u/js-spy
 *ESM*
 
 ```js
-import {createSpy, createSpiesGroup} from '@e22m4u/js-spy';
+import {createSpy, createSandbox} from '@e22m4u/js-spy';
 ```
 
 *CommonJS*
 
 ```js
-const {createSpy, createSpiesGroup} = require('@e22m4u/js-spy');
+const {createSpy, createSandbox} = require('@e22m4u/js-spy');
 ```
 
 ## Использование
@@ -167,7 +167,7 @@ addSpy.restore();
 например, восстановить их все разом.
 
 ```js
-import {createSpiesGroup} from '@e22m4u/js-spy';
+import {createSandbox} from '@e22m4u/js-spy';
 
 // объект с методами для отслеживания
 const service = {
@@ -186,16 +186,16 @@ function standaloneLogger(message) {
   console.log(`LOG: ${message}`);
 }
 
-// создание группы
-const group = createSpiesGroup();
+// создание песочницы
+const sandbox = createSandbox();
 
-// добавление шпионов в группу:
-//   метод group.on() работает аналогично createSpy(),
-//   но добавляет шпиона в группу и возвращает созданного
+// добавление шпионов в песочницу:
+//   метод sandbox.on() работает аналогично createSpy(),
+//   но добавляет шпиона в песочницу и возвращает созданного
 //   шпиона
-const fetchDataSpy = group.on(service, 'fetchData');
-const processItemSpy = group.on(service, 'processItem');
-const loggerSpy = group.on(standaloneLogger);
+const fetchDataSpy = sandbox.on(service, 'fetchData');
+const processItemSpy = sandbox.on(service, 'processItem');
+const loggerSpy = sandbox.on(standaloneLogger);
 
 // так как методы заменяются шпионами прямо на объекте,
 // допустимо вызывать непосредственно их
@@ -210,14 +210,14 @@ console.log(fetchDataSpy.callCount);   // 1
 console.log(processItemSpy.callCount); // 1
 console.log(loggerSpy.callCount);      // 1
 
-// восстановление всех шпионов в группе:
+// восстановление всех шпионов песочницы:
 //   - оригинальные методы service.fetchData
 //     и service.processItem будут восстановлены
 //   - история вызовов (callCount, called, calls и т.д.)
 //     для fetchDataSpy, processItemSpy и loggerSpy
 //     будет сброшена
-//   - внутренний список шпионов в группе будет очищен
-group.restore();
+//   - внутренний список шпионов песочницы будет очищен
+sandbox.restore();
 
 console.log(service.fetchData === fetchDataSpy);
 // false (оригинальный метод восстановлен)
@@ -345,7 +345,7 @@ expect(spy).on.nth(10).be.called.with('result');
 
 ### Свойства и методы шпиона
 
-Каждая функция-шпион, возвращаемая `createSpy` (или `group.on`), обладает
+Каждая функция-шпион, возвращаемая `createSpy` (или `sandbox.on`), обладает
 следующими свойствами и методами:
 
 #### spy(...args)
@@ -458,31 +458,31 @@ fnSpy.restore();
 console.log(fnSpy.callCount); // 0 (история сброшена)
 ```
 
-### Функция `createSpiesGroup`
+### Функция `createSandbox`
 
-Фабричная функция для создания экземпляра `SpiesGroup` (группа шпионов).
+Фабричная функция для создания экземпляра песочницы.
 
 ```js
-import {createSpiesGroup} from '@e22m4u/js-spy';
+import {createSandbox} from '@e22m4u/js-spy';
 
-const group = createSpiesGroup();
+const sandbox = createSandbox();
 ```
 
-### Методы группы шпионов
+### Методы песочницы
 
-Экземпляр `SpiesGroup` имеет следующие методы:
+Экземпляр `Sandbox` имеет следующие методы:
 
-#### group.on(...)
+#### sandbox.on(...)
 
-Создает шпиона и добавляет его в группу.
+Создает шпиона и добавляет его в песочницу.
 
 Сигнатуры вызова:
 
 1.  Отслеживание отдельной функции:  
-    `group.on(targetFn, [customImpl])`
+    `sandbox.on(targetFn, [customImpl])`
 
 2.  Отслеживание метода объекта:  
-    `group.on(targetObject, methodName, [customImpl])`
+    `sandbox.on(targetObject, methodName, [customImpl])`
 
 Возвращает:
 
@@ -491,34 +491,33 @@ const group = createSpiesGroup();
 Пример:
 
 ```js
-const group = createSpiesGroup();
+const sandbox = createSandbox();
 const obj = {greet: () => 'Hello'};
 
-const greetSpy = group.on(obj, 'greet');
-// obj.greet теперь шпион, и greetSpy добавлен в группу
+const greetSpy = sandbox.on(obj, 'greet');
+// obj.greet теперь шпион, и greetSpy добавлен в песочницу
 obj.greet();
 console.log(greetSpy.called); // true
 ```
 
-#### group.restore()
+#### sandbox.restore()
 
-Вызывает метод `restore()` для каждого шпиона, содержащегося в группе.
+Вызывает метод `restore()` для каждого шпиона, содержащегося в песочнице.
 Это означает, что:
 
 - Все оригинальные методы объектов, для которых были созданы шпионы
-  в этой группе, будут восстановлены.
-- История вызовов всех шпионов в группе будет сброшена.
-- Внутренний список шпионов в самой группе будет очищен, делая группу
-  готовой к повторному использованию (если необходимо).
+  в данной песочнице, будут восстановлены.
+- История вызовов всех шпионов в песочнице будет сброшена.
+- Внутренний список шпионов в песочнице будет очищен.
 
 Возвращает:
 
-- `this` (экземпляр `SpiesGroup`) для возможной цепочки вызовов.
+- `this` для возможной цепочки вызовов.
 
 Пример:
 
 ```js
-const group = createSpiesGroup();
+const sandbox = createSandbox();
 
 // объект с методом для отслеживания
 const service = {
@@ -529,8 +528,8 @@ const service = {
 function utilFn() { /* ... */ }
 
 // создание шпионов
-const processSpy = group.on(service, 'process');
-const utilSpy = group.on(utilFn);
+const processSpy = sandbox.on(service, 'process');
+const utilSpy = sandbox.on(utilFn);
 
 // вызов отслеживаемого метода
 // и шпиона одиночной функции
@@ -543,12 +542,12 @@ console.log(utilSpy.callCount);    // 1
 
 // восстановление шпионов
 // и сброс истории
-group.restore();
+sandbox.restore();
 
 // service.process теперь оригинальный метод
 console.log(processSpy.callCount); // 0
 console.log(utilSpy.callCount);    // 0
-console.log(group.spies.length);   // 0
+console.log(sandbox.spies.length);   // 0
 ```
 
 ## Тесты

dist/cjs/index.cjs

@@ -21,9 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.js
 var index_exports = {};
 __export(index_exports, {
-  SpiesGroup: () => SpiesGroup,
+  Sandbox: () => Sandbox,
   chaiSpies: () => chaiSpies,
-  createSpiesGroup: () => createSpiesGroup,
+  createSandbox: () => createSandbox,
   createSpy: () => createSpy
 });
 module.exports = __toCommonJS(index_exports);
@@ -414,8 +414,8 @@ function createSpy(target = void 0, methodNameOrImpl = void 0, customImplForMeth
 }
 __name(createSpy, "createSpy");
 
-// src/create-spies-group.js
-var _SpiesGroup = class _SpiesGroup {
+// src/create-sandbox.js
+var _Sandbox = class _Sandbox {
   /**
    * Constructor.
    */
@@ -424,7 +424,7 @@ var _SpiesGroup = class _SpiesGroup {
   }
   /**
    * Создает шпиона для отдельной функции
-   * или метода объекта и добавляет его в группу.
+   * или метода объекта и добавляет его в песочницу.
    *
    * @param {Function|object} [target]
    * @param {Function|string} [methodNameOrImpl]
@@ -438,9 +438,8 @@ var _SpiesGroup = class _SpiesGroup {
   }
   /**
    * Восстановление всех оригинальных методов объектов,
-   * для которых были созданы шпионы в этой группе,
-   * и сброс истории вызовов для всех шпионов в группе.
-   * Очищает внутренний список шпионов.
+   * для которых были созданы шпионы в данной песочнице,
+   * и сброс истории вызовов.
    *
    * @returns {this}
    */
@@ -450,16 +449,16 @@ var _SpiesGroup = class _SpiesGroup {
     return this;
   }
 };
-__name(_SpiesGroup, "SpiesGroup");
-var SpiesGroup = _SpiesGroup;
-function createSpiesGroup() {
-  return new SpiesGroup();
+__name(_Sandbox, "Sandbox");
+var Sandbox = _Sandbox;
+function createSandbox() {
+  return new Sandbox();
 }
-__name(createSpiesGroup, "createSpiesGroup");
+__name(createSandbox, "createSandbox");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  SpiesGroup,
+  Sandbox,
   chaiSpies,
-  createSpiesGroup,
+  createSandbox,
   createSpy
 });

src/create-sandbox.d.ts

@@ -0,0 +1,44 @@
+import {Spy} from './create-spy.js';
+import {MethodKey, AnyCallable} from './types.js';
+
+/**
+ * Песочница позволяет создавать шпионов
+ * и управлять ими как единым целым.
+ */
+export declare class Sandbox {
+  /**
+   * Внутренний массив, хранящий все шпионы.
+   */
+  spies: Spy<any>[];
+
+  /**
+   * Создает шпиона для отдельной функции
+   * и добавляет его в песочницу.
+   */
+  on<TFunc extends AnyCallable>(
+    target: TFunc,
+    customImpl?: TFunc,
+  ): Spy<TFunc>;
+
+  /**
+   * Создает шпиона для метода объекта, добавляет
+   * его в песочницу и заменяет оригинальный метод.
+   */
+  on<TObj extends object, K extends MethodKey<TObj>>(
+    target: TObj,
+    methodName: K,
+    customImpl?: AnyCallable,
+  ): Spy<Extract<TObj[K], AnyCallable>>;
+
+  /**
+   * Восстановление всех оригинальных методов объектов,
+   * для которых были созданы шпионы в данной песочнице,
+   * и сброс истории вызовов.
+   */
+  restore(): this;
+}
+
+/**
+ * Создание песочницы.
+ */
+export function createSandbox(): Sandbox;

src/create-spies-group.js → src/create-sandbox.js

@@ -1,10 +1,10 @@
 import {createSpy} from './create-spy.js';
 
 /**
- * Группа позволяет создавать шпионов
- * и управлять ими как одним.
+ * Песочница позволяет создавать шпионов
+ * и управлять ими как единым целым.
  */
-export class SpiesGroup {
+export class Sandbox {
   /**
    * Constructor.
    */
@@ -14,7 +14,7 @@ export class SpiesGroup {
 
   /**
    * Создает шпиона для отдельной функции
-   * или метода объекта и добавляет его в группу.
+   * или метода объекта и добавляет его в песочницу.
    *
    * @param {Function|object} [target]
    * @param {Function|string} [methodNameOrImpl]
@@ -29,9 +29,8 @@ export class SpiesGroup {
 
   /**
    * Восстановление всех оригинальных методов объектов,
-   * для которых были созданы шпионы в этой группе,
-   * и сброс истории вызовов для всех шпионов в группе.
-   * Очищает внутренний список шпионов.
+   * для которых были созданы шпионы в данной песочнице,
+   * и сброс истории вызовов.
    *
    * @returns {this}
    */
@@ -43,10 +42,10 @@ export class SpiesGroup {
 }
 
 /**
- * Создание группы шпионов.
+ * Создание песочницы.
  *
- * @returns {SpiesGroup}
+ * @returns {Sandbox}
  */
-export function createSpiesGroup() {
-  return new SpiesGroup();
+export function createSandbox() {
+  return new Sandbox();
 }

src/create-spies-group.spec.js → src/create-sandbox.spec.js

@@ -1,70 +1,73 @@
 import {expect} from 'chai';
-import {SpiesGroup, createSpiesGroup} from './create-spies-group.js';
+import {Sandbox, createSandbox} from './create-sandbox.js';
 
-describe('SpiesGroup', function () {
-  describe('createSpiesGroup factory', function () {
-    it('should return an instance of SpiesGroup', function () {
-      const group = createSpiesGroup();
-      expect(group).to.be.instanceOf(SpiesGroup);
+describe('Sandbox', function () {
+  describe('createSandbox factory', function () {
+    it('should return an instance of Sandbox', function () {
+      const sandbox = createSandbox();
+      expect(sandbox).to.be.instanceOf(Sandbox);
     });
 
     it('should initialize with an empty spies array', function () {
-      const group = createSpiesGroup();
-      expect(group.spies).to.be.an('array').that.is.empty;
+      const sandbox = createSandbox();
+      expect(sandbox.spies).to.be.an('array').that.is.empty;
     });
   });
 
-  describe('SpiesGroup instance', function () {
-    let group;
+  describe('Sandbox instance', function () {
+    let sandbox;
 
     beforeEach(function () {
-      group = createSpiesGroup();
+      sandbox = createSandbox();
     });
 
     describe('.on(target, methodNameOrImpl, customImplForMethod)', function () {
-      it('should create a spy using createSpy with the given arguments', function () {
+      it('should create a spy for a standalone function', function () {
         const targetFn = () => {};
-        const customImpl = () => {};
-        // шпион для standalone функции
-        const fnSpy = group.on(targetFn);
+        const fnSpy = sandbox.on(targetFn);
         expect(fnSpy).to.be.a('function');
-        // проверка, что это действительно шпион
         expect(fnSpy.callCount).to.equal(0);
-        // шпион для standalone функции с кастомной реализацией
-        const fnSpyWithImpl = group.on(targetFn, customImpl);
-        // вызов для проверки кастомной реализации
-        fnSpyWithImpl();
-        expect(fnSpyWithImpl.calls[0].returnValue).to.equal(customImpl());
-        // шпион для метода объекта
+        expect(fnSpy).to.have.property('calls');
+      });
+
+      it('should create a spy for a standalone function with a custom implementation', function () {
+        const targetFn = () => {};
+        const customImpl = () => 'custom result';
+        const fnSpy = sandbox.on(targetFn, customImpl);
+        fnSpy();
+        expect(fnSpy.calls[0].returnValue).to.equal('custom result');
+      });
+
+      it('should create a spy for an object method and replace the original method', function () {
         const obj = {method: () => 'original method'};
-        const methodSpy = group.on(obj, 'method');
-        // проверка замены метода
+        const methodSpy = sandbox.on(obj, 'method');
         expect(obj.method).to.equal(methodSpy);
-        // шпион для метода объекта с кастомной реализацией
-        const objWithCustom = {method: () => 'original method 2'};
-        const customMethodImpl = () => 'custom method';
-        group.on(objWithCustom, 'method', customMethodImpl);
-        // проверка вызова кастомной реализации
-        expect(objWithCustom.method()).to.equal('custom method');
+        expect(methodSpy).to.be.a('function');
+      });
+
+      it('should create a spy for an object method with a custom implementation', function () {
+        const obj = {method: () => 'original method'};
+        const customImpl = () => 'custom method';
+        sandbox.on(obj, 'method', customImpl);
+        expect(obj.method()).to.equal('custom method');
       });
 
       it('should add the created spy to the internal spies array', function () {
         const targetFn1 = () => {};
         const targetFn2 = () => {};
-        const spy1 = group.on(targetFn1);
-        expect(group.spies).to.have.lengthOf(1);
-        expect(group.spies[0]).to.equal(spy1);
-        const spy2 = group.on(targetFn2);
-        expect(group.spies).to.have.lengthOf(2);
-        expect(group.spies[1]).to.equal(spy2);
+        const spy1 = sandbox.on(targetFn1);
+        expect(sandbox.spies).to.have.lengthOf(1);
+        expect(sandbox.spies[0]).to.equal(spy1);
+        const spy2 = sandbox.on(targetFn2);
+        expect(sandbox.spies).to.have.lengthOf(2);
+        expect(sandbox.spies[1]).to.equal(spy2);
       });
 
       it('should return the created spy instance', function () {
         const targetFn = () => {};
-        const returnedSpy = group.on(targetFn);
+        const returnedSpy = sandbox.on(targetFn);
         expect(returnedSpy).to.be.a('function');
-        // проверка, что это тот же шпион, что и в массиве
-        expect(group.spies[0]).to.equal(returnedSpy);
+        expect(sandbox.spies[0]).to.equal(returnedSpy);
       });
     });
 
@@ -92,10 +95,10 @@ describe('SpiesGroup', function () {
           return 'standalone2';
         };
 
-        spyObj1 = group.on(obj1, 'method');
-        spyFn1 = group.on(standaloneFn1);
-        spyObj2 = group.on(obj2, 'method');
-        spyFn2 = group.on(standaloneFn2);
+        spyObj1 = sandbox.on(obj1, 'method');
+        spyFn1 = sandbox.on(standaloneFn1);
+        spyObj2 = sandbox.on(obj2, 'method');
+        spyFn2 = sandbox.on(standaloneFn2);
 
         // вызов всех шпионов для наполнения истории
         obj1.method(); // spyObj1
@@ -109,8 +112,8 @@ describe('SpiesGroup', function () {
         expect(spyFn2.callCount).to.equal(1);
       });
 
-      it('should call restore() on all spies in the group', function () {
-        group.restore();
+      it('should call restore() on all spies in the sandbox', function () {
+        sandbox.restore();
         // проверка восстановления методов объектов
         expect(obj1.method).to.equal(originalMethod1);
         expect(obj1.method()).to.equal('original1');
@@ -128,31 +131,31 @@ describe('SpiesGroup', function () {
       });
 
       it('should clear the internal spies array', function () {
-        expect(group.spies).to.have.lengthOf(4);
-        group.restore();
-        expect(group.spies).to.be.an('array').that.is.empty;
+        expect(sandbox.spies).to.have.lengthOf(4);
+        sandbox.restore();
+        expect(sandbox.spies).to.be.an('array').that.is.empty;
       });
 
-      it('should return the SpiesGroup instance for chaining (if other methods were added)', function () {
-        const returnedValue = group.restore();
-        expect(returnedValue).to.equal(group);
+      it('should return the Sandbox instance for chaining (if other methods were added)', function () {
+        const returnedValue = sandbox.restore();
+        expect(returnedValue).to.equal(sandbox);
       });
 
       it('should be idempotent - calling restore multiple times should not error', function () {
         // первый вызов restore
-        group.restore();
+        sandbox.restore();
         // второй вызов restore
-        expect(() => group.restore()).to.not.throw();
+        expect(() => sandbox.restore()).to.not.throw();
         // проверки состояний после второго вызова (должно быть таким же)
         expect(obj1.method).to.equal(originalMethod1);
         expect(spyObj1.callCount).to.equal(0);
-        expect(group.spies).to.be.an('array').that.is.empty;
+        expect(sandbox.spies).to.be.an('array').that.is.empty;
       });
 
       it('should handle an empty spies array gracefully', function () {
-        const emptyGroup = createSpiesGroup();
-        expect(() => emptyGroup.restore()).to.not.throw();
-        expect(emptyGroup.spies).to.be.an('array').that.is.empty;
+        const emptySandbox = createSandbox();
+        expect(() => emptySandbox.restore()).to.not.throw();
+        expect(emptySandbox.spies).to.be.an('array').that.is.empty;
       });
     });
   });

src/create-spies-group.d.ts

@@ -1,56 +0,0 @@
-import {Spy} from './create-spy.js';
-import {MethodKey, AnyCallable} from './types.js';
-
-/**
- * Представляет группу шпионов, позволяющую
- * управлять ими коллективно.
- */
-export declare class SpiesGroup {
-  /**
-   * Внутренний массив, хранящий все шпионы,
-   * созданные в этой группе. Не предназначен
-   * для прямого доступа.
-   */
-  spies: Spy<any>[];
-
-  /**
-   * Создает шпиона для отдельной функции
-   * и добавляет его в группу.
-   *
-   * @param target
-   * @param customImpl
-   */
-  on<TFunc extends AnyCallable>(
-    target: TFunc,
-    customImpl?: TFunc,
-  ): Spy<TFunc>;
-
-  /**
-   * Создает шпиона для метода объекта, добавляет
-   * его в группу и заменяет оригинальный метод
-   * объекта шпионом.
-   *
-   * @param target
-   * @param methodName
-   * @param customImpl
-   */
-  on<TObj extends object, K extends MethodKey<TObj>>(
-    target: TObj,
-    methodName: K,
-    customImpl?: AnyCallable,
-  ): Spy<Extract<TObj[K], AnyCallable>>;
-
-  /**
-   * Восстановление всех оригинальных методов объектов,
-   * для которых были созданы шпионы в этой группе,
-   * и сброс истории вызовов для всех шпионов в группе.
-   * Очищает внутренний список шпионов.
-   */
-  restore(): this;
-}
-
-/**
- * Фабричная функция для создания
- * нового экземпляра `SpiesGroup`.
- */
-export function createSpiesGroup(): SpiesGroup;

src/index.d.ts

@@ -1,3 +1,3 @@
 export * from './chai/index.js';
 export * from './create-spy.js';
-export * from './create-spies-group.js';
+export * from './create-sandbox.js';

src/index.js

@@ -1,3 +1,3 @@
 export * from './chai/index.js';
 export * from './create-spy.js';
-export * from './create-spies-group.js';
+export * from './create-sandbox.js';