Nest GraphQL Schema Package

GraphQL schema definitions and generated TypeScript types for Tanzania Nest Rental Platform.

Installation

npm install nest-ql-schema

Usage

1. In CDK (AppSync API)

import * as appsync from 'aws-cdk-lib/aws-appsync';
import { schemaPath, SCHEMA_VERSION } from 'nest-ql-schema';

// Create AppSync API with schema
const api = new appsync.GraphqlApi(this, 'NestAPI', {
  name: 'nest-rental-api',
  schema: appsync.SchemaFile.fromAsset(schemaPath),
  authorizationConfig: {
    defaultAuthorization: {
      authorizationType: appsync.AuthorizationType.API_KEY,
    },
    additionalAuthorizationModes: [
      {
        authorizationType: appsync.AuthorizationType.USER_POOL,
        userPoolConfig: { userPool }
      }
    ]
  }
});

console.log(`Schema version: ${SCHEMA_VERSION}`);

2. Type-Safe Resolvers

import type { 
  QueryResolvers, 
  MutationResolvers,
  Property,
  PropertyCard,
  Application
} from 'nest-ql-schema';

// Implement type-safe resolvers
const queryResolvers: QueryResolvers = {
  getProperty: async (_, { propertyId }, context) => {
    const property = await dynamoDB.get({
      TableName: 'Properties',
      Key: { propertyId }
    });
    return property.Item as Property;
  },
  
  getPublicInitialData: async (_, { limit, nextToken }) => {
    const regions = await getRegions();
    const properties = await getRecentProperties(limit, nextToken);
    const featured = await getFeaturedProperties();
    
    return {
      regions,
      recentProperties: properties,
      featuredProperties: featured
    };
  }
};

const mutationResolvers: MutationResolvers = {
  addToFavorites: async (_, { propertyId }, context) => {
    const userId = context.identity.sub;
    await dynamoDB.put({
      TableName: 'UserActivity',
      Item: {
        PK: `USER#${userId}`,
        SK: `FAVORITE#${propertyId}`,
        propertyId,
        favoritedAt: new Date().toISOString()
      }
    });
    return { success: true, message: 'Property added to favorites' };
  }
};

3. Using Types in Lambda Functions

import type { Property, PropertyInput } from 'nest-ql-schema';

export const handler = async (event: any) => {
  const property: Property = {
    propertyId: 'prop-123',
    landlordId: 'user-456',
    title: 'Beautiful Apartment',
    description: '2 bedroom apartment in Ilala',
    // ... fully typed
  };
  
  return property;
};

4. Runtime Schema Validation

import { schema } from 'nest-ql-schema';
import { buildSchema } from 'graphql';

// Use schema string for runtime validation
const executableSchema = buildSchema(schema);

Package Structure

After publishing to npm, the package contains:

nest-ql-schema/
├── dist/
│   ├── src/
│   │   ├── index.js         # Main export
│   │   └── index.d.ts       # TypeScript definitions
│   ├── schemas/
│   │   ├── schema.graphql   # Complete unified schema
│   │   ├── location.graphql # Location hierarchy
│   │   └── application.graphql # Application workflow
│   └── generated/
│       ├── types.ts         # Generated TypeScript types
│       ├── resolvers.ts     # Resolver type definitions
│       └── introspection.json
└── package.json

Exports

// Types
export * from './generated/types';
export type { Resolvers, QueryResolvers, MutationResolvers, SubscriptionResolvers };

// Schema
export const schema: string;           // Schema as string
export const schemaPath: string;        // Path to schema file (for CDK)
export const SCHEMA_VERSION: string;    // Version number

// Introspection
export function getIntrospection(): any;  // Lazy-loaded introspection data

Build & Publish

# Build the package
npm run build

# Publish to npm
npm publish

# Or publish with specific tag
npm publish --tag beta

Development

# Install dependencies
npm install

# Generate types from schema
npm run codegen

# Build
npm run build

# Watch mode
npm run watch

GraphQL Schema Features

Complete API

• 25 Queries (8 public, 17 authenticated)
• 12 Mutations (consolidated for efficiency)
• 4 Subscriptions (real-time updates)

Key Types

• Users: Tenant, Landlord, Admin
• Properties: Property, PropertyCard (lightweight)
• Applications: Application, ApplicationCard
• Locations: Region, District, Ward, Street

Guest Access (No Auth)

• Browse properties
• Filter by location, price, amenities
• View property details
• See landlord contact

Authenticated Features

• Personalized dashboard
• Favorites & recently viewed
• Application management
• Landlord/tenant stats

License

MIT

Author

Nest Platform Team