{"_id":"@andersondacampo/volt-core","_rev":"2-54697bb2ba745016b3682a65d3e3c7e9","name":"@andersondacampo/volt-core","dist-tags":{"latest":"0.3.0"},"versions":{"0.3.0":{"name":"@andersondacampo/volt-core","version":"0.3.0","keywords":["typescript","api","framework","http","router","nextjs","express","fastify","type-safe","middleware","server"],"author":{"name":"Anderson da Campo","email":"andeerc@gmail.com"},"license":"MIT","_id":"@andersondacampo/volt-core@0.3.0","maintainers":[{"name":"andersondacampo","email":"andercampo12@gmail.com"}],"homepage":"https://andeerc.github.io/volt-js","bugs":{"url":"https://github.com/andeerc/volt-js/issues"},"dist":{"shasum":"a1a5d5e8a8a4740a65fc80b878fc2f572193f8ef","tarball":"https://registry.npmjs.org/@andersondacampo/volt-core/-/volt-core-0.3.0.tgz","fileCount":40,"integrity":"sha512-i2Q4QUQz5xjduGmdGPdYmfUF+zgLqOq+NkJtsE9aHMIO/itQ8TP5RqsRdyljQelZaTvjXu0hIR4jG4kBDaa4dw==","signatures":[{"sig":"MEUCIA3LagLI17i1yNtwQ2GIInYAuruZYBUlsospbNxhb4mpAiEAsVQxMZo9joNrQEpeSFwgHJv8ieX+LiQp9lMOjNnu970=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":6144811},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./client":{"node":{"types":"./dist/client/index.server.d.ts","import":"./dist/client/index.server.mjs","require":"./dist/client/index.server.js"},"worker":{"types":"./dist/client/index.browser.d.ts","import":"./dist/client/index.browser.mjs","require":"./dist/client/index.browser.js"},"browser":{"types":"./dist/client/index.browser.d.ts","import":"./dist/client/index.browser.mjs","require":"./dist/client/index.browser.js"},"default":{"types":"./dist/client/index.d.ts","import":"./dist/client/index.mjs","require":"./dist/client/index.js"}},"./plugins":{"types":"./dist/plugins/index.d.ts","import":"./dist/plugins/index.mjs","require":"./dist/plugins/index.js"},"./adapters":{"types":"./dist/adapters/index.d.ts","import":"./dist/adapters/index.mjs","require":"./dist/adapters/index.js"}},"gitHead":"1644259c6649446b8ccfb3f8b89759f06d125f46","scripts":{"dev":"tsup --watch","lint":"eslint src --ext .ts,.tsx","test":"vitest run","build":"tsup","clean":"rm -rf dist","lint:fix":"eslint src --ext .ts,.tsx --fix","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"andersondacampo","email":"andercampo12@gmail.com"},"repository":{"url":"git+https://github.com/andeerc/volt-js.git","type":"git"},"_npmVersion":"10.8.2","description":"A modern, type-safe, and flexible HTTP framework for building scalable APIs with TypeScript","directories":{},"_nodeVersion":"20.19.1","dependencies":{"glob":"^11.0.0","rou3":"^0.5.1","chalk":"4.1.2","lodash":"^4.17.21","uncrypto":"^0.1.3","@scalar/core":"^0.3.11"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"zod":"3.25.67","tsup":"^8.3.5","eslint":"^8.57.0","vitest":"^2.1.4","typescript":"^5.6.3","@types/next":"^9.0.0","@types/node":"^22.9.0","@types/react":"^19.0.10","@types/lodash":"^4.17.15","@types/webpack":"^5.28.5","@types/react-dom":"^19.0.4"},"peerDependencies":{"next":">=13.0.0","react":"^19.0.0","ioredis":"","webpack":">=5.0.0","react-dom":"^19.0.0","typescript":">=5.0.0"},"peerDependenciesMeta":{"webpack":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/volt-core_0.3.0_1755745403025_0.9329259838954798","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."}},"time":{"created":"2025-08-21T03:03:22.920Z","modified":"2026-04-01T03:25:33.302Z","0.3.0":"2025-08-21T03:03:23.260Z"},"bugs":{"url":"https://github.com/andeerc/volt-js/issues"},"author":{"name":"Anderson da Campo","email":"andeerc@gmail.com"},"license":"MIT","homepage":"https://andeerc.github.io/volt-js","keywords":["typescript","api","framework","http","router","nextjs","express","fastify","type-safe","middleware","server"],"repository":{"url":"git+https://github.com/andeerc/volt-js.git","type":"git"},"description":"A modern, type-safe, and flexible HTTP framework for building scalable APIs with TypeScript","maintainers":[{"name":"andersondacampo","email":"andercampo12@gmail.com"}],"readme":"# @volt-js/core\r\n\r\n[![NPM Version](https://img.shields.io/npm/v/@volt-js/core.svg)](https://www.npmjs.com/package/@volt-js/core)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n[![Build Status](https://img.shields.io/github/actions/workflow/status/andeerc/volt-js/main.yml?branch=main)](https://github.com/andeerc/volt-js/actions)\r\n\r\nThe core package for the Volt.js framework. It contains the essential building blocks for creating type-safe, modern TypeScript applications.\r\n\r\n## Role in the Ecosystem\r\n\r\nThis package is the heart of the Volt.js framework. It provides all the fundamental tools you need to build a robust and scalable API, including:\r\n\r\n-   **The Volt Builder:** A fluent API for composing your application's features.\r\n-   **Action Factories:** `volt.query()` and `volt.mutation()` to define your API endpoints.\r\n-   **Controller Factory:** `volt.controller()` to group related actions.\r\n-   **Procedure Factory:** `volt.procedure()` for creating reusable, type-safe middleware.\r\n-   **The Router:** `volt.router()` to assemble all your controllers into a single, executable API handler.\r\n-   **Core Interfaces:** All the essential TypeScript types and interfaces that power the framework's end-to-end type safety.\r\n\r\n## Installation\r\n\r\nYou can install the core package using your favorite package manager:\r\n\r\n```bash\r\n# npm\r\nnpm install @volt-js/core\r\n\r\n# yarn\r\nyarn add @volt-js/core\r\n\r\n# pnpm\r\npnpm add @volt-js/core\r\n\r\n# bun\r\nbun add @volt-js/core\r\n```\r\n\r\nWhile `@volt-js/core` has no required production dependencies, you will likely install `zod` for schema validation, as it is tightly integrated with the framework's type system.\r\n\r\n```bash\r\nnpm install zod\r\n```\r\n\r\n## Basic Usage\r\n\r\nHere is a minimal example of how to create a complete Volt.js application using only the `core` package.\r\n\r\n### 1. Define the Context (`src/volt.context.ts`)\r\n\r\nDefine the shape of your application's global context. This is where you'll provide dependencies like a database connection.\r\n\r\n```typescript\r\n// src/volt.context.ts\r\nexport interface AppContext {\r\n  // In a real app, this would be a database client instance.\r\n  db: {\r\n    findUsers: () => Promise<{ id: number; name: string }[]>;\r\n  };\r\n}\r\n```\r\n\r\n### 2. Initialize the Volt Builder (`src/volt.ts`)\r\n\r\nCreate the main `volt` instance, telling it about your `AppContext`.\r\n\r\n```typescript\r\n// src/volt.ts\r\nimport { Volt } from '@volt-js/core';\r\nimport type { AppContext } from './volt.context';\r\n\r\nexport const volt = Volt.context<AppContext>().create();\r\n```\r\n\r\n### 3. Create a Controller (`src/features/user/user.controller.ts`)\r\n\r\nDefine your API endpoints using `volt.controller()` and `volt.query()`.\r\n\r\n```typescript\r\n// src/features/user/user.controller.ts\r\nimport { volt } from '@/volt';\r\n\r\nexport const userController = volt.controller({\r\n  path: '/users',\r\n  actions: {\r\n    list: volt.query({\r\n      path: '/',\r\n      handler: async ({ context, response }) => {\r\n        const users = await context.db.findUsers();\r\n        return response.success({ users });\r\n      },\r\n    }),\r\n  },\r\n});\r\n```\r\n\r\n### 4. Assemble the Router (`src/volt.router.ts`)\r\n\r\nRegister your controller with the main application router.\r\n\r\n```typescript\r\n// src/volt.router.ts\r\nimport { volt } from '@/volt';\r\nimport { userController } from '@/features/user/user.controller';\r\n\r\nexport const AppRouter = volt.router({\r\n  controllers: {\r\n    users: userController,\r\n  },\r\n});\r\n```\r\n\r\n### 5. Create an HTTP Server\r\n\r\nFinally, use the `AppRouter.handler` to serve HTTP requests. The handler is framework-agnostic and works with any server that supports the standard `Request` and `Response` objects.\r\n\r\n```typescript\r\n// src/server.ts\r\nimport { AppRouter } from './volt.router';\r\nimport { createServer } from 'http';\r\n\r\n// A simple example with Node.js http server\r\n// In a real app, you would use a framework adapter (e.g., Next.js, Hono)\r\ncreateServer(async (req, res) => {\r\n  const request = new Request(`http://${req.headers.host}${req.url}`, {\r\n    method: req.method,\r\n    headers: req.headers,\r\n    // body handling would be more complex\r\n  });\r\n\r\n  const response = await AppRouter.handler(request);\r\n\r\n  res.statusCode = response.status;\r\n  for (const [key, value] of response.headers.entries()) {\r\n    res.setHeader(key, value);\r\n  }\r\n  res.end(await response.text());\r\n}).listen(3000, () => {\r\n  console.log('Server running on http://localhost:3000');\r\n});\r\n```\r\n\r\nFor more detailed guides and advanced concepts, please refer to the **[Official Volt.js Wiki](https://voltjs.com/docs)**.\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please see the main [CONTRIBUTING.md](/CONTRIBUTING.md) file for details on how to get started.\r\n\r\n## License\r\n\r\nThis package is licensed under the [MIT License](/LICENSE).\r\n","readmeFilename":"README.md"}