@itreg/shuffle-array 0.1.0

package/.github/ISSUE_TEMPLATE/FEATURE_REQUEST_TEMPLATE.md

@@ -0,0 +1,40 @@
+---
+name: "Feature Request"
+about: "Suggest a new feature or enhancement"
+title: ""
+labels: "feature"
+assignees: ""
+---
+
+## Summary
+
+<!--
+Please provide a short summary of the feature or enhancement you'd like to see.
+-->
+
+## Motivation
+
+<!--
+Explain why this feature would be useful. Are you facing any limitations or is it filling a gap?
+Try to provide a clear use-case.
+-->
+
+## Proposed Solution
+
+<!--
+Describe your idea of how you’d like this feature to function.
+It’s helpful to be as specific as possible.
+Feel free to add mockups or pseudo-code.
+-->
+
+## Alternatives
+
+<!--
+If you’ve considered any alternative solutions or workarounds, please list them here.
+-->
+
+## Additional Context
+
+<!--
+Include any other details or visuals that may help clarify the request.
+-->

package/.github/ISSUE_TEMPLATE/ISSUE_TEMPLATE.md

@@ -0,0 +1,58 @@
+---
+name: "Bug Issue"
+about: "Submit a bug report"
+title: ""
+labels: "bug"
+assignees: ""
+---
+
+## Description
+
+<!--
+Please provide a clear and concise description of the issue or feature request.
+For a bug report, describe the bug. For a feature, describe the enhancement you would like to see.
+-->
+
+## Steps to Reproduce (for bugs)
+
+<!--
+1. Outline the exact steps to reproduce the problem.
+2. Detail any environment or configuration changes that might be relevant.
+3. Include any code snippets or console logs, if helpful.
+-->
+
+1. ...
+2. ...
+3. ...
+
+## Expected Behavior (for bugs)
+
+<!--
+What should have happened?
+-->
+
+## Actual Behavior (for bugs)
+
+<!--
+What actually happened instead?
+-->
+
+## Proposed Solution or Feature Request
+
+<!--
+If you are requesting a feature or have a suggested fix/solution for the bug, please provide details here.
+-->
+
+## Additional Context
+
+<!--
+Add any other context, screenshots, videos, or additional information that may be helpful.
+-->
+
+## Environment
+
+- **Package Version**:
+- **Node.js Version**:
+- **Browser (if applicable)**:
+- **Operating System**:
+- **Additional Details**:

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,61 @@
+## Description
+
+<!-- Provide a short summary explaining the purpose of this pull request. -->
+
+
+## Related Issue
+
+<!-- If this pull request fixes or is related to an existing issue, link to it here. -->
+<!-- For example: "Closes #123" or "Fixes #123" -->
+
+
+## Type of Change
+
+<!-- Mark with an x all the checkboxes that apply (like [x]). -->
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactoring (no functional changes, no API changes)
+- [ ] Documentation update
+- [ ] Other (please describe):
+
+## Proposed Changes
+
+<!--
+Provide additional details regarding the changes made.
+For example, list out key points you implemented or refactored.
+-->
+
+1. ...
+2. ...
+3. ...
+
+## How Has This Been Tested?
+
+<!--
+Describe the tests you ran to ensure the code works as expected.
+Include instructions so we can reproduce your tests.
+-->
+
+- [ ] Unit Tests
+- [ ] Integration Tests
+- [ ] Manual Testing
+
+**Test Configuration**:
+- Node.js Version:
+- NPM/Yarn Version:
+- Operating System:
+
+## Checklist
+
+- [ ] I have read the [contribution guidelines](../CONTRIBUTING.md).
+- [ ] My code follows the style of this project.
+- [ ] I have added tests to cover my changes.
+- [ ] All new and existing tests passed.
+- [ ] I have updated the documentation as needed (inline code comments / README / any other relevant documentation).
+
+## Additional Comments
+
+<!--
+Add any other context or screenshots about the pull request here.
+-->

package/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+
+# Contributing to @yourusername/shuffle-array
+
+> Thank you for your interest in contributing! Your help is greatly appreciated.
+
+## Table of Contents
+
+- [How Can You Contribute?](#how-can-you-contribute)
+- [Development Setup](#development-setup)
+- [Committing Changes](#committing-changes)
+
+## How Can You Contribute?
+
+1. **Report Bugs**
+   - If you find any bugs, please open an issue in the repository. Please follow the [ISSUE_TEMPLATE.md](./.github/ISSUE_TEMPLATE/ISSUE_TEMPLATE.md)
+
+2. **Suggest Features**
+   - If you have an idea for a feature or improvement, feel free to open an issue describing your idea. Please follow the [FEATURE_REQUEST_TEMPLATE.md](./.github/ISSUE_TEMPLATE/FEATURE_REQUEST_TEMPLATE.md)
+
+3. **Create Pull Requests**
+   - PRs for bug fixes, enhancements, or documentation updates are always welcome.
+   - Please ensure all tests pass and that the code is well-documented.
+   - Please follow the [PULL_REQUEST_TEMPLATE.md](./.github/PULL_REQUEST_TEMPLATE.md)
+
+## Development Setup
+
+1. **Clone the repository**:
+   ```sh
+   git clone https://github.com/yourusername/shuffle-array.git
+   cd shuffle-array
+   ```
+2. **Install dependencies**:
+   ```sh
+   npm install
+   ```
+3. **Build the package**:
+   ```sh
+   npm run build
+   ```
+4. **Run tests**:
+   ```sh
+   npm run tests
+   ```
+
+## Committing Changes
+
+Please follow these guidelines for commit messages and pull requests:
+- **Commit Message Format**: Commit messages should be descriptive, e.g., `feat: add new shuffle algorithm` following the [Conventional Commits Specification](https://www.conventionalcommits.org/en). It is easy to follow if you are using the [semantic-git-commit-cli](https://www.npmjs.com/package/semantic-git-commit-cli)
+- **Pull Request**: If you open a Pull Request please follow the [PULL_REQUEST_TEMPLATE.md](./.github/PULL_REQUEST_TEMPLATE.md).

package/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2025-current <YOUR-NAME>
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# @yourusername/shuffle-array (Class 2 Example)
+
+> A small library that takes an array as input and returns a new array that is shuffled.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+   - [Examples](#examples)
+- [Contribution](#contribution)
+- [Security](#security)
+- [License](#license)
+
+## Installation
+
+Install via npm:
+
+```bash
+npm install @yourusername/shuffle-array
+```
+Install via yarn:
+
+```bash
+yarn add @yourusername/shuffle-array
+```
+
+## Usage
+
+Basic Usage
+
+```js
+import shuffleArray from '@yourusername/shuffle-array';
+
+const startArray = [1, 2, 3, 4, 5];
+const newShuffledArray = shuffleArray(startArray);
+
+console.log(startArray);       // e.g., [1, 2, 3, 4, 5]
+console.log(newShuffledArray); // e.g., [3, 1, 5, 2, 4]
+```
+
+### Examples
+
+Shuffle a list of user IDs:
+
+```js
+import shuffleArray from '@yourusername/shuffle-array';
+
+const userIds = ['u1', 'u2', 'u3', 'u4'];
+const randomizedOrderOfUserIds = shuffleArray(userIds);
+
+console.log(randomizedOrderOfUserIds); // e.g., ['u1', 'u3', 'u4', 'u2']
+```
+
+Use in a game for randomizing cards:
+
+```js
+import shuffleArray from '@yourusername/shuffle-array';
+
+const deck = ['Ace of Spades', 'Two of Hearts']; // some card deck
+const shuffledDeck = shuffleArray(deck);
+
+console.log(shuffledDeck); // e.g., ['Two of Hearts', 'Ace of Spades', ...]
+```
+
+## Contribution
+
+Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for more details.
+
+## Security
+
+Please refer to our [SECURITY.md](./SECURITY.md) for information about our security policies, how to report vulnerabilities, and our approach to handling security concerns.
+
+**Important Note**: This library uses non-cryptographic randomness (`Math.random()`). Do not rely on it for security-critical functionality.
+
+## License
+
+This project is licensed under the [MIT License](./LICENSE.md).

package/SECURITY.md

@@ -0,0 +1,38 @@
+# Security Policy
+
+We only provide official security updates for the current major release (e.g., `1.x`). Older versions may not be actively maintained or patched for vulnerabilities.
+
+## Supported Versions
+
+| Version | Supported |
+| ------- | --------- |
+| 1.x     | ✅        |
+| 0.x     | ❌        |
+
+## Reporting a Vulnerability
+
+We take security issues seriously and appreciate your efforts to responsibly disclose them. If you believe you have found a security vulnerability in this project, please follow these steps:
+
+1. **Contact the Team**
+   Send an email to **[security@yourdomain.com](mailto:security@yourdomain.com)** with a clear description of the issue, the steps to reproduce it, and any potential impact it may have.
+
+2. **Do Not Disclose Publicly**
+   Please do not file a public issue for a vulnerability, as it may put other users at risk. We ask that you keep any discovered vulnerabilities confidential until we have a fix in place.
+
+3. **Confirmation**
+   You should receive an acknowledgment of your report within **72 hours**. If you do not hear back, feel free to follow up.
+
+4. **Fix & Disclosure**
+   After we address the issue, we will release a fix as soon as possible. We will also publish a short advisory and acknowledge your contribution once the patch is made public.
+
+## Scope
+
+- Our project does not handle sensitive data like passwords or personal user information beyond normal usage.
+- Please note that this library uses non-cryptographic randomness (e.g., `Math.random()`) and therefore is **not** intended for security-critical tasks.
+
+## Resources
+
+- [GitHub Security Documentation](https://docs.github.com/en/code-security)
+- [Responsible Disclosure Guidelines](https://en.wikipedia.org/wiki/Responsible_disclosure)
+
+Thank you for helping us keep this project secure!

package/jest.config.js

@@ -0,0 +1,10 @@
+// jest.config.js
+module.exports = {
+  testEnvironment: 'node', // sets the test environment to Node.js
+  moduleFileExtensions: ['js', 'json'], // recognize .js and .json files
+  testMatch: ['**/?(*.)+(spec).js'], // run files ending with .spec.js
+  // Uncomment the transform section if you're using ES6+ features that need Babel
+  // transform: {
+  //   '^.+\\.jsx?$': 'babel-jest'
+  // },
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@itreg/shuffle-array",
+  "version": "0.1.0",
+  "description": "A small library that takes an array as input and returns a new array that is shuffled.",
+  "main": "dist/index.js",
+  "umd:main": "dist/index.umd.js",
+  "module": "dist/index.m.js",
+  "source": "src/index.js",
+  "scripts": {
+    "build": "microbundle",
+    "pretest": "npm run build",
+    "test": "npx jest --coverage"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itregit/shuffle-array.git"
+  },
+  "keywords": [
+    "array",
+    "shuffle",
+    "functional"
+  ],
+  "author": "itreg",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/itregit/shuffle-array/issues"
+  },
+  "homepage": "https://github.com/itregit/shuffle-array#readme",
+  "devDependencies": {
+    "jest": "^29.7.0",
+    "microbundle": "^0.15.1"
+  }
+}

package/src/index.js

@@ -0,0 +1,6 @@
+export default function shuffleArray(array) {
+  return array
+    .map(value => ({ value, sort: Math.random() }))
+    .sort((currentItem, nextItem) => currentItem.sort - nextItem.sort)
+    .map(({ value }) => value);
+};

package/test/index.spec.js

@@ -0,0 +1,19 @@
+const shuffleArray = require('../dist/index');
+
+describe('shuffleArray', () => {
+  test('returns a new array with the same elements as the input', () => {
+    const originalArray = [1, 2, 3, 4, 5];
+    const shuffledArray = shuffleArray(originalArray);
+
+    // Check that a new array is returned (not the same reference)
+    expect(shuffledArray).not.toBe(originalArray);
+
+    // Check that the array lengths are identical
+    expect(shuffledArray.length).toBe(originalArray.length);
+
+    // Check that both arrays contain the same elements, regardless of order
+    const sortedOriginal = [...originalArray].sort((a, b) => a - b);
+    const sortedShuffled = [...shuffledArray].sort((a, b) => a - b);
+    expect(sortedShuffled).toEqual(sortedOriginal);
+  });
+});