{"id":21626094,"url":"https://github.com/shtse8/xserver","last_synced_at":"2026-01-07T10:47:17.598Z","repository":{"id":250619375,"uuid":"834965205","full_name":"shtse8/xserver","owner":"shtse8","description":"xserver is a Dart-based web server framework that leverages source generation for automatic handler registration, making it easier to manage and expand your web server's endpoints.","archived":false,"fork":false,"pushed_at":"2024-08-05T20:59:16.000Z","size":97,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-03T21:47:26.399Z","etag":null,"topics":["dart","framework","server"],"latest_commit_sha":null,"homepage":"","language":"Dart","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/shtse8.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2024-07-28T20:58:16.000Z","updated_at":"2024-08-05T20:59:19.000Z","dependencies_parsed_at":"2024-11-25T01:12:47.343Z","dependency_job_id":"dbad8d8c-b3db-4d5b-af20-44895a653b06","html_url":"https://github.com/shtse8/xserver","commit_stats":null,"previous_names":["shtse8/xserver"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shtse8%2Fxserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shtse8%2Fxserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shtse8%2Fxserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shtse8%2Fxserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shtse8","download_url":"https://codeload.github.com/shtse8/xserver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246156025,"owners_count":20732357,"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":["dart","framework","server"],"created_at":"2024-11-25T01:12:10.063Z","updated_at":"2026-01-07T10:47:12.557Z","avatar_url":"https://github.com/shtse8.png","language":"Dart","readme":"# xserver\n\nxserver is a Dart-based web server framework that leverages source generation for automatic handler registration, making it easier to manage and expand your web server's endpoints.\n\n## Features\n\n- **Automatic Handler Registration**: Utilize annotations to auto-register handlers.\n- **Flexible Response Types**: Return various response types including `Future\u003cT\u003e`, `Stream\u003cT\u003e`, and more.\n- **Type-safe Parameter Handling**: Use annotations to handle query parameters, body, headers, and path parameters.\n- **Client Generation**: Automatically generate client code for easy API consumption.\n- **Async Context Management**: Access the current request context asynchronously with `XServer.currentRequest`.\n\n## Getting Started\n\n### Installation\n\nAdd xserver as a dependency in your `pubspec.yaml`:\n\n```yaml\ndependencies:\n  xserver: ^0.2.0\n```\n\nRun `pub get` to install the package.\n\n### Usage\n\n#### Define the Server\n\nCreate a class for your server and annotate it with `@xServer`.\n\n```dart\nimport 'package:xserver/xserver.dart';\n\npart 'app_server.g.dart';\n\n@xServer\nclass AppServer extends _$AppServer {\n}\n```\n\n#### Define Handlers\n\nDefine your handlers within the `AppServer` class. Use annotations to specify the HTTP method and path.\n\n```dart\n@xServer\nclass AppServer extends _$AppServer {\n  @get\n  Future\u003cString\u003e test({\n    @query required String query,\n    @body required Data body,\n    @query required int query2,\n    @header required String header,\n    @header required int header2,\n  }) async {\n    return 'test';\n  }\n\n  @Get('/user/\u003cid\u003e')\n  Future\u003cString\u003e user(@path String id) async {\n    return 'User: $id';\n  }\n\n  @Post('/data')\n  Future\u003cData\u003e data() async {\n    return const Data(\n      query: 'query',\n      body: 'body',\n      query2: 1,\n      header: 'header',\n      header2: 2,\n    );\n  }\n\n  @Get('/stream')\n  Stream\u003cString\u003e stream() async* {\n    for (var i = 0; i \u003c 100; i++) {\n      yield 'stream $i';\n      await Future.delayed(const Duration(seconds: 1));\n    }\n  }\n}\n```\n\n#### Generate Handlers\n\nRun the build command to generate the handler registration code:\n\n```bash\ndart run build_runner build\n```\n\n#### Start the Server\n\nYou can start the server in your main function:\n\n```dart\nimport 'package:xserver/xserver.dart';\n\nvoid main() async {\n  final server = AppServer();\n  await server.start('localhost', 8080);\n  print('Server listening on port 8080');\n}\n```\n\n## Handler Annotations\n\n- `@All(path)`: Handles all HTTP methods\n- `@Get(path)`: Handles GET requests\n- `@Post(path)`: Handles POST requests\n\n## Parameter Annotations\n\n- `@Query([name])`: Extracts query parameters. If name is omitted, uses the parameter name.\n- `@Body()`: Extracts the request body\n- `@Header([name])`: Extracts headers. If name is omitted, uses the parameter name.\n- `@Path([name])`: Extracts path parameters. If name is omitted, uses the parameter name.\n\n## Response Types\n\nHandlers can return various types:\n\n- `Future\u003cT\u003e`: For asynchronous responses\n- `Stream\u003cT\u003e`: For server-sent events or streaming responses\n- `T`: For synchronous responses (will be automatically wrapped in a Future)\n\nWhere `T` can be:\n\n- `String`: For text responses\n- `Map\u003cString, dynamic\u003e`: For JSON responses\n- Custom classes with `toJson()` method: Will be serialized to JSON\n\n## Client Generation\n\nThe generator also creates a client class that can be used to make requests to your server:\n\n```dart\nfinal client = AppServerClient('http://localhost:8080');\nfinal result = await client.test(\n  query: 'example',\n  body: Data(...),\n  query2: 42,\n  header: 'some-header',\n  header2: 123\n);\nprint(result);\n```\n\nThis client handles serialization and deserialization of requests and responses, making it easy to interact with your server from other parts of your application.\n\n## Async Context Management\n\nxserver uses zoned contexts to manage asynchronous requests. You can access the current request at any time without passing it explicitly:\n\n```dart\nimport 'package:xserver/xserver.dart';\n\n@Get('/example')\nFuture\u003cString\u003e exampleHandler() async {\n  final currentRequest = XServer.currentRequest;\n  // Use the currentRequest as needed\n  return 'Handled asynchronously!';\n}\n```\n\n## Documentation\n\nDetailed documentation and examples can be found in the documentation directory.\n\n## Contributing\n\nContributions are welcome! Please read our contributing guide to get started.\n\n## License\n\nThis project is licensed under the MIT License. See the LICENSE file for details.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshtse8%2Fxserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshtse8%2Fxserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshtse8%2Fxserver/lists"}