{"id":13520425,"url":"https://github.com/fuse-box/fusedb","last_synced_at":"2025-05-04T07:31:06.928Z","repository":{"id":26894486,"uuid":"109400605","full_name":"fuse-box/fusedb","owner":"fuse-box","description":"FuseDB - blazing fast ORM with simplicity in mind with love from FuseBox","archived":false,"fork":false,"pushed_at":"2022-12-10T20:31:17.000Z","size":208,"stargazers_count":29,"open_issues_count":10,"forks_count":4,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-24T13:45:55.713Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fuse-box.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-03T13:47:02.000Z","updated_at":"2022-10-01T04:19:05.000Z","dependencies_parsed_at":"2023-01-14T05:31:38.987Z","dependency_job_id":null,"html_url":"https://github.com/fuse-box/fusedb","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fuse-box%2Ffusedb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fuse-box%2Ffusedb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fuse-box%2Ffusedb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fuse-box%2Ffusedb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fuse-box","download_url":"https://codeload.github.com/fuse-box/fusedb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224389542,"owners_count":17303296,"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":[],"created_at":"2024-08-01T05:02:20.313Z","updated_at":"2024-11-13T04:28:13.837Z","avatar_url":"https://github.com/fuse-box.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/fuse-box/fusedb.svg?branch=master)](https://travis-ci.org/fuse-box/fusedb)\n\n# FuseDB\n\nFuseDB is an ORM with traditional ActiveRecord approach, that provides a simple yet powerful API. FuseDB stores data in the filesystem ([nedb](https://github.com/louischatriot/nedb)) or MongoDB. You write your own [adapter](https://github.com/fuse-box/fusedb/blob/master/src/adapters/Adapter.ts) and implement a different database suppport.\n\nIt's perfectly suitable for medium scale databases or Electron apps and takes 5 minutes to dive in.\n\n\nCheckout this [example](https://github.com/fuse-box/fusedb-example)\n\n\n## Setting up a connection\n\nEverything works by default, and the files will be stored in your home folder e.g `/home/user/.fusedb` on linux or `/Users/user/.fusedb` on mac. In order to customise it, do the following\n\n### File database \n```js\nimport { FuseDB, FileAdapter } from \"fusedb\"\nFuseDB.setup({ adapter : \n    FileAdapter({ path: \"/path/to/folder/\", database: \"test\" }) });\n```\n\n### MongoDB database\nInstall mongo module first\n```bash\nnpm install mongodb --save\n```\n\n```js\nimport { FuseDB, MongoAdapter } from \"fusedb\";\nFuseDB.setup({\n    adapter: MongoAdapter({\n        url : \"mongodb://localhost:27017/fusedb\",\n        dbName : \"myProject\"\n    })\n});\n```\n\n## Models\n\n\nModels contain essential methods to talk to the database, methods like `save`, `find`, `remove` are reserved. Therefore we don't need any \"repositories\" and connection pools as everything is handled internally\n\n```js\nimport { Field, Model } from \"fusedb\";\n\nclass Author extends Model\u003cAuthor\u003e {\n    @Field()\n    public name: string;\n\n    @Field()\n    public books: Book[];\n}\n\n\nclass Book extends Model\u003cBook\u003e {\n    @Field()\n    public name: string;\n\n    @Field()\n    public author: Author;\n}\n```\n\n`Field` decorator tells fusedb to serialize the field. There are a few reserved methods:\n\n### Creating records\n\n```js\nconst john = new Author({ name: \"John\" });\nawait john.save();\n\nconst book1 = new Book({ name: \"book1\", author: john });\nconst book2 = new Book({ name: \"book2\", author: john });\n\nawait book1.save();\nawait book2.save();\n\n\njohn.books = [book1, book2];\nawait john.save();\n```\n\nFuseDB will save references as `ids` and it won't store the entire model\n\n\n### Field decorator\n\nField decorator has a few properties you might find useful\n\n#### hidden\n\nHiding your field when sending to view\n```ts\n@Field({ hidden : true })\npublic password: string;\n```\n\n#### toJSON\nDefine custom serialiser when sending to view\n```ts\n@Field({ \n    toJSON : value =\u003e moment(value).format(\"LLLL\") \n})\npublic date: Date;\n```\n\n### Finding\n\nFirst record:\n\n```js\nconst author = await Author.find\u003cAuthor\u003e({ name: \"john\" }).first();\n```\n\nAll records:\n\n```js\nconst authors = await Author.find\u003cAuthor\u003e({\n        name : {$in : [\"a\", \"b\"]}\n        }).all();\n```\n\nCount:\n\n```js\nconst num = await Author.find\u003cAuthor\u003e().count();\n```\n\n\n\n### Query normalization \n\n#### ObjectID\nYou don't need to convert strings to ObjectID When you using MongoAdapter. FuseDB does it for you.\n\nfor example:\n\n```ts\n const record = await Foo.findById\u003cFoo\u003e(\"5b290c188e9f69ab51c3bd41\");\n```\n\nIt will be applied for `find` method recursively for example\n\n```ts\n await Foo.find\u003cFoo\u003e({\n     _id : $in : [\"5b290c188e9f69ab51c3bd41\", \"5b290c188e9f69ab51c3bd42\"]\n  }).first()\n```\n\n#### Passing real objects to query\n\nInstead of extracting IDs you can pass a real FuseDB Model to the query. For example\n\n```ts\nconst group = await Group.find({name : \"admin\"}).first();\nconst adminUsers = await Users.find({group : group}).all(); // will fetch all users that belong to admin group\n```\n\n### Chaining query\n\n```js\nconst authors \n    = await Author.find\u003cAuthor\u003e({active : true})\n            .sort(\"name\", \"desc\")\n            .limit(4)\n            .skip(2)\n            .all()\n```\n\n### Joining references\n\nFuseDB can automatically join referenced fields by making optimised requests (collecting all ids and making additional queries to the database)\ne.g\n\n```js\nconst books = await Book.find\u003cBook\u003e().with(\"author\", Author).all();\n```\n\n## Saving\n\n```js\nconst author = new Author();\nauthor.name = \"john\"\nawait autor.save() \n```\n\n\n## Removing\n```js\nconst author = await Author.find({name : \"john\"});\nawait author.remove()\n```\n\n## Model event hooks\n\nDefining the following hooks will allow you to intercept model events\n\n```ts\nexport class Foo extends Model\u003cFoo\u003e {\n    @Field()\n    public name: string;\n    // before updating or creating a record\n    async onBeforeSave() {}\n    // after creating or updating a record\n    async onAfterSave() {}\n    // before updating a record\n    async onBeforeUpdate() {}\n    // after creating a record\n    async onBeforeCreate() {}\n}\n```\n\n## Validators\n\nValidators in FuseDb are quite easy to use and implement. The framework offers a few default validators, \nin order to enable them call a function in your entry point (before you start importing your models)\n\n```js\nimport { enableDefaultDecorators } from \"fusedb\"\nenableDefaultDecorators();\n```\n\nNow you can start using them in your models, like that:\n\n```js\nclass FooBarMax extends Model\u003cFooBarMin\u003e {\n    @Field() @Validate({max : 3})\n    public name: string;\n}\n```\n\nDefault validators can assert a custom message\n\n```js\n@Validate({nameOftheValidator : { message :\"Failed\", value : 3}})\n```\n\n### Min Symbols Validator\n\n```js\nclass FooBarMin extends Model\u003cFooBarMin\u003e {\n    @Field() @Validate({min : 3})\n    public name: string;\n}\n```\n\n### Max Symbols Validator\n\n```js\nclass FooBarMax extends Model\u003cFooBarMax\u003e {\n    @Field() @Validate({max : 3})\n    public name: string;\n}\n```\n\n### Email Validator\n\n```js\nclass FooBarEmail extends Model\u003cFooBarEmail\u003e {\n    @Field() @Validate({email : true})\n    public name: string;\n}\n```\n\n### RegExp Validator\n\n```js\nclass FooBarRegExp extends Model\u003cFooBarRegExp\u003e {\n    @Field() @Validate({regExp : /\\d{2}/})\n    public name: string;\n}\n```\n\n### Enum Validator\n\n```js\nconst seasons = {\n    SUMMER: 'summer',\n    WINTER: 'winter',\n    SPRING: 'spring'\n}\n```\n\n```js\nclass FooBarEnum extends Model\u003cFooBarEnum\u003e {\n    @Field() @Validate({enum : seasons})\n    public season: string;\n}\n```\n\n### Function validator\n\n```js\nclass FooBarCustom extends Model\u003cFooBarCustom\u003e {\n    @Field() \n    @Validate({fn : value =\u003e {\n        if( value !== \"foo\") throw new Error(\"Value should be foo only\")\n    }})\n    public name: string;\n}\n```\n\n## Your own validators\n\nDefine a class with `Validator`\n```js\nimport { Validator, FieldValidator } from \"fusedb\";\n\n@Validator()\nexport class OopsValidator implements FieldValidator {\n    validate(field: string, props: any, value: any) {\n        throw \"Somethign wentWrong\"\n    }\n}\n```\n\nA validator with name `oops` has be registered, how you can use it in your models\n\n```js\nclass Hello extends Model\u003cHello\u003e {\n    @Field() @Validate({oops : true})\n    public name: string;\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffuse-box%2Ffusedb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffuse-box%2Ffusedb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffuse-box%2Ffusedb/lists"}