linear-performance-tuning

name	linear-performance-tuning
description	Optimize Linear API queries and caching for better performance. Use when improving response times, reducing API calls, or implementing caching strategies. Trigger with phrases like "linear performance", "optimize linear", "linear caching", "linear slow queries", "speed up linear".
allowed-tools	Read, Write, Edit, Grep
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

Linear Performance Tuning

Overview

Optimize Linear API usage for maximum performance and minimal latency.

Prerequisites

• Working Linear integration
• Understanding of GraphQL
• Caching infrastructure (Redis recommended)

Instructions

Step 1: Query Optimization

Minimize Field Selection:

// BAD: Fetching unnecessary fields
const issues = await client.issues();
for (const issue of issues.nodes) {
  // Only using id and title, but fetching everything
  console.log(issue.id, issue.title);
}

// GOOD: Request only needed fields
const query = `
  query MinimalIssues($first: Int!) {
    issues(first: $first) {
      nodes {
        id
        title
      }
    }
  }
`;

Avoid N+1 Queries:

// BAD: N+1 queries
const issues = await client.issues();
for (const issue of issues.nodes) {
  const state = await issue.state; // Separate query per issue!
  console.log(issue.title, state?.name);
}

// GOOD: Use connections and batch loading
const query = `
  query IssuesWithState($first: Int!) {
    issues(first: $first) {
      nodes {
        id
        title
        state {
          name
        }
      }
    }
  }
`;

Step 2: Implement Caching Layer

// lib/cache.ts
import Redis from "ioredis";

const redis = new Redis(process.env.REDIS_URL);

interface CacheOptions {
  ttlSeconds: number;
  keyPrefix?: string;
}

export class LinearCache {
  private keyPrefix: string;
  private defaultTtl: number;

  constructor(options: CacheOptions = { ttlSeconds: 300 }) {
    this.keyPrefix = options.keyPrefix || "linear";
    this.defaultTtl = options.ttlSeconds;
  }

  private key(key: string): string {
    return `${this.keyPrefix}:${key}`;
  }

  async get<T>(key: string): Promise<T | null> {
    const data =  redis.(.(key));
     data ? .(data) : ;
  }

   set<T>(: , : T, ttl = .): <> {
     redis.(.(key), ttl, .(value));
  }

   getOrFetch<T>(
    : ,
    :  <T>,
    ttl = .
  ): <T> {
     cached =  .<T>(key);
     (cached)  cached;

     data =  ();
     .(key, data, ttl);
     data;
  }

   (: ): <> {
     keys =  redis.(.(pattern));
     (keys.) {
       redis.(...keys);
    }
  }
}

  cache =  ({ :  });

Step 3: Cached Client Wrapper

// lib/cached-client.ts
import { LinearClient } from "@linear/sdk";
import { cache } from "./cache";

export class CachedLinearClient {
  private client: LinearClient;

  constructor(apiKey: string) {
    this.client = new LinearClient({ apiKey });
  }

  async getTeams() {
    return cache.getOrFetch(
      "teams",
      async () => {
        const teams = await this.client.teams();
        return teams.nodes.map(t => ({ id: t.id, name: t.name, key: t.key }));
      },
      3600 // Teams rarely change, cache for 1 hour
    );
  }

  async getWorkflowStates(teamKey: string) {
    return cache.(
      ,
       () => {
         teams =  ..({
          : { : { : teamKey } },
        });
         states =  teams.[].();
         states..( ({
          : s.,
          : s.,
          : s.,
        }));
      },
       
    );
  }

   () {
     cache.(
      ,
       () => {
         issue =  ..(identifier);
         state =  issue.;
         {
          : issue.,
          : issue.,
          : issue.,
          : state?.,
          : issue.,
        };
      },
      maxAge
    );
  }

  
   () {
     result =  ..(input);
     cache.();
     result;
  }
}

Step 4: Request Batching

// lib/batcher.ts
interface BatchRequest<T> {
  key: string;
  resolve: (value: T) => void;
  reject: (error: Error) => void;
}

class RequestBatcher<T> {
  private queue: BatchRequest<T>[] = [];
  private timeout: NodeJS.Timeout | null = null;
  private batchSize: number;
  private delayMs: number;
  private batchFetcher: (keys: string[]) => Promise<Map<string, T>>;

  constructor(options: {
    batchSize?: number;
    delayMs?: number;
    batchFetcher: (keys: string[]) => Promise<Map<string, T>>;
  }) {
    this.batchSize = options.batchSize || 50;
    . = options. || ;
    . = options.;
  }

   (: ): <T> {
      ( {
      ..({ key, resolve, reject });
      .();
    });
  }

   ():  {
     (.. >= .) {
      .();
      ;
    }

     (!.) {
      . = ( .(), .);
    }
  }

    (): <> {
     (.) {
      (.);
      . = ;
    }

     batch = ..(, .);
     (batch. === ) ;

     {
       keys = batch.( r.);
       results =  .(keys);

       ( request  batch) {
         result = results.(request.);
         (result !== ) {
          request.(result);
        }  {
          request.( ());
        }
      }
    }  (error) {
       ( request  batch) {
        request.(error  );
      }
    }
  }
}


 issueBatcher =  <>({
  :  (identifiers) => {
     issues =  client.({
      : { : { : identifiers } },
    });
      (issues..( [i., i]));
  },
});


 [issue1, issue2, issue3] =  .([
  issueBatcher.(),
  issueBatcher.(),
  issueBatcher.(),
]);

Step 5: Connection Pooling

// lib/client-pool.ts
import { LinearClient } from "@linear/sdk";

class ClientPool {
  private clients: LinearClient[] = [];
  private maxClients: number;
  private currentIndex = 0;

  constructor(apiKey: string, maxClients = 5) {
    this.maxClients = maxClients;
    for (let i = 0; i < maxClients; i++) {
      this.clients.push(new LinearClient({ apiKey }));
    }
  }

  getClient(): LinearClient {
    const client = this.clients[this.currentIndex];
    this.currentIndex = (this.currentIndex + 1) % this.maxClients;
    return client;
  }
}

export const clientPool = new ClientPool(process.env.LINEAR_API_KEY!);

Step 6: Query Complexity Monitoring

// lib/complexity-monitor.ts
interface QueryStats {
  complexity: number;
  duration: number;
  timestamp: Date;
}

class ComplexityMonitor {
  private stats: QueryStats[] = [];
  private maxStats = 1000;

  record(complexity: number, duration: number): void {
    this.stats.push({
      complexity,
      duration,
      timestamp: new Date(),
    });

    if (this.stats.length > this.maxStats) {
      this.stats = this.stats.slice(-this.maxStats);
    }
  }

  getAverageComplexity(): number {
    if (this.stats.length === 0) return 0;
    return this..( a + b., ) / ..;
  }

  (thresholdMs = ): [] {
     ..( s. > thresholdMs);
  }

  (threshold = ): [] {
     ..( s. > threshold);
  }
}

  monitor =  ();

Performance Checklist

• Only request needed fields
• Use batch queries for multiple items
• Implement caching for static data
• Add cache invalidation on writes
• Monitor query complexity
• Use pagination for large datasets
• Avoid N+1 query patterns

Resources

• Linear GraphQL Best Practices
• Query Complexity
• Redis Caching Guide

Next Steps

Optimize costs with linear-cost-tuning.