@ttoss/graphql-api-cli 0.9.0 → 0.9.2

package/README.md

@@ -1,10 +1,6 @@
 # @ttoss/graphql-api-cli
 
-This package generates schema and TypeScript types for your GraphQL API.
-
-## ESM Only
-
-This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
+CLI tool that generates GraphQL schemas and TypeScript types from your [`@ttoss/graphql-api`](https://ttoss.dev/docs/modules/packages/graphql-api/) schema composer, enabling seamless integration with Relay and providing type safety for your GraphQL operations.
 
 ## Installation
 
@@ -12,15 +8,23 @@ This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908
 pnpm add -D @ttoss/graphql-api-cli
 ```
 
-## Usage
+## Core Functionality
+
+This CLI is essential for GraphQL development workflows using the ttoss ecosystem, providing automated generation of:
+
+- **GraphQL Schema (SDL)**: Creates `schema/schema.graphql` file required for Relay introspection queries
+- **TypeScript Types**: Generates `schema/types.ts` with strongly-typed interfaces for your GraphQL schema
+- **Development Integration**: Seamlessly integrates with your build pipeline and development workflow
+
+The tool operates by importing your `schemaComposer.ts` file, extracting the schema definition, and generating both the SDL schema file and corresponding TypeScript types using GraphQL Code Generator.
 
-As Relay needs an introspection query to work, this package provides a way to build the GraphQL schema by running `ttoss-graphql-api build-schema`. It build the schema using the `schemaComposer` from `src/schemaComposer.ts` file and save the schema in `schema/schema.graphql` file and TypeScript types in `schema/types.ts` file.
+## Basic Usage
 
 ```bash
 ttoss-graphql-api build-schema
 ```
 
-You can add the `build-schema` script to your `package.json`:
+Add the build script to your `package.json` for easy integration:
 
 ```json
 {
@@ -30,20 +34,98 @@ You can add the `build-schema` script to your `package.json`:
 }
 ```
 
-## Options
+This command:
 
-### `--directory`/`-d`
+1. Reads your `src/schemaComposer.ts` file
+2. Bundles it using esbuild to resolve all dependencies
+3. Extracts the schema definition using the schemaComposer
+4. Generates `schema/schema.graphql` in SDL format
+5. Creates `schema/types.ts` with TypeScript type definitions
 
-If your `schemaComposer` is in a different directory, you can pass the `--directory`/`-d` option to `ttoss-graphql-api build-schema` command:
+## Command Options
+
+### Schema Composer Directory (`-d`, `--directory`)
+
+Specify a custom directory for your `schemaComposer.ts` file:
 
 ```bash
-ttoss-graphql-api build-schema -d tests
+ttoss-graphql-api build-schema -d src/graphql
+ttoss-graphql-api build-schema --directory tests
+```
+
+**Default:** `src`
+
+### External Dependencies (`--external`)
+
+Control which dependencies are marked as external during the bundling process:
+
+```bash
+ttoss-graphql-api build-schema --external graphql-compose,@aws-sdk/client-dynamodb
+```
+
+**Default behavior:** Automatically excludes all dependencies and devDependencies from your `package.json`, except:
+
+- `graphql` package (required for proper schema generation)
+
+## Integration Examples
+
+### Basic Project Structure
+
+```
+my-graphql-api/
+├── schema/                   # Generated files
+│   ├── schema.graphql        # SDL schema
+│   └── types.ts              # TypeScript types
+├── src/
+│   ├── schemaComposer.ts     # Your schema definition
+│   └── modules/              # GraphQL modules
+└── package.json
+```
+
+### Schema Composer Example
+
+```typescript
+// src/schemaComposer.ts
+import { schemaComposer } from '@ttoss/graphql-api';
+import './modules/User/composer';
+import './modules/Post/composer';
+
+export { schemaComposer };
 ```
 
-### `--external`
+### Advanced Configuration
 
-External dependencies to ignore during build. If you don't set this option, the `build-schema` command will use the `dependencies` from your `package.json` file.
+For complex projects requiring specific external handling:
 
 ```bash
-ttoss-graphql-api build-schema --external graphql-compose,graphql
+# Custom directory with specific externals
+ttoss-graphql-api build-schema \
+  --directory src/api \
+  --external graphql-compose,dataloader,aws-sdk
 ```
+
+### CI/CD Integration
+
+```json
+{
+  "scripts": {
+    "build": "pnpm build-schema && pnpm compile",
+    "build-schema": "ttoss-graphql-api build-schema",
+    "dev": "pnpm build-schema && tsx watch server.ts"
+  }
+}
+```
+
+## Technical Details
+
+**ESM Only**: This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) and requires Node.js with ES modules support.
+
+**Bundling Process**: Uses esbuild to bundle your schema composer and its dependencies, ensuring all imports are resolved correctly before schema extraction.
+
+**Type Generation**: Leverages [@graphql-codegen/typescript](https://www.npmjs.com/package/@graphql-codegen/typescript) for precise TypeScript type generation with interface declarations and preserved naming conventions.
+
+## Related Packages
+
+- **[@ttoss/graphql-api](https://ttoss.dev/docs/modules/packages/graphql-api/)**: Core GraphQL API building library
+- **[@ttoss/graphql-api-server](https://ttoss.dev/docs/modules/packages/graphql-api-server/)**: Local development server
+- **[@ttoss/appsync-api](https://ttoss.dev/docs/modules/packages/appsync-api/)**: AWS AppSync integration

package/dist/esm/index.js

@@ -13,7 +13,7 @@ import log from "npmlog";
 // package.json
 var package_default = {
   name: "@ttoss/graphql-api-cli",
-  version: "0.8.7",
+  version: "0.9.1",
   description: "A library for building GraphQL APIs types and schema.",
   license: "MIT",
   author: "ttoss",
@@ -34,10 +34,10 @@ var package_default = {
   sideEffects: false,
   dependencies: {
     "@graphql-codegen/core": "^4.0.2",
-    "@graphql-codegen/typescript": "^4.1.2",
-    commander: "^12.1.0",
-    esbuild: "^0.25.5",
-    graphql: "^16.9.0",
+    "@graphql-codegen/typescript": "^4.1.6",
+    commander: "^14.0.0",
+    esbuild: "^0.25.8",
+    graphql: "^16.11.0",
     npmlog: "^7.0.1"
   },
   peerDependencies: {
@@ -66,7 +66,11 @@ var importSchemaComposer = async ({
   const outfile = path.resolve(process.cwd(), "out", filename + ".js");
   const packageJsonPath = path.resolve(process.cwd(), "package.json");
   const packageJson = await fs.promises.readFile(packageJsonPath, "utf-8");
-  const dependencies = Object.keys(JSON.parse(packageJson).dependencies).filter(dependency => {
+  const parsedPackageJson = JSON.parse(packageJson);
+  const dependencies = Object.keys({
+    ...(parsedPackageJson.dependencies || {}),
+    ...(parsedPackageJson.devDependencies || {})
+  }).filter(dependency => {
     if (isMonorepo && dependency.startsWith("@ttoss/")) {
       return false;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/graphql-api-cli",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "A library for building GraphQL APIs types and schema.",
   "license": "MIT",
   "author": "ttoss",
@@ -22,10 +22,10 @@
   "sideEffects": false,
   "dependencies": {
     "@graphql-codegen/core": "^4.0.2",
-    "@graphql-codegen/typescript": "^4.1.2",
-    "commander": "^12.1.0",
-    "esbuild": "^0.25.5",
-    "graphql": "^16.9.0",
+    "@graphql-codegen/typescript": "^4.1.6",
+    "commander": "^14.0.0",
+    "esbuild": "^0.25.8",
+    "graphql": "^16.11.0",
     "npmlog": "^7.0.1"
   },
   "peerDependencies": {
@@ -33,7 +33,7 @@
   },
   "devDependencies": {
     "tsup": "^8.5.0",
-    "@ttoss/config": "^1.35.4"
+    "@ttoss/config": "^1.35.6"
   },
   "keywords": [
     "api",