@ttoss/graphql-api-cli 0.9.1 → 0.9.3

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 additional 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 package.json dependencies (except workspace packages and `graphql`) and appends any specified external dependencies to this list. Workspace dependencies (those with `workspace:` prefix) are automatically excluded from external handling to prevent bundling issues in monorepo environments. The `graphql` dependency is always bundled to avoid dynamic require errors.
+
+## 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
 ```
 
-### `--external`
+### Schema Composer Example
 
-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.
+```typescript
+// src/schemaComposer.ts
+import { schemaComposer } from '@ttoss/graphql-api';
+import './modules/User/composer';
+import './modules/Post/composer';
+
+export { schemaComposer };
+```
+
+### Advanced Configuration
+
+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. Automatically excludes all package.json dependencies as external (except workspace packages and `graphql`), with support for additional external dependencies via the `--external` option. The `graphql` package is always bundled to prevent "Dynamic require of 'graphql' is not supported" errors.
+
+**Workspace Dependencies**: Dependencies with `workspace:` prefix are automatically excluded from external handling to prevent TypeScript import errors in monorepo environments where workspace packages may export `.ts` files directly.
+
+**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.9.0",
+  version: "0.9.2",
   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",
+    "@graphql-codegen/typescript": "^4.1.6",
     commander: "^14.0.0",
-    esbuild: "^0.25.5",
-    graphql: "^16.9.0",
+    esbuild: "^0.25.8",
+    graphql: "^16.11.0",
     npmlog: "^7.0.1"
   },
   peerDependencies: {
@@ -56,29 +56,41 @@ var package_default = {
 
 // src/index.ts
 var logPrefix = "graphql-api";
-var isMonorepo = process.env.TTOSS_MONOREPO === "true";
 var importSchemaComposer = async ({
-  external,
+  external = [],
   schemaComposerPath
 }) => {
   const lastEntryPointName = schemaComposerPath.split("/").pop();
   const filename = lastEntryPointName?.split(".")[0];
   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 => {
-    if (isMonorepo && dependency.startsWith("@ttoss/")) {
-      return false;
+  const getPackageDependencies = packageJsonPath2 => {
+    const packageJson = fs.readFileSync(packageJsonPath2, "utf-8");
+    const parsedPackageJson = JSON.parse(packageJson);
+    const dependencies2 = [];
+    for (const [dependency, version] of Object.entries(parsedPackageJson.dependencies || {})) {
+      if (dependency === "graphql") {
+        continue;
+      }
+      if (version.startsWith("file:")) {
+        continue;
+      }
+      if (version.startsWith("workspace:")) {
+        continue;
+      }
+      dependencies2.push(dependency);
     }
-    if (dependency === "graphql") {
-      return false;
-    }
-    return true;
+    return dependencies2;
+  };
+  const dependencies = getPackageDependencies(packageJsonPath).filter((dep, index, self) => {
+    return self.indexOf(dep) === index;
+  }).sort((a, b) => {
+    return a.localeCompare(b);
   });
   const result = await esbuild.build({
     bundle: true,
     entryPoints: [schemaComposerPath],
-    external: external || dependencies,
+    external: [...external, ...dependencies],
     format: "esm",
     outfile,
     platform: "node",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/graphql-api-cli",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "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",
+    "@graphql-codegen/typescript": "^4.1.6",
     "commander": "^14.0.0",
-    "esbuild": "^0.25.5",
-    "graphql": "^16.9.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.5"
+    "@ttoss/config": "^1.35.6"
   },
   "keywords": [
     "api",