{"id":15020075,"url":"https://github.com/oslabs-beta/transversal","last_synced_at":"2025-10-07T23:16:20.945Z","repository":{"id":40452454,"uuid":"458591265","full_name":"oslabs-beta/transversal","owner":"oslabs-beta","description":"Transversal is an open-source package that aids developers in utilizing GraphQL's dynamic querying language to auto-generate schemas, queries, and mutations on the frontend from the query template initially setup in the backend.","archived":false,"fork":false,"pushed_at":"2022-05-07T16:56:05.000Z","size":443,"stargazers_count":34,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"transversal","last_synced_at":"2025-09-15T12:31:07.092Z","etag":null,"topics":["graphql","redis","websocket"],"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/oslabs-beta.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-02-12T17:26:03.000Z","updated_at":"2022-09-18T02:25:24.000Z","dependencies_parsed_at":"2022-08-09T20:51:24.754Z","dependency_job_id":null,"html_url":"https://github.com/oslabs-beta/transversal","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/oslabs-beta/transversal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oslabs-beta%2Ftransversal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oslabs-beta%2Ftransversal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oslabs-beta%2Ftransversal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oslabs-beta%2Ftransversal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oslabs-beta","download_url":"https://codeload.github.com/oslabs-beta/transversal/tar.gz/refs/heads/transversal","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oslabs-beta%2Ftransversal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278861062,"owners_count":26058637,"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","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"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":["graphql","redis","websocket"],"created_at":"2024-09-24T19:54:33.375Z","updated_at":"2025-10-07T23:16:20.924Z","avatar_url":"https://github.com/oslabs-beta.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **Transversal**\nTransversal is an open-source package that aids developers in utilizing GraphQL's dynamic querying language to auto-generate schemas, queries, and mutations on the frontend from the query template initially setup in the backend. Transversal leverages Redis' in-memory caching mechanism to quickly reference server-side caching.\n\n[![License](https://img.shields.io/badge/license-MIT-orange)]()\n[![Contributions](https://img.shields.io/badge/contributions-welcome-blue)]()\n\n## Table of Contents\n\n- [Description](#description)\n- [Features](#features)\n- [Installation](#installation)\n- [Getting Started](#getting-started)\n- [Further Documentation](#documentation)\n- [Contributions](#contributions)\n- [Developer Team](#developers)\n- [License](#license)\n\n## \u003ca name=\"description\"\u003e\u003c/a\u003e Description\n\nTransversal employs methods for the backend engineer to simply call its library to auto-generate the database schema for use by the front end developer — allowing one half of the usual setup to be abstracted away — and offers a quick Redis caching option if the team so chooses! 🚀\n\n## \u003ca name=\"features\"\u003e\u003c/a\u003e Features\n\n- GraphQL automation stemming from the backend\n- Rapid frontend development\n- Redis caching optional\n- WebSocket for fast frontend notice from the backend\n\n## \u003ca name=\"installation\"\u003e\u003c/a\u003e Installation\n\n\nTo start using this dev tool, developers establish their existing mongoDB URI link and start simply by creating a query template on the backend. Let’s get started! Run ‘npm install transversal’ and ‘npm install transversal-client’ and let’s roll on to the backend!\n```\nnpm install transversal\n\nnpm install transversal-client\n```\n\n\n## \u003ca name=\"getting-started\"\u003e\u003c/a\u003e Getting Started\n\n\n### Back-end\n\n\u003e _Extra Feature — As mentioned above, we’ve put some added tooling into this dev tool to make development faster, and this is a good time to mention the first — WebSocket for immediate up-to-date changes on the frontend if the backend changes._\n\nThis WebSocket option is available by establishing an event listener. While this WebSocket is established any changes to the backend template for auto-generation is immediately updated for our frontend team members. We encourage the use of a WebSocket, as our focus is quick production and iteration, but it’s not required.\n```ts\nconst server = http.createServer(app);\n\nconst json = transversal.jsonStringify(transversal);\n\nconst socket = transversal.instantiateSocket(server, 'http://localhost:8080');\n\nsocket.openConnection(json);\n```\nNow we dive into the real productivity improvement. Simply start by creating a Transversal class (OOP approach) by calling the transversal() method that takes three arguments — the team’s GraphQL schema, Redis Client, and an origin.\n```ts\nconst transversal = new Transversal(schema, redisClient, origin);\n```\nAfter we’ve instantiated the class, we can focus on bringing in our queries and mutations. Let’s get auto-generating and establish GraphQL’s types from the connected database, which we’ll call generateFieldSchema().\n```ts\ntransversal.generateFieldSchema();\n```\nWhen setting up GraphQL queries or mutations, you can use Transversal’s generateQuery() and generateMutation() method. But first, we need to define the arguments for the resolver if any, and the resolver itself. Then we need to pass in the query/mutation name in which we want to register, and the field schema to reference the arguments for the resolver if any, if none then null, and the resolver.\n\n**Queries**\n```ts\nconst userArgs = {  \n    age: { type: GraphQLInt },  \n    height: { type: GraphQLInt },  \n};\n\nconst userResolver = async (parent, args) =\u003e {  \n    const users = await User.find({   \n       age: args.age,   \n       height: args.height   \n    });  \n    return users;  \n};\n\ntransversal.generateQuery(queryName, fieldSchemaName, resolver, args);\n```\n**Mutations**\n```ts\nconst addUserArgs = {  \n    firstName: { type: GraphQLString },  \n    lastName: { type: GraphQLString },  \n    age: { type: GraphQLInt },  \n    height: { type: GraphQLInt },  \n};\n\nconst addUserResolver = async (parent, args) =\u003e {  \n    const users = await User.create({  \n        firstName: args.firstName,  \n        lastName: args.lastName,  \n        age: args.age,  \n        height: args.height,  \n    });  \n    return users;  \n};\n\ntransversal.generateMutation(queryName, fieldSchemaName, resolver, args);\n```\nIt wouldn’t be such a great tool if it didn’t allow for the flexibility that GraphQL sets out to establish in its paradigm. The tool allows you to create your own custom field schema types on the fly by calling generateCustomFieldSchema() method by passing in the custom schema and the schema name you want to register.\n```ts\nconst customSchema = {  \n    firstName: 'String',  \n    lastName: 'String',  \n    age: 'Number',  \n    height: 'Number',  \n    school: {  \n        name: 'String',  \n        year: 'Number',  \n        code: {  \n            code: 'String',  \n        },  \n    },  \n    messages: [{ message: 'String' }],  \n};\n\ntransversal.generateCustomFieldSchema(customSchema, 'customQuery');\n```\n\u003e _Final Feature — For our final integrated feature, caching. Modern applications, especially those with growing number of users and requests, should implement caching to help server data faster. That’s why we’ve decided to create an out-of-the-box Redis caching attachment available on request at your discretion._\n\n[](https://redis.io/)\n\n## Redis\n\nThe open source, in-memory data store used by millions of developers as a database, cache, streaming engine, and… read more redis.io\n\n**Local**\n```ts\nconst redisClient = redis.createClient({  \n    host: '127.0.0.1',  \n    port: \u003cport\u003e  \n});\n```\n**Microservice**\n```ts\nconst redisClient = redis.createClient({  \n    url: process.env.REDIS_URI  \n});\n```\nWhen initially creating the Transversal class, one of the arguments calls for a Redis client URI. If you prefer to use caching with your transversal package, it’s simple to get started. There are two general options, create a local Redis service running side by side with your back-end server (monolithic), or run Redis as a micro service. By flagging this feature on a client-side query, caching will be initiated for that request drastically increasing the latency. See the Redis  [documentation](https://redis.io/docs/), you won’t be disappointed.\n\n# Front-end\n\nNow for the payoff! On the frontend, import the TransversalClient and instantiate it with your preferred endpoint to set up the WebSocket connection.\n```ts\nimport { TransversalClient } from 'transversal-client';\n\nconst transversal = new TransversalClient.default('http://localhost:3000');\n```\nMake a call to getTransversalInstance() method to get the gql object containing all the queries and mutations templates needed to make API calls and store it in state where it can easily be accessed.\n```ts\ntransversal.getTransversalInstance().then((data) =\u003e {  \n    console.log('gql data from server', data.gql);  \n    setGql(data.gql);  \n});\n```\nMaking queries and mutations are done simply by calling transversalQuery() method and passing arguments. You would first need to specify the name of the query or mutation, arguments required (as we saw on the backend previously), specify if you want the call to come from the cache or server, and the last argument can be omitted if you want everything to be returned from the api call. If not, just pass in a custom shape(string) for your data to fill.\n```ts\ntransversal.transversalQuery(  \n    gql.getUsers,  \n    {  \n      age: 10,  \n      height: 10,  \n    },  \n    false  \n);\n```\nAnd that’s it! You’ve streamlined auto-generated schemas for GraphQL.  🚀\n\n## \u003ca name=\"documentation\"\u003e\u003c/a\u003e Further Documentation\n\nhttps://transversal.dev\n\n## \u003ca name=\"contributions\"\u003e\u003c/a\u003e Contributions\n\nConsider contributing, craft it to your needs and let us know your experience. Open issues, reach out to the team, we want to hear from you! Let us know!\n\n\u003ca name=\"developers\"\u003e\u003c/a\u003e \n## Development Team\n\n- [Dan Forrester](https://github.com/daniel-forrester)\n- [Han Kim](https://github.com/han900204)\n- [Norman Liu](https://github.com/normsliu)\n- [Kevin Mun](https://github.com/kmun94)\n\n## \u003ca name=\"license\"\u003e\u003c/a\u003e License\n\nThis product is licensed under the MIT License - see the LICENSE.md file for details.\n\nProduct developed under tech accelerator [OS Labs](https://opensourcelabs.io/). \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foslabs-beta%2Ftransversal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foslabs-beta%2Ftransversal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foslabs-beta%2Ftransversal/lists"}