{"id":50288708,"url":"https://github.com/codewithveek/harpee","last_synced_at":"2026-05-28T04:04:24.257Z","repository":{"id":42491852,"uuid":"391053967","full_name":"codewithveek/harpee","owner":"codewithveek","description":"Harpee is an object modeling tool for HarperDB, harpee supports both callbacks and promises.","archived":false,"fork":false,"pushed_at":"2023-04-05T10:51:37.000Z","size":1294,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-04T14:37:16.658Z","etag":null,"topics":["database","harperdb","library","modeling","nodejs","nosql","sql"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/codewithveek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-07-30T12:17:39.000Z","updated_at":"2023-04-27T11:09:21.000Z","dependencies_parsed_at":"2025-08-21T19:58:34.124Z","dependency_job_id":"b7fb7820-40db-42db-a820-5d9ec5a819dc","html_url":"https://github.com/codewithveek/harpee","commit_stats":null,"previous_names":["darkcodewrangler/harpee","codewithveek/harpee"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/codewithveek/harpee","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codewithveek%2Fharpee","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codewithveek%2Fharpee/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codewithveek%2Fharpee/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codewithveek%2Fharpee/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codewithveek","download_url":"https://codeload.github.com/codewithveek/harpee/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codewithveek%2Fharpee/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33593424,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["database","harperdb","library","modeling","nodejs","nosql","sql"],"created_at":"2026-05-28T04:04:16.116Z","updated_at":"2026-05-28T04:04:24.232Z","avatar_url":"https://github.com/codewithveek.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e This [documentation](https://harpee-docs-v4.netlify.app) is for v4.x, you can find the documentation for previous versions [here](https://harpee-docs.netlify.app), Before upgrading please read the docs , this version includes breaking changes.\n\n# Introduction.\n\n**Harpee** is a modeling tool for [HarperDB](https://harperdb.io/?utm_source=luckyvictory) which allows you to have a structured data for your tables (collections), it supports both callbacks and promises.\n\n## Installation.\n\nTo use **harpee**, install with\n\n`npm i harpee --save`\n\nor\n\n`yarn add harpee`\n\nrequire it in your application.\n\n```js\n// commonjs\nconst { harpee } = require(\"harpee\");\n\n// as ES6 module\nimport { harpee } from \"harpee\";\n```\n\n## Setup\n\n```js\n// as ES6 module\nimport { harpee,HType } from \"harpee\";\n// create a connection.\n\nharpee.createConnection({host:\n// \"https://localhost:9925\" or https://xxxxxxxx.harperdbcloud.com,\n  user:\"YOUR-DB-USERNAME\",\n  pass:\"YOUR-DB-PASSWORD\",\n  token:xcxxxxxxxxxxx, // your JWT token, you should only use token if no `username` and `password`.\n  })\n\n  // create a Schema.\n  // `name` is optional , if not specified, a default schema with the name `defaultSchema` will be created.\n\n  const usersSchema =  new harpee.Schema({\n  name:\"usersSchema\",\n  fields:{\n    username: HType.string().required(),\n    email: HType.string()\n        .email({ minDomainSegments: 2, tlds: { allow: ['com', 'net'] } }).required() ,\n    phone: HType.number(),\n    verified:HType.bool().default(false)\n  }\n   primaryKey:'user_id' // optional, alias for hash_attribute, default 'id'\n   silent:false // optional, when true turns off error throwing when `Schema.fields` doesn't match `Model.create` values, default is false\n  })\n\n\n// create a model, the model name represents a table.\n\nconst UsersModel = new harpee.Model(\"users\",usersSchema);\n\n// Next, initialize it.\n// Recommended: you should get rid of this method after running your app for the first time.\n\nawait UsersModel.init();\n\n```\n\n## Usage.\n\nNow you can start using the model `UsersModel` to perform several operations.\n\n```js\n// this will insert the following data in `users` table.\nUsersModel.create(\n    {\n        username: \"lucky\",\n        email: \"user@email.com\",\n        phone: 1234567890,\n    },\n    callback\n);\n```\n\n```js\n// this returns every data  from the `users` table.\nUsersModel.find({}, (err, result) =\u003e {\n    if (err) console.log(err);\n    console.log(result.data);\n});\n\n// or\nUsersModel.find([]).then((result) =\u003e console.log(result.data));\n\n// you can specify the columns to be returned.\n\nconst result = await UsersModel.find([\"username\"]);\n//  console.log(result.data)\n\n// you can specify an object with options\nUsersModel.find(\n    {\n        limit: 5,\n        offset: 10,\n        orderby: [\"user_id\"],\n        order: \"desc\",\n        where: 'username=\"lucky\"',\n        getAttributes: [\"username\"],\n    },\n    (err, result) =\u003e {\n        if (err) console.log(err);\n        console.log(result.data);\n    }\n); // this will return only usernames.\n```\n\n```js\n// this will return only data based on the specified `ids`,\nUsersModel.findById(\n    { ids: [1, 2], getAttributes: [\"username\", \"email\"] },\n    (err, result) =\u003e {\n        if (err) console.log(err);\n        console.log(result.data);\n    }\n);\n```\n\n## Docs .\n\n\u003e To better understand how **Harpee** works, you should check out [HarperDB docs](https://harperdb.io/docs/overview/?utm_source=luckyvictory) to learn more about HarperDB.\n\n**Harpee** consist of the following function and classes,\n\n-   **`createConnection`**: _function_\n-   **[Schema](https://harpee-docs-v4.netlify.app/classes/core_harpee_schema.HarpeeSchema.html)**: _class_\n-   **[Model](https://harpee-docs-v4.netlify.app/classes/core_harpee_model.HarpeeModel.html)**: _class_\n-   **[Logger](https://harpee-docs-v4.netlify.app/classes/core_harpee_logger.HarpeeLogger.html)**: _class_\n-   **[Utilities](https://harpee-docs-v4.netlify.app/classes/core_harpee_utilities.HarpeeUtilities.html)**: _class_\n-   **[Sqler](https://harpee-docs-v4.netlify.app/classes/core_sql_handler.SqlHandler.html)**: _class_\n\n## createConnection(config)\n\n`createConnection` function creates a connection with your harperDB instance. it takes in an object with the following props.\n\n-   `host` _Type - String_ : your HarperDB url, _https://localhost:9925_ or *https://xxxxxxxxxx.harperdbcloud.com*.\n-   `username` _Type - String_ : your HarperDB username.\n-   `user` _Type - String_ : same as username.\n-   `password` _Type - String_ : your HarperDB password.\n-   `pass` _Type - String_ : same as password.\n-   `token` _Type - String_ : A generated JWT token, token is _optional_,you should only include it in place of `username` and `password`.\n\n## Schema(options)\n\n`Schema` class creates a schema, it takes in an object with the following props,\n\n-   `name` _Type - String_ : _optional_, if not specified a default schema named **defaultSchema** will be created, but if you want your schema to have a different name, then you should specify this option.\n-   `primaryKey` _Type - String_ _*optional*_: this option allows you to set a _hash_attribute_, if not specified, will default to `id`.\n-   `silent` _Type - boolean_ : _optional_ when true, turns off errors when `Schema.fields` types doesn't match `Model.create()` values, default is `false`.\n-   `fields` _Type - Object_ : this option let's specify table columns and their types ,\n\n\u003e Note: the properties and data-types declared in **fields** must be same with properties and data-types that will be specified at `Model.create(object)` or `Model.createMany(object[])`, otherwise an error will be thrown, you can turn this off by setting `silent` option in `Schema` class to `true` .\n\n```js\nconst ArticleSchema = new harpee.Schema({ name:\"MyArticlesSchema\"},\nfields:{\n  title: HType.string().required(),\n  author: HType.object({name: HType.string()}).required(),\n  body: HType.string().required(),\n  publishDate: HType.date().default(new Date()),\n  status:HType.string().equal('published','draft').default('published'),\n  tags:HType.array()\n})\n```\n\n## Model(modelName,SchemaConfig)\n\nThe Model class takes the following options.\n\n-   `modelName` _Type - String_ : this modelName represents a table that will be created.\n-   `schemaConfig` Type - Schema(Object) : this option takes in an instance of `Schema` .\n-\n\n```js\nconst Articles = new harpee.Model(\"Articles\", ArticleSchema);\n```\n\n### Methods.\n\n**Model** has the following methods. all methods supports both callbacks and promises, the callback function takes two parameters `err` and `result`.\n\n#### create(object,callback)\n\ninserts new data into the table, takes in an object of the data to be inserted.\n\n```js\n// inserts new data into Articles table.\nArticles.create({\n    id: 1,\n    title: \"post 1\",\n    author: { name: \"lucky\" },\n    body: \"lorem ipsum dot set amor\",\n    publishDate: new Date(),\n    tags: [\"first\"],\n});\n```\n\n#### updateNested({id,path,value, returnData? ,getAttributes?:string[]}, callback)\n\nThis methods let's you update values as well nested values, such as objects \u0026 arrays, by simply specifying a path.\n\n```js\n// this will update the author's name, 'lucky' =\u003e 'lucky victory'\nArticles.updateNested(\n    {\n        // the id of the data to be updated\n        id: 1,\n        path: \"author.name\",\n        // the new value\n        value: \"lucky victory\",\n        // returns the updated data\n        returnData: true,\n    },\n    (err, result) =\u003e {\n        console.log(result.data);\n    }\n);\n\n// exampme 2\nArticles.updateNested(\n    {\n        // the id of the data to be updated\n        id: 1,\n        // this will update the tags\n        path: \".tags\",\n        // the new value\n        value: (article) =\u003e {\n            article.tags.push(\"second\");\n            return article.tags;\n        },\n        // returns the updated data\n        returnData: true,\n    },\n    (err, result) =\u003e {\n        console.log(result.data);\n    }\n);\n```\n\n#### find([options],callback)\n\nThe **find** method returns all data from the table. to do this, pass an empty array `[]` or wildcard `[\"*\"]` as the first argument, you can also choose to return specific data,\nfor instance, in order to return only _Article titles_,\n\n```js\n// this will return only Articles titles.\nArticles.find([\"title\"], (err, result) =\u003e {\n    console.log(result.data);\n});\n```\n\nthe **find** method also takes an object with options, useful for advanced filtering.\n\n-   `limit`: _Type - Number_ _optional_:\n    -   `getAttributes`:_Type - Array_ _optional_\n    -   `limit`: **Type - Number** _optional_,\n    -   `offset`: **Type - Number** _optional_,\n    -   `order`: **Type - String** _optional_\n    -   `orderby` : **Type - String[]** _optional_\n    -   `where` : **Type - String** _optional_\n    -   `and` : **Type - String|Number** _optional_\n\nYou can find more methods on the [documentation](https://harpee-docs-v4.netlify.app/classes/core_harpee_model.HarpeeModel.html) page.\n\n### Bugs or Feature Request.\n\nFor bugs or feature request, please create an [issue](https://github.com/lucky-victory/harpee/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodewithveek%2Fharpee","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodewithveek%2Fharpee","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodewithveek%2Fharpee/lists"}