{"id":28089238,"url":"https://github.com/toviszsolt/stormflow","last_synced_at":"2025-05-13T12:55:24.050Z","repository":{"id":192713086,"uuid":"687256140","full_name":"toviszsolt/stormflow","owner":"toviszsolt","description":"StromFlow - A Lightweight Data Modeling and Storage Library","archived":false,"fork":false,"pushed_at":"2024-12-04T03:47:53.000Z","size":703,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-24T21:56:49.062Z","etag":null,"topics":["data","database","datamanagement","datastore","db","document","jsondatabase","memorydatabase","model","mongodb","mongoose","nodb","nosql","query","schema","stormflow"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/stormflow","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toviszsolt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":"FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["toviszsolt"],"paypal":["toviszsolt"]}},"created_at":"2023-09-05T01:36:40.000Z","updated_at":"2024-06-11T01:25:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"3eb95163-dafd-4475-9579-946822e05375","html_url":"https://github.com/toviszsolt/stormflow","commit_stats":null,"previous_names":["toviszsolt/stormflow"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toviszsolt%2Fstormflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toviszsolt%2Fstormflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toviszsolt%2Fstormflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toviszsolt%2Fstormflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toviszsolt","download_url":"https://codeload.github.com/toviszsolt/stormflow/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253948333,"owners_count":21988953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data","database","datamanagement","datastore","db","document","jsondatabase","memorydatabase","model","mongodb","mongoose","nodb","nosql","query","schema","stormflow"],"created_at":"2025-05-13T12:55:23.372Z","updated_at":"2025-05-13T12:55:24.032Z","avatar_url":"https://github.com/toviszsolt.png","language":"JavaScript","funding_links":["https://github.com/sponsors/toviszsolt","toviszsolt","https://www.paypal.com/paypalme/toviszsolt"],"categories":[],"sub_categories":[],"readme":"[![GitHub License](https://img.shields.io/github/license/toviszsolt/stormflow?style=flat)](https://github.com/toviszsolt/stormflow/blob/main/LICENSE)\n[![npm](https://img.shields.io/npm/v/stormflow?style=flat\u0026color=red)](https://www.npmjs.com/package/@toviszsolt/stormflow)\n[![GitHub Repo stars](https://img.shields.io/github/stars/toviszsolt/stormflow?color=DAAA3F)](https://github.com/toviszsolt/stormflow/stargazers)\n[![Run tests](https://github.com/toviszsolt/stormflow/actions/workflows/main.yml/badge.svg)](https://github.com/toviszsolt/stormflow/actions/workflows/main.yml)\n[![codecov](https://codecov.io/gh/toviszsolt/stormflow/graph/badge.svg?token=IONV9YMZXG)](https://codecov.io/gh/toviszsolt/stormflow)\n[![Sponsor](https://img.shields.io/static/v1?label=sponsor\u0026message=❤\u0026color=ff69b4)](https://github.com/sponsors/toviszsolt)\n\n# StormFlow\n\nA Lightweight Data Modeling and Storage Library\n\n## Introduction\n\nStormFlow is a lightweight data modeling and storage library for Node.js. It provides a simple and flexible way to\ncreate, query, and manage data collections with schemas. StormFlow is particularly well-suited for small to medium-sized\nprojects where you need a data storage solution without the complexity of a full-fledged database.\n\n\u003c!-- StormFlow is a versatile Node.js data management library designed for efficient data handling and\npersistence. It provides a robust framework for creating, updating, querying, and storing data\ncollections, along with built-in support for data schema management. With StormFlow, you can\nstreamline data operations and enhance data integrity in your Node.js applications, making it an\nessential tool for full-stack developers. --\u003e\n\n## Features\n\n- **Data Modeling:** Define data schemas using the Schema module to ensure data consistency and structure.\n\n- **Data Collection:** Create and manage collections of data with CRUD (Create, Read, Update, Delete) operations.\n\n- **Middleware Support:** Add custom pre and post middleware functions to intercept and modify data operations.\n\n- **Querying:** Use powerful queries to retrieve data from collections based on criteria.\n\n- **Data Persistence:** StormFlow supports data persistence to disk, allowing you to store and retrieve data even after\n  the application restarts.\n\n- **References:** Easily handle references between objects in your data model.\n\n## Compatibility\n\nThis package includes both `ES modules` and `CommonJS` versions, so you can safely use both `require` and `import`\nstatements in any environment. In the examples I'll use the `require` syntax, so don't be scared, feel free to use the\n`import` syntax if you like, that will work too. TypeScript support is also available.\n\n## Getting Started\n\n### Installation\n\nTo get started with StormFlow, you can install it using yarn or npm:\n\n```bash\nyarn add stormflow\n```\n\n```bash\nnpm i stormflow\n```\n\n### Initializing StormFlow\n\nBefore using StormFlow, you need to initialize it with your configuration. Here's an example of how to start StormFlow\nwith default options:\n\n```js\nconst db = require('stormflow');\n\ndb.start({ dataFolder: './data_blog' });\n```\n\nYou can also provide custom configuration options when initializing StormFlow.\n\n### Creating Models\n\nStormFlow allows you to define data models with schemas. Schemas help validate and structure your data. Here's an\nexample of creating a model with a schema:\n\n```js\nconst db = require('stormflow');\n\nconst userSchema = db.Schema({\n  name: String,\n  email: {\n    type: String,\n    required: true,\n  },\n  age: Number,\n})\n\nconst User = db.model('user', userSchema});\n```\n\nCRUD Operations Once you've defined a model, you can perform CRUD (Create, Read, Update, Delete) operations on your\ndata. Here are some examples:\n\n```js\n// Create a new user\nconst newUser = await User.create({ name: 'John', email: 'john@example.com' });\n\n// Find users based on a query\nconst users = await User.find({ age: { $gte: 18 } });\n\n// Update a user\nconst updatedUser = await User.update({ _id: newUser._id }, { age: 30 });\n\n// Delete a user\nconst deletedUser = await User.deleteOne({ _id: newUser._id });\n```\n\n### Middleware\n\nStormFlow supports middleware functions that can be executed before or after CRUD operations. You can register\nmiddleware functions for your models. For example:\n\n```js\nUser.pre('create', async (user, next) =\u003e {\n  // Do something before creating a user\n  console.log('Creating user:', user.name);\n  next();\n});\n\nUser.post('update', async (user, next) =\u003e {\n  // Do something after updating a user\n  console.log('User created:', user.name);\n  next();\n});\n```\n\n## File-Based Storage\n\nStormFlow supports file-based storage, allowing you to persist your data. By default, StormFlow will store data in a\n'data' directory in your project's root.\n\n## Statistics\n\nYou can retrieve statistics about disk writes and skipped writes using StormFlow's stats feature.\n\n```js\nconst stats = db.stats();\nconsole.log('Disk Writes in user collection:', stats.diskWrites.user);\nconsole.log('Skipped Writes user collection:', stats.skippedWrites.user);\n```\n\n## Documentation\n\n### start(options)\n\nInitializes the module with the provided options.\n\n#### Parameters\n\n- `options` (Object, optional): An object with configuration options.\n\n| Option              | Type    | Default    | Description                                                                          |\n| ------------------- | ------- | ---------- | ------------------------------------------------------------------------------------ |\n| `dataDirectory`     | String  | `'./data'` | The directory where data and backup files are stored.                                |\n| `diskWrite`         | Boolean | `true`     | Enables or disables disk write operations.                                           |\n| `diskWriteThrottle` | Number  | `100`      | Time interval (in milliseconds) for disk write throttling.                           |\n| `backupFiles`       | Boolean | `true`     | Enables or disables backup file (GZip) creation.                                     |\n| `defaultFields`     | Boolean | `true`     | Enables or disables make default `_created` and `_updated` fields as Unix timestamp. |\n| `verbose`           | Boolean | `false`    | Enables or disables the verbose mode in console.                                     |\n\n#### Example\n\n```js\n// Initialize the module with custom options\ndb.start({\n  dataDirectory: './my-data',\n  diskWrite: true,\n  diskWriteThrottle: 200,\n  backupFiles: false,\n  defaultFields: false,\n});\n```\n\n### Schema(schemaObj)\n\nCreates a schema for data models. Pass an object defining the schema structure.\n\n#### Parameters\n\n- `schemaObj` (Object): An object defining the schema structure. The keys represent field names, and the values define\n  field constraints.\n\n#### Returns\n\nA schema object that can be used when creating data models.\n\n#### Example\n\n```js\nconst db = require('db');\n\n// Define a schema for a user model\nconst userSchema = db.Schema({\n  name: String,\n  age: Number,\n  email: {\n    type: String,\n    required: true,\n  },\n  address: {\n    street: String,\n    city: String,\n    zipCode: String,\n  },\n});\n\n// Use the userSchema when creating a data model\nconst UserModel = db.model('users', userSchema);\n\n// Create a new user\nconst newUser = UserModel.create({\n  name: 'Alice',\n  age: 28,\n  email: 'alice@example.com',\n  address: {\n    street: '123 Main St',\n    city: 'Exampleville',\n    zipCode: '12345',\n  },\n});\n```\n\n### `model(collectionName, schema)`\n\nCreates a data model for a collection based on the provided schema.\n\n#### Parameters\n\n- `collectionName` (String): The name of the collection. It is used to identify the collection and its associated data.\n- `schema` (Object): The schema for the collection, defining the structure and constraints of its data.\n\n#### Returns\n\nAn object with methods for performing CRUD (Create, Read, Update, Delete) operations on the collection's data.\n\n#### Example\n\n```js\nconst db = require('db');\n\n// Define a schema for a user model\nconst userSchema = db.Schema({\n  name: String,\n  age: Number,\n  email: {\n    type: String,\n    required: true,\n  },\n});\n\n// Create a data model for the \"users\" collection\nconst UserModel = db.model('users', userSchema);\n\n// Create a new user\nconst newUser = UserModel.create({ name: 'Alice', age: 28, email: 'alice@example.com' });\n\n// Find users matching a query\nconst usersAbove25 = UserModel.find({ age: { $gt: 25 } });\n\n// Update a user's age\nUserModel.update({ name: 'Alice' }, { age: 29 });\n\n// Delete a user by ID\nUserModel.deleteOne({ \\_id: newUser.\\_id });\n```\n\nReturns an object with the following methods:\n\n- `create(items)`: Create new items in the collection.\n- `find(query)`: Find items in the collection based on a query.\n- `findById(id)`: Find an item by its ID.\n- `findOne(query)`: Find the first item matching the query.\n- `count(query)`: Count the number of items matching the query.\n- `exists(query)`: Check items in the collection based on a query.\n- `update(query, updates)`: Update items in the collection.\n- `deleteOne(query)`: Delete one item matching the query.\n- `deleteMany(query)`: Delete multiple items matching the query.\n\n### Query Parameter\n\nThe query parameter is an essential part of data retrieval when using the functions provided by the model object. It\nallows you to filter and search for specific data items within a collection based on defined criteria.\n\n#### Basic Query\n\nA basic query consists of a JavaScript object where each key represents a field in the data, and the corresponding value\nis the condition you want to apply to that field. Here's a breakdown:\n\n- Field Key: This should be a string that matches a field name in your data schema.\n- Condition Value: The value associated with the field key defines the condition for filtering data. It can be of\n  various types, such as strings, numbers, booleans, or objects, depending on your schema.\n\n#### Example\n\n```js\n// Find users with the name \"John\"\nconst johnUsers = UserModel.find({ name: 'John' });\n```\n\nIn this example, we use a basic query to find all users whose name field matches the string 'John'. The UserModel.find()\nmethod will return an array of user objects that meet this condition.\n\n### Comparison Query Operators\n\nYou can create more complex queries by using operators like `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$nin`\nand `$regex`. Here's how they work:\n\n- `$eq` (Equal): Matches values that are equal to a specified value.\n- `$ne` (Not Equal): Matches values that are not equal to a specified value.\n- `$lt` (Less Than): Matches values less than the specified value.\n- `$lte` (Less Than or Equal): Matches values less than or equal to the specified value.\n- `$gt` (Greater Than): Matches values greater than the specified value.\n- `$gte` (Greater Than or Equal): Matches values greater than or equal to the specified value.\n- `$in` (In Array): Matches values that exist in the specified array.\n- `$nin` (Not In Array): Matches values that not exist in the specified array.\n- `$regex` (Regular Expression): Matches values using a regular expression pattern.\n\n#### Examples\n\n```js\n// Find users younger than 30\nconst youngUsers = UserModel.find({ age: { $lt: 30 } });\n\n// Find users with ages between 25 and 35\nconst midAgeUsers = UserModel.find({ $and: [{ age: { $gt: 25 } }, { age: { $lt: 35 } }] });\n\n// Find users with specific emails\nconst specificEmailUsers = UserModel.find({\n  email: { $in: ['john@example.com', 'alice@example.com'] },\n});\n\n// Find users with names starting with \"A\" using regex\nconst aNames = UserModel.find({ name: { $regex: '^A', $options: 'i' } });\n```\n\nIn these examples, we use advanced queries to find users based on various conditions, such as age range, email existence\nin an array, and names matching a regular expression pattern.\n\n### Logical Query Operators\n\nYou can also use logical operators like `$and`, `$or`, `$not`, `$nor` to combine multiple conditions within a single\nquery.\n\n- `$and`: the operator joins query clauses with a logical AND operator. It returns data that satisfies all of the\n  specified conditions within the query.\n- `$or`: the operator accepts an array of query objects and returns data that satisfies at least one of the conditions.\n  It's used when you want to match documents that meet any of the specified conditions.\n- `$not`: the operator joins query clauses with a logical NOT operator. It returns data that doesn't match the specified\n  condition within the query. It's used to exclude documents that meet a certain condition.\n- `$nor`: the operator joins query clauses with a logical NOR operator. It returns data that doesn't satisfy any of the\n  conditions within the array. It's useful when you want to exclude documents that match any of the specified\n  conditions.\n\n#### Example\n\n```js\n// Find users with either age less than 25 or age greater than 40\nconst youngOrElderUsers = UserModel.find({\n  $or: [{ age: { $lt: 25 } }, { age: { $gt: 40 } }],\n});\n```\n\nIn this example, we use the $or operator to find users who are either younger than 25 or older than 40.\n\nThese query options provide powerful filtering capabilities for your data, allowing you to retrieve specific records\nthat meet your criteria efficiently.\n\n#### Notes:\n\n- When using multiple conditions in a query, the logical operators like $or help create complex queries to find data\n  that matches any of the conditions.\n- Combining basic and advanced queries allows for fine-grained data retrieval based on your schema's structure and the\n  specific requirements of your application.\n- Always refer to your schema definition to ensure that the field names and types in your query match the schema's\n  structure.\n\n  This concludes the documentation on how the query parameter works when using the model functions for data querying.\n\n## stats()\n\nReturns statistics about data operations, such as disk writes and skipped writes.\n\n## Guidelines\n\nTo learn about the guidelines, please read the [Code of Conduct](./CODE_OF_CONDUCT.md),\n[Contributing](./CONTRIBUTING.md) and [Security Policy](./SECURITY.md) documents.\n\n## License\n\nMIT License @ 2022 [Zsolt Tövis](https://github.com/toviszsolt)\n\nIf you found this project interesting, please consider supporting my open source work by\n[sponsoring me on GitHub](https://github.com/sponsors/toviszsolt) /\n[sponsoring me on PayPal](https://www.paypal.com/paypalme/toviszsolt) /\n[give the repo a star](https://github.com/toviszsolt/stormflow).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoviszsolt%2Fstormflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoviszsolt%2Fstormflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoviszsolt%2Fstormflow/lists"}