DEV Community: Georgi Parlakov

How to Run Apollo GraphQL in a QWIK Endpoint

Georgi Parlakov — Sun, 09 Jul 2023 12:28:21 +0000

Short version

code Github

Long version

Highlights:

starting with settin up QWIK and Apollo server
we'll add a couple of routes
- one to expose the graphql as an endpoint
- one to consume it
in the endpoint we'll use code inspired by the expressMiddlware for Apollo server 4 and update it so it works with the QWIK RequestHandler interface
on the consuming side
- fetch will need a slighly different URL when working on the server (SSR) vs the client so we'll use the onRequest and routeLoader to provide the URL from QWIK down to the gqlCall function

0. Setting up QWIK

start by setting up QWIK
npm create qwik@latest
- we used the empty app template
branch in GitHub

1. Set up routes

one route for the graphql endpoint
- so create a file
one for a page that will consume that GQL
branch in GitHub

2. Setting up Apollo

Apollo getting started docs
npm install @apollo/server graphql
Typescript and node types already installed and tsconfig configured by qwik so we can skip that
create the ./graphql/index.ts file
start with the schema

    import { ApolloServer } from '@apollo/server';
    import { startStandaloneServer } from '@apollo/server/standalone';

    // A schema is a collection of type definitions (hence "typeDefs")
    // that together define the "shape" of queries that are executed against
    // your data.
    const typeDefs = `#graphql
    # Comments in GraphQL strings (such as this one) start with the hash (#) symbol.

    # This "Book" type defines the queryable fields for every book in our data source.
    type Book {
        title: String
        author: String
    }

    # The "Query" type is special: it lists all of the available queries that
    # clients can execute, along with the return type for each. In this
    # case, the "books" query returns an array of zero or more Books (defined above).
    type Query {
        books: [Book]
    }
    `;

add a resolver and the server

  import { ApolloServer } from '@apollo/server';

  // A schema is a collection of type definitions (hence "typeDefs")
  // that together define the "shape" of queries that are executed against
  // your data.
  const typeDefs = `#graphql
    # Comments in GraphQL strings (such as this one) start with the hash (#) symbol.

    # This "Book" type defines the queryable fields for every book in our data source.
    type Book {
      title: String
      author: String
    }

    # The "Query" type is special: it lists all of the available queries that
    # clients can execute, along with the return type for each. In this
    # case, the "books" query returns an array of zero or more Books (defined above).
    type Query {
      books: [Book]
    }
  `;


  const books = [
      {
        title: 'The Awakening',
        author: 'Kate Chopin',
      },
      {
        title: 'City of Glass',
        author: 'Paul Auster',
      },
    ];


  // Resolvers define how to fetch the types defined in your schema.
  // This resolver retrieves books from the "books" array above.
  const resolvers = {
      Query: {
          books: () => books,
      },
  };

  // The ApolloServer constructor requires two parameters: your schema
  // definition and your set of resolvers.
  const server = new ApolloServer({
      typeDefs,
      resolvers,
  });

  export const serverStarted = server.start();

on the last line we export the serverStarted which we'll use in the next step to expose the GraphQL API and UI
branch in GitHub

3. Starting the server in an endpoint

we have the endpoint in the src/routes/graphql/index.ts file
the following is inspired and using the code from expressMiddleware @apollo/server/src/express4/index.ts

  import { ContextFunction, BaseContext, HeaderMap, HTTPGraphQLRequest } from '@apollo/server';
  import { RequestHandler } from '@builder.io/qwik-city';
  import { serverStarted, server } from '~/graphql';

  export const onRequest: RequestHandler = async ({
    parseBody,
    method,
    next,
    send,
    request,
    query,
    getWritableStream,
  }) => {
    await serverStarted;

    // from expressMiddleware node_modules/@apollo/server/src/express4/index.ts
    server.assertStarted('QWIK Endpoint');

    // This `any` is safe because the overload above shows that context can
    // only be left out if you're using BaseContext as your context, and {} is a
    // valid BaseContext.
    const defaultContext: ContextFunction<[{}], BaseContext> = async () => ({});

    return parseBody().then((body) => {
      const headers = new HeaderMap(request.headers);

      const httpGraphQLRequest: HTTPGraphQLRequest = {
        method: method.toUpperCase(),
        headers,
        search: query.toString() ?? '',
        body: body ?? {},
      };

      return server
        .executeHTTPGraphQLRequest({
          httpGraphQLRequest,
          context: () => defaultContext({}),
        })
        .then(async (httpGraphQLResponse) => {
          if (httpGraphQLResponse.body.kind === 'complete') {
            const response = new Response(httpGraphQLResponse.body.string, {
              status: 200,
              headers: [...httpGraphQLResponse.headers.entries()],
            });

            send(response);
            return;
          }

          const writableStream = getWritableStream();
          const writer = writableStream.getWriter();
          const encoder = new TextEncoder();

          for await (const chunk of httpGraphQLResponse.body.asyncIterator) {
            writer.write(encoder.encode(chunk));
          }
          writer.close();
        })
        .catch((e) => {
          console.error(e);
          next();
        });
    });
  };

this basically let's the Apollo server have the body and headers
and then relays the response back to the client
- in one go - if the kind === complete
- otherwise - in a stream
branch in GitHub

4. Consume from a page

in the src/routes/page/index.tsx we have the placeholder of a page
in the src/routes/page/gql-call.ts let's create a function to make a gql call

    export function gqlCall<T>(
      url: string,
      body: string,
      controller?: AbortController
    ): Promise<{ data?: T; errors?: unknown[] }> {
      return fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Accept: 'application/json',
        },
        body: JSON.stringify({ query: body }),
        signal: controller?.signal,
      })
        .then((r) => {
          if (r.status === 200) {
            const value = r.json();
            return value;
          }

          return r.body
            ?.getReader()
            .read()
            .then((v) => {
              throw new Error(`An error occurred: , /n ${r.statusText} /n${String.fromCodePoint(...(v.value ?? []))}`);
            });
        })
        .catch((e) => console.error(e));
    }

it adds the necessary minimum headers, reads the body, and has a minimal error handling

now we can make a call in the page's component using the Qwik Resource primitive/component

import { Resource, component$, useResource$, useSignal, useTask$ } from '@builder.io/qwik';
import { gqlCall } from './gql-call';

const titlesQuery = `#gql
query BookTitlesQuery {
    books {
        title
    }
}
`

export default component$(() => {

    const reload = useSignal(0)
    const res = useResource$(({track}) => {
        track(reload)
        return gqlCall<{ books: { title: string }[] }>(JSON.stringify({ query: titlesQuery }));
    })

    return (
        <>
            <button onClick$={() => reload.value +=1}>:reload:</button>
            <Resource
                value={res}
                onResolved={({ data }) => data != null && Array.isArray(data?.books)
                    ? <>{data.books.map(b => <div> {b.title}</div>)}</>
                    : <div>{JSON.stringify(data)}</div>
                }
            />
        </>
    );
});

branch in GitHub

5. Import the GraphQL schema

In a Real-world® scenario we would probably read that off of an environment variable:

const typeDefsFile = process.env.GRAPHQL_SCHEMA

To consume the GraphQL schema from a file we need a couple of changes:

starting with the external file src/graphql/schema.graphql
- for this demo we'll just copy over the book schema from index.ts
then in our src/graphql/index.ts we can

...
import typeDefs from './schema.graphql?raw';
....

so at runtime typeDefs will hold the raw contents of the schema.graphql file allowing for the Apollo server to be built
branch in GitHub

Summary

Thus we have a single process that runs both the QWIK ssr and client code as well as the GraphQL server. We can use the endpoint /graphql by the app or externally.

Cheers.

🧞‍🙏 Thanks for reading!

Give some 💖 or 🦄 if you liked this post.
These help other people find this post and encourage me to write more. Thanks!

Check out my projects:

SCuri — Unit test boilerplate automation (with Enterprise support option too)
ngx-forms-typed — Angular form, only strong typed!
ngx-show-form-control — Visualize/Edit any FormControl/Group

await for Observables

Georgi Parlakov — Fri, 03 Jun 2022 04:23:01 +0000

Subscribe for me, please!

Continue reading on Medium »

How does RxJs retry Work?

Georgi Parlakov — Mon, 26 Apr 2021 18:38:58 +0000

Turns out, retry operator, like many others subscribes to the observable that it is applied on. What's different is that retry works on the error case. On the error case it re-subscribes to the source observable as many times as attempts it was given.

So retry(2) will listen for error and retry once, then listen for another error and retry a second time and then on the third error it will give up and let the error bubble up to your error handler.

For more details, code, and step by step head over https://www.educative.io/edpresso/what-is-the-rxjs-retry-operator-and-how-does-it-work

Yes — The Angular CLI is Creating Unit Tests Wrong

Georgi Parlakov — Sat, 03 Oct 2020 15:13:11 +0000

Photo by Neven Krcmarek on Unsplash

I strongly agree with The Angular CLI is creating your unit tests wrong article!

In fact, I’ve got both an alternative approach and a tool to automate a lot of the boilerplate :

the tool is SCuri — https://www.npmjs.com/package/scuri
approach described in Opinionated approach to Angular testing
my favourite — TestBed considered harmful

The Page Pattern

Georgi Parlakov — Tue, 01 Sep 2020 15:11:44 +0000

Photo by Simon Rae on Unsplash

Separating the business logic problem in Angular.

This article aims to give you a tool to help keep those business and UI concerns separate. It’s the result of a year’s worth of experimentation in a couple of teams I worked with. It might seem unnatural and complex at first, but then again everything new is like that right?

Optimize for the case that the software we write will change and evolve!

There are 2 problems:

We want to separate 💸business logic from user✨interface logic! But that requires a lot of thought effort, which leads to the second problem.
People just want to deliver their feature/fix their bug and go home! And not be constantly worrying: “Where do I put this logic?”

Why are these a problem?

1. Why does business logic need to be separate from user interface logic?

Let’s start with what each is. Think of a select list or a dropdown or a select combo box

we’d like to keep all instances of this look and feel the same (UI)
every instance will show different stuff (business)

In such fairly low-level concepts, it’s trivial to see how business and UI logic need to be separate. Every list will contain different entities people, addresses, orders, etc., but we’d like all of the app’s dropdown-s to look and feel the same for the user’s sake.

We slip into mixing our 💸business and ✨ UI logic when we get to more complex scenarios and get all kinds of pressure! Take your pick: I want to finish faster! I want to make it clever and future proof and reusable as f..k! My boss wants me to finish this by tonight! We promised we would deliver this sprint!

All this is true and real. What is also true and real is your future self having to maintain the code you write today. Help it and separate your business logic from the UI.

Because business requirements evolve — add new payment method — 💸 business concern!
Because users say — hey this wizard/form/whatever looks cool and feels natural and makes my life easy, make the other page look the same — ✨ UI concern!
Because users say — refresh the data on this grid after adding a row — 💸 business concern!

Any of those listed above requirements become really hard or near impossible if we have all our logic in the UI component. Then look and behavior become inseparable. And such requirements are the bread and butter of what we do — evolving software to meet the user’s needs! Ideally, we would have a perfect understanding of what the users need, how to present it and when to update it! We do not! That’s why any living software has issues, bugs, enhancements.

So, let’s optimize for the case that our software will change and evolve!

2. We don’t want to think!

We, the people, need a clear set of rules as to what/how/where/when!

But G, you might say, wait a minute! I’m a smart developer, I don’t need rules! I create the rules in code!

I know, how you feel, I’ve felt the same way. The rules thing can come across insulting. Bear with me, I’ll explain.

It turns out that our brain wants to spend as little energy as possible. It’s a survival and evolutionary thing. The brain does not want to think about the same things every time and looks for the repeatable pattern to memorize and offload to the second system which automates the boring tasks. Think of tying your shoelaces, buttoning a button, washing the dishes, writing code(?!). You don’t want to constantly be thinking about these things — you’ve got more important things to worry about! Where do I go on vacation? Do I need a new car, and can I afford it? The big rocks!

OK, enough about that! Let’s say for the sake of argument that you agree with me that people need a clear set of rules to make their life bearable. Se here’s my list:

Know your 💸business logic from your ✨UI logic!
Keep ’em separated!

Simple! Right?

But, G, how exactly do I do that?!

One set of rules that can give you that is the Redux pattern — NgRx, MobX, etc. Its trade-off is the complex but flexible one.

Or you can implement the Page pattern.

Introducing the Page pattern

A “Page” is what the user interacts with, in one scrollable screen.

It’s not necessarily one component, though one component will often need to be the container of this “Page”! It’s not one route, it can be many, though the container component would probably have one route taking users to it.

The “Page” is the business entity:

the user profile page
the reservation page
the cat owner’s page
the billing page
the landing page

The “Page” (1) owns the data (💸 business concern!) and it (2) requires the user input and the data render to be done on the ✨UI level:

The “Page” expects to get notified about user’s input and intent: onChangePassword onChangePasswordCancel, onChangePasswordConfirm. Also "Page" wants to know when user enters and leaves its domain: onPageEnter and onPageLeave.

The “Page” owns multi-step, 💸 business logic (BL), processes, like the delete user account with a confirmation dialog step:

How do you know what to put in it? Can the user see or click on it? Then its a ✨ UI concern — put it in the Component!

Anything else goes in the 💸 Page!

That’s a bit extreme, I know. The idea is for its implementation by us, the people, to be simple, to make the decision as to what to put where a no-brainer! Thus we take care of both the 1. Know your 💸BL and your ✨ UI! 2. Keep ’em separated!

For example, let’s say that we have a grid of bills:

the bills are displayed on a grid with columns: status(paid/due), name (electricity home, water home, water at mum’s), due date, provider
the bill can be drilled into for details
the bill can be selected
multiple bills can be selected
bill can be paid
bill can be hidden (some bills you don’t want to see — take care of by someone else)

The UI would be the Grid, the checkboxes on the rows representing the selection, the buttons Pay and Hide. Let’s create a component for that:

Why don’t I just put everything in the component and be done with it? This all looks too complex, too much repetition, too much! What did we gain by separating all this?

Software lives, breathes, and changes. That’s just a fact of life. Especially while developing it, but even when in maintenance mode — no new features, just bug fixes. So, let’s imagine what happens next:

Change request — Add payment method!

That would make the BillPaymentPage present a new step with a list of payment methods before showing the confirmation dialog. No need to change the UI around that. And we have the "multi-payment-method" logic all in our page where we can extract it away in case we'd like to use it in another "Page".

Change request — Use the same confirmation dialog on the logout button!

Our confirmation dialog knows only what it needs and can be easily placed in as many places as needed! No bills-payment-page-specific logic in it!

Bug — After hide the data does not refresh.

It only affects business logic so we can write a unit test, and then fix the bug, making sure we see no more of that!

How about Angular Services?

That’s a good question — why not use what the framework has provided? We can. Go right ahead. It can be used just as easy as the “Page” would. It is standard and well-known, which is a good thing for the people using it! It has a few downsides too. Very often these services start as entity specific request proxies (UserService, BillsService) and then become page-specific. What I mean is a situation similar to:

I have a change request for the BillsPaymentPage
I see the BillsService does the Http Requesting of the Bill entity
I’ll just put my implementation in the BillsService
Soon the BillsService becomes the BillsPaymentPageService, but the name remains the same
repeat from the top for another developer for a different page
now the BillsService is one giant ball of mud and no one can figure it out, let alone try to refactor or reuse any of its logic

And then the Page:

it has a name that explains what it is responsible for
it can own the data — cache it or not and it can reliably do so because it is the single source of truth
no one will mistake the BillsOverviewPage responsibility with the BillsPaymentPage

Angular TestBed considered harmful!

Georgi Parlakov — Tue, 19 May 2020 03:31:28 +0000

Why I don’t use Angular TestBed and perhaps you shouldn’t either

Continue reading on Medium »

How to read Azure Dev Ops logs from Node.js using REST API

Georgi Parlakov — Wed, 22 Apr 2020 14:17:52 +0000

Step by step guide

Getting some logs can't be that hard, can it? I can surely do that in a few lines of code!

Well, that's what I though... initially. It turns out it's more than just calling a GET endpoint.

Some of it is that the response from the logs endpoint is actually a zip file. And inside that there are multiple file entries - one for each pipeline task. Plus there's the authorization part. So...

This article will take you step by step from a blank file to having the logs from your Azure Dev Ops Release pipeline. As you may know they are available online, but to get to them there are a couple of steps/clicks one must go through. You may want to get the logs and process them programmatically. For example I had to check if a particular string is part of the Release pipeline logs.

Prerequisites:

node js - install Windows/MacOS or Linux
Azure Dev Ops account - sign up here (don't worry it's free)

What we'll do

Start with a blank node.js project and include dependencies - axios and yauzl.
Get a personal access token(PAT) from Azure Dev Ops and store it in an environment variable. Use that for authorization.
Get the zipped logs via the Azure Dev Ops REST API.
Unzip in memory and read the text contents.
We'll read logs out of a Release Pipeline run, but at the end there is a section on how to convert the script and read a Build Pipeline script.

If you only want the finished script here's the gist for reading logs from a Release Pipeline and Build Pipeline. I've left reminders // TODO Replace with your own for the variables.

My setup

I'll be using ts-node because I prefer typescript safety and don't want to have to deal with the transpilation step. So instead of node index.js I'll do ts-node index.ts. The script should work as plain js, after the types are removed if you so prefer.

My shell is bash running inside Windows Subsystem for Linux (WSL).

1. Start

In a folder azdo-logs initialize a node package:

mkdir azdo-logs
cd azdo-logs
npm init -y

Expect to see an output similar to:

Create index.ts file and include these lines:

/// <reference types="node" />

const accessToken = process.env.AZURE_ACCESS_TOKEN;

if (accessToken == null || accessToken === '') {
  throw new Error('Please provide an access token');
} else {
  console.log('token is present!');
}

We'd like to be sure the token is there, safely hidden in your private environment variable and NOT checked in with the code!

The reference on top gives us access to the nodejs types. You might need to install them as a dev dependency:

npm i @types/node -D

2. Add dependencies

Globally install ts-node and typescript to execute our script.

npm i -g ts-node typescript

Install axios and yauzl in our package. The flag -s will save them to our package.json. And @types/yauzl will give us typing, adding it to devDependencies with the -D flag

npm i axios yauzl -s
npm i @types/yauzl -D

This is how package.json looks like now:

{
  "name": "azdo-logs",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "axios": "^0.19.2",
    "yauzl": "^2.10.0"
  },
  "devDependencies": {
    "@types/yauzl": "^2.9.1"
  }
}

3. Get Azure Dev Ops token

It can be acquired via the profile menu

open personal access tokens page
create a new access token with Release Read permission
store it because you will not be able to see it anymore(you'll be able to recreate it if you lose it)

Finally place that in an environment variable on you local machine or in safe storage (e.g. secret environment variable)

export AZURE_ACCESS_TOKEN = "token-placeholder-not-actual-thing"; # replace token-placeholder-not-actual-thing with your token

or Windows command line

set AZURE_ACCESS_TOKEN="token-placeholder-not-actual-thing";

I've added this line to my .bashrc file so the PAT is available on bash start and I don't have to remember to export it every time I start a terminal.

On Windows you can add it to your Environment Variables. Keep in mind you'll need to restart your session (logout/login) for the env variables to take effect.

Now run ts-node index.ts and you should see

For more details on how to get personal access token see this link.

Ok - we now have the token and dependencies!

4. Get the Azure Dev Ops Organization and Project

To get the logs, we'll need the organization and project names as well as the release id we'd like to read the logs of. The latter would increment for each subsequent run - release 1, 2, 3 so we'd need to provide it per call. For this example, I'll target the release pipeline for a package I maintain.

The project name and organization we can get from the Azure Dev Ops UI:

In my case, it's organization 'gparlakov' and project 'Scuri'. Add those lines in index.ts and replace with your org and project names:

const project = 'Scuri';
const organization = 'gparlakov';

5. Authenticate

To get authorization for the API endpoint using a personal access token (PAT) we need to send a header with the token encoded in base64 format adhering to a specific contract. Add the following at the and of index.ts:

const headers = {
  Authorization: `Basic ${Buffer.from(`PAT:${this.token}`).toString('base64')}`,
  'X-TFS-FedAuthRedirect': 'Suppress', // we can't handle auth redirect so - suppress
};

export const axiosInstance = axios.create({
  baseURL: `https://vsrm.dev.azure.com/${organization}/${project}/_apis/`,
  headers: headers,
});

We need to import the axios module, at the top of index.ts

import axios from 'axios';

6. Get the logs for your release

For this example, I'll use an actual release with the id of 58 (replace with your own). Appending to index.ts:

const releaseId = 58;
axiosInstance
  .get(`release/releases/${releaseId}/logs`, {
    responseType: 'stream',
  })
  .then((logs) => {
    if (logs.status != 200) {
      throw new Error('logs missing');
    }
    console.log('Received bytes:', logs.data.read().length);
  });

Running ts-node index.ts should yield something similar to:

That proves we are authorized to use this REST API endpoint!

7. Unzip the logs

Delete or comment out the console.log line - we'll not need it for now and change the axiosInstance call so it looks like this:

axiosInstance
  .get(`release/releases/${releaseId}/logs`, {
    responseType: 'stream',
  })
  .then((logs) => {
    if (logs.status != 200) {
      throw new Error('logs missing');
    }
    return readLogs(logs.data);
  })
  .then(({ logs }) => {
    console.log(logs);
  });

and finally the readLogs function:

function readLogs
  zipBuffer: NodeJS.ReadableStream
): Promise<{ logs: string; skippedFor: Error[] }> {
  // we'll reject the promise when we can't read anything from the zip
  // and resolve it when we could read (some) plus add the errors for the skipped parts
  // in the end we'd like to say - yes the logs contain the Proof OR no the logs do not contain the proof but there were skipped parts
  return new Promise((res, rej) => {
    const es: Error[] = [];
    const zipChunks: any[] = [];

    zipBuffer.on('data', (d) => zipChunks.push(d));
    zipBuffer.on('end', () => {
      yauzl.fromBuffer(Buffer.concat(zipChunks), { lazyEntries: true }, function (err, zipfile) {
        // can not even open the archive just reject the promise
        if (err) {
          rej(err);
        }
        if (zipfile != null) {
          const chunks: any[] = [];

          zipfile.on('entry', function (entry) {
            if (/\/$/.test(entry.fileName)) {
              // Directory file names end with '/'.
              // Note that entries for directories themselves are optional.
              // An entry's fileName implicitly requires its parent directories to exist.
              zipfile.readEntry();
            } else {
              // file entry
              zipfile.openReadStream(entry, function (err, readStream) {
                if (err) {
                  es.push(err);
                  // skip this one - could not read it from zip
                  zipfile.readEntry();
                }
                if (readStream == null) {
                  // just skip - could not get a read stream from it
                  es.push(
                    new Error(
                      'Could not create a readable stream for the log ' + (entry || {}).fileName ||
                        '<missing file name>'
                    )
                  );
                  zipfile.readEntry();
                } else {
                  readStream.on('data', (c) => chunks.push(c));
                  readStream.on('error', (e) => {
                    es.push(e);
                    // skip this one - could not read it from zip
                    zipfile.readEntry();
                  });
                  readStream.on('end', function () {
                    zipfile.readEntry();
                  });
                }
              });
            }
          });

          zipfile.once('end', function () {
            zipfile.close();
            res({ logs: Buffer.concat(chunks).toString('utf8'), skippedFor: es });
          });

          zipfile.readEntry();
        } else {
          // can't read the archive - reject the promise
          rej(new Error('Could not read the zipfile contents'));
        }
      });
    });
  });
}

There seems to be a lot going on here. It boils down to working with 3 streams.

First, we read the zipFile push into the zipChunks and concat those into a Buffer.
Then, use that Buffer in the yauzl.fromBuffer() call which returns an object that has a readEntry() method. I think of it as a next, because it reads the next entry in the archive.
We get a readStream for each zip file entry. That is a ReadableStream that we push into the chunks.
Finally, we concat all files' chunks into a buffer and read a string out of it:

  Buffer.concat(chunks).toString('utf8');

Done!

We now have a string variable containing all our logs!

Here's a gist of the final index.ts. I've left reminders // TODO Replace with your own for the variables.

Reading a build pipeline logs

To read the logs from a build pipeline, we would need to

Add the "Build: Read" permission to our token or issue a new one with that permission:
Change a bit (just remove one piece) the auth logic:

   const headers = {
     Authorization: `Basic ${Buffer.from(`:${this.token}`).toString('base64')}`,
     'X-TFS-FedAuthRedirect': 'Suppress', // we can't handle auth redirect so - suppress
   };

Change the base URL:

   export const axiosInstance = axios.create({
     baseURL: `https://dev.azure.com/${organization}/${project}/_apis/`,
     headers: headers,
   });

Change the endpoint address and provide a build number (in my case I'll use this build)

   const buildId = 200;
   axiosInstance.get(`build/builds/${buildId}/logs`, {
     responseType: 'stream',
     headers: {
       accept: 'application/zip',
     },
   });

Here's the final script.

Memory consumption note

This whole approach keeps a few buffers in memory, basically copying the zip file a few times* in memory. Considering that we are reading pipeline logs, this should not be a problem. I expect they won't be too large. If that's a problem for you, store the archive locally (though that may be a security consern as Samuel Attard @marshallofsound pointed out) and then use the other method of yauzl

logs.data.pipe(fs.createWriteStream('my-temp-zip-file.zip'))

yauzl.open('my-temp-zip-file.zip', { lazyEntries: true }, function(err, zipfile) {
    //... same code from here on down

*the response stream, the chunks, the buffer, the zip content chunks, their buffer and finally the string - for a 50k log we end up using 250k RAM.

Resources

Restful API docs - really helpful
nodejs client for the API (but its around 116k minified+GZipped! according to bundlephobia ~830k worth of script for your runtime to parse - for each request)
Docs for axios
Docs for yauzl

5+ tips for Angular Library authors

Georgi Parlakov — Sun, 05 Apr 2020 14:06:53 +0000

Here’s what works. I found that out the hard way.

These tips are the result of me publishing a few Angular libraries and making some silly mistakes. Hope you find some of them useful:

Use the CLI and library schematic (ng g library) to scaffold your library. It does a lot of work you’ll otherwise need to do manually: Updates angular.json and adds an ng-package.json config file which allows package config. Ng packager emits a standard Angular library with a public-api.ts which is what is expected by the ng compiler.

A library has it’s own package.json (and readme.md, tsconfig.lib.json, etc.). That makes sense since you'd like to publish the library and the app separately and independently from one another. So you’ll need to update them and not the main app ones (like I did :). If we take the useful-lib example from the previous tip:

Add the repository to lib’s package.json "repository":"github.com/author/repo". Users would want to visit your open source repo too for issues, code, etc. And allows NPM to get images and other assets from it. That is if your readme.md file references an image from /assets/my-lib.png npm will figure out that it’s actually https://raw.githubusercousntent.com/author/my-lib/HEAD?assets/my-lib.png. For real-world example see the first image in my package and it’s raw readme for example.
Use tags! Example: npm publish dist\my-package --tag alpha. Anything not tagged is considered latest and will be installed for users doing npm install. Meaning that your package version 1.0.0-alpha.0 published without tags (hence tagged latest) will end up in the users’ node_modules. Then you’ll start getting issues as for production-ready version. Here’s a snapshot of a package I maintain:

Document it and make it pretty — add pics , quick start, examples, and all the things users need to get started using a project. As the author, it’s easy to forget about those things because you know your work in and out. Users don’t so try and make them feel at home by giving them a guide. Think of what you’ll need or better yet — have someone try and use your library and give you feedback. Here’s a pretty, if somewhat contrived example of readme:

Thanks, https://unsplash.com/@hansonluu for the pretty pic

Don’t publish manually — have an automated process that does it for you. When fixing a bug or adding a feature you focus on development. The packaging and pushing to NPM (or any other package registry) is not interesting so it’s easy to mess it up or even completely forget about it. I know I have. An example from my AzDO pipeline:

Read the angular docs about libraries: Angular.io

Thanks for reading. I hope it helps!

🧞‍🙏 Thanks for reading!

Give some 💖 or 🦄 if you liked this post.
These help other people find this post and encourage me to write more. Thanks!

Check out my projects:

SCuri — Unit test boilerplate automation (with Enterprise support option too)
ngx-forms-typed — Angular form, only strong typed!
ngx-show-form-control — Visualize/Edit any FormControl/Group

Buy me a coffee

Angular Forms Story: Strong Types

Georgi Parlakov — Thu, 02 Apr 2020 15:53:30 +0000

How I strongly typed my Angular forms. And you can too!

Originally published in Angular-In-Depth here.

This is part of the Angular Forms Story series:

Angular Forms Story: Dev Tooling (link)
Angular Forms Story: Strong Types (this one)
Angular Forms Story: The Whole Story (coming up)

Angular Reactive Forms are not strongly typed! AbstractControl and it’s implementations FormControl FormGroup and FormArray do not support strong typing their value or changes or any other property/method. For the longest time, I accepted and worked around that, considering it just one of life’s things — so it goes…

In this article, I want to share the process I went through while gradually adding strong types to my forms. If you just want to see the end result see ngx-forms-typed. It’s strong type, backward compatible (works with Angular 2.4.0 !) and reduces boilerplate.

This work draws inspiration and ideas from “Working with Angular forms in an enterprise environment” and “Building scalable robust and type safe forms with Angular” and others. I would encourage you to check those articles out.

For my job, I had to do a reasonably large form, enough so to make me fear the business logic mixing with the form logic and sub-parts of the form. I wanted to have a strongly-typed , easy to use and @angular/forms_-y_ way to extract sub-forms components from a large form. Much like we extract components to handle their own concerns. The (sub)form component would need to conform to the following requirements:

have a strongly typed model
@angular/forms — compatible
use existing abstraction for communication (the AbstractControl and the ControlValueAccessor) to handle validation, status changes, etc.

In short, I wanted to have a component that could be used as a single control in a larger form AND be a form in its own right with multiple fields, validation, status changes. And all the while keeping the parent form happily unaware of implementation details and communicating via the AbstractControl API.

For example Address as a sub-form in a Person form and in an Order form. But the full form in a NewAddress form.

In the beginning, I was decorating my FormGroup-s and their constituent FormControl-s with types, like this:

Now I could rely on strong typing during refactoring or adding/removing features. Any Person type change would trickle down to the form — for example, if the property address was to be added I would get an error immediately (vs run time and maybe):

Then I suffered the form.controls.get('name') way of reaching my controls. I did not like the pattern of creating a public getter for it. Mainly, I wanted type safety. So:

Yaay, intellisense! Productivity!

Now I had intellisense for my controls! Oh joy and productivity 😂⚒👷‍♂️. And with a bit more finesse (and beating Typescript into submission) I had a type-dependent form group (or model-dependent if you will). See this little change trickling down:

Notice the email changed into emailS and causing Typescript giving me very helpful advice :)

Did you notice the as unknown as PersonFormGroup (at the end of the form group instantiation form = new Form(…) as unknown …)— that’s what I was referring to as beating Typescript. In this case, I knew better than it what the actual shape of the run-time thing is! This is the only case so far usually, Typescript❤ ️knows better!

Taking this work to the next step is to type as much of the FormControl/FormGroup/FormArray types as possible. And the result is the package ngx-forms-typed. It provides the TypedFormControl (GitHub src)TypedFormGroupand TypedFormArray types.

For example, let’s take a look at TypedFormControl:

It adds a strong type to the value and valueChanges properties of FormControl so that you know what shape the value is when using it. It also strong types the method setValue so that you’d need to pass in a value of the expected type and maybe options — also strong typed. reset method is strongly typed too. See ResetValue source.

And helper functions for creating instances with those types typedFormControl(GitHub src), typedFormArray and typedFormGroup which make the creation of forms strongly typed too:

TS error pushing us towards the correct type of the forms control.

Does intellisense too!

The function itself only instantiates a FormGroup which is to say that it is compatible with existing forms code and can be used next to it without breaking it:

I wanted to enable forms and sub-forms to communicate i.e. when sub-form get’s touched — touch the parent when it gets invalid — make the parent invalid too. These two are supported by the ControlValueAccessor abstraction. I also wanted to force the sub-form to get touched on cue from the parent, in order to show validation, which is not supported by ControlValueAccessor. I wanted to use existing ControlValueAccessor-AbstractControl channels of communication.

I came up with a builder-like pattern for interaction with controls of a form group/array. It comes in a function called forEachControlIn (see full code in GitHub). Its goal is to make interacting with controls in a form and between forms easy. It relies on having references to the forms.

Finally, to avoid boilerplate I tied it all in a ControlValueAccessorConnector (see full code on GitHub). It handles all the connection logic between a parent form and a sub-form.

See a working example here and code in Stackblitz:

angular-forms-story-strong-types - StackBlitz

Just like a user would expect, pressing the Submit button shows validation for the whole page. Blurring an input control shows validation only for that control.

There’s an example of a nested form using formGroup directive in the party-form.component and a stand-alone one, using ngModel in app.component.

You can see the library’s readme here.

This was a short introduction to the library. Would you like to see a deep dive? Vote here:

https://medium.com/media/2c1089cfe2771558f59ffd9ec0463dc4/href

This approach (and package) is not the only one and there are several other approaches. Check out the next article in the series where I summarize my research in the @angular/forms space of packages, PRs, and articles.

I am working on a few Open Source Angular Dev Tooling projects. Check them out at:

SCuri — Unit test boilerplate automation (with Enterprise support option too)

ngx-forms-typed — Angular form, only strong typed!

ngx-show-form-control — Visualize/Edit any FormControl/Group

Angular Forms Story: A Dev Tool

Georgi Parlakov — Tue, 17 Mar 2020 21:24:26 +0000

A simple tool to make Dev’s life easy :)

This is part of the Angular Forms Story series:

Angular Forms Story: A Dev Tool (this one)
Angular Forms Story: Strong Types (link)
Angular Forms Story: The Whole Story (coming up)

More than once, while developing forms in Angular application I had to template hack {{form.value | json}} and {{form.valid}} and form.pending while editing to check if my form control was actually doing what I wanted it to do.

I thought:

Wouldn’t it be nice if there was a component to show me all the info about the form?

So I created it:

ngx-show-form-control

Named and draggable window!
Status — dirty/pristine, touched/untouched, valid/invalid/pending/disabled
Value JSON.stringify-ed. Editable — edited value appears in form!
Minify and Maximize And MORE… * Resizable (see bottom right corner) * Multiple instances supported * Only visible in dev builds! No danger of it showing in production!

See it in action :

Making it a directive and supporting older Angular versions is on the roadmap. It now needs Angular v5 at least — due to using Metadata version 4

Go check it out and submit issues at https://github.com/gparlakov/forms-typed/issues.

I am working on a few Open Source Angular Dev Tooling projects. Check them out at:

SCuri — Unit test boilerplate automation (with Enterprise support option too)

ngx-forms-typed — Angular form, just typed!

ngx-show-form-control — Visualize/Edit any FormControl/Group

Angular Unit Test Automation

Georgi Parlakov — Tue, 15 Oct 2019 06:59:56 +0000

How can I automate my unit test creation and update chores?

What if I told you that I can auto-generate your unit tests? And then maintain them?

TL;DR;

No chores. No boring boilerplate. Just tests.

Install SCuri and create or update a spec file by:

**npm install scuri**
 **ng g scuri:spec --name src/app/my.component.ts** 
_# OR to update an existing spec_
**ng g scuri:spec --name src/app/with-spec.component.ts --update**

This requires Angular CLI 6. For previous versions see troubleshooting section in the readme.

Caption actually uses the schematics CLI which supports Angular < 6

Wow, this looks great. But what’s the catch?

There is actually just one:

Structure your tests in a specific fashion.*

*or rather keep it as the tool generates them

SCuri assumes that the tests will have a specific structure. It assumes there is a setup function (or creates one if it’s missing) where the setting up of the spec conditions occurs. And that the names of the tests include the names of public methods on the class-under-test. Read more about it in this article (see point 4 and on).

These assumptions allow it (SCuri) to automate the tasks of creation and update of unit tests for Angular components, services, and plain old typescript classes.

But wait, ng c component already generates a spec, right? Why do I need another tool?

Yes, it does. But as soon as the first dependency is added to that generated component and the test needs to be updated , that’s where Angular CLI falls short. And that’s where SCuri shines!

Let’s try it!

Assuming SCuri is installed npm install scuri in the project folder and the Angular CLI is version 6 or greater.

I’ve created a demo component with no tests

ng g demo --skipTests

ng g scuri:spec --name src/app/demo/demo.component.ts

There are a couple of things to note here:

The setup function. This is where all the setting up of tests preconditions and dependencies would occur.
The autoSpy function. This is what will create automatic mocks for your dependencies. It will take any class and mock its public methods (s_ee details in_ SCuri readme). And it can be generated for you by the tool! ng g scuri:autospy — for jasmine:

Now for the fun part:

Create a service:

ng g service my

Include it it the component dependencies. Let’s also add a public event handler method for good measure.

Now run ng g scuri:spec --name src/app/demo/demo.component.ts --update

And now the dependency is mocked , included in the MyComponent build function! And the new method has a test scaffolded for it!

All that’s left is the logic, that only you , the human being, can author.

What else can I use the setup function for?

For each test case, we usually require some setup. And leaving that in the it body makes it difficult to read. So we can use the builder that setup returns and attach methods on it for setting up the specific details.

For example, let’s say that we need to fetch some data in ngOnInit

We run ng g scuri:spec --name src/app/demo/demo.component.ts --update again to update dependencies. And now we can use the mock created by autoSpy in the test:

Or we can move the mock part in the setup builder:

Now our test is cleaner and calls a method that is named so as to speak to the reader what the goal is, rather than expect them to read through the mock declaration and extrapolate what the author meant. The name carries the author’s intent! (this is a contrived and trivial example — think of what your components do and how you mock that!)

Notice how we call the withHeroes in the default builder method. That’s because every time we call ngOnInit we’ll need an observable to subscribe to, otherwise our we’ll get an exception that there is no subscribe method on undefined

Let’s put SCuri to the test! (:

Let’s try it on a real-world project! What better than The Real World Example App! It’s an example Medium clone Angular app, that just so happens has no unit tests (as of today).

git clone [https://github.com/gothinkster/angular-realworld-example-app](https://github.com/gothinkster/angular-realworld-example-app)
cd angular-realworld-example-app
npm install scuri
ng g scuri:spec --name src/app/home/home.component.ts

And now the src/app/home/home.component.spec.ts has the dependencies mocked and ready, and the public method tests scaffolded. All ready for you to do the tests magick.

No chores. No boring boilerplate. Just tests.

An Opinionated Approach to Testing Angular

Georgi Parlakov — Fri, 12 Jul 2019 13:26:51 +0000

Angular plus Jest. Logos from https://worldvectorlogo.com/logo/angular-icon https://freebiesupply.com/logos/jest-logo/

Informed by a few years of writing, reading and depending on tests.

Originally posted at https://medium.com/ng-gotchas/an-opinionated-approach-to-testing-angular-4cf14ef7463f

First, let me lay out the basic points and then we’ll jump into details.

Disclaimer: I will not try to convince you that unit testing is a good idea. If you don’t think it is, go read something else. The opinions expressed here may seem arbitrary and just plain wrong if you are not relying on unit tests for your everyday work.

1. No logic in the templates — just call an event handler public method. We can trust Angular to do its part (that is already tested — example) which is to call us. And we do our part — test only our code.

2. Include all dependencies as injectable constructor params. Document, Date.now(), requestAnimationFrame etc.

3. All properties and methods used by the template are *public *. This might be obvious to you but it was not for me initially. And the language service wasn’t there to tell me otherwise.

4. In each test have a setup function that sets up all required state and infrastructure for the test.

5. In the setup function use the builder pattern to set up the dependencies and construct the class under test.

6. Use Jest (jest.io) [Jest’s snapshot feature (this one is marginally useful)]

7. For button clicking and input typing i.e. what the user uses the UI for, create a few UI (aka end-to-end) tests which actually use the user interface

All right — now for some details:

1. No logic in the templates — just call the event handler public method — this way we can trust Angular to do its part (which is already tested example). We test only our code. Consider the following two versions of the same template:

The top one looks like a smart and readable choice when writing the template but actually requires for your test to use the template , which needs to get compiled etc. It also requires any person reading the code to have both the my.component.html and my.component.ts open in order to follow the logic.

The bottom one allows for the test to instantiate the component class (no compiling of the template and so on) and simply call the public method onHereButtonClick(). The name of the handler is a convention combining the element name and the event name — onHereButtonClick — when here button is clicked do something — the logic.

This way the my.component.ts holds the logic and not the template and a person reading it can follow the logic that much easier.

…trusting that the DOM and/or Angular will call my code and when I call them they will do their job…

1.1. That allows us to only test the class without compiling the whole component with its .css and .html. Much faster, easier and no need to keep all the .ts and .html and .spec.ts open in order to write the tests

Include all dependencies as injectable constructor params. Document, Date.now(), requestAnimationFrame etc. Any direct calls to browser APIs like Date.now() or requestAnimationFrame or setTimeout become hard to test. But, if we wrap those in services the tests become trivial.

The document is already provided by the framework: https://github.com/angular/angular/blob/2b44be984e0932bab83fcea015fc5b4ee2d3b151/packages/common/src/dom_tokens.ts#L11-L19

2.1. Use the AAA — arrange act assertpattern/convention. It allows for the person reading the code to discern what happens where.

Any similar convention —ex When Then Should — would do the trick as long as the whole team is on board of course.

All properties and methods used by the template are public . This might be obvious to you but it was not for me initially. And the language service wasn’t there to tell me otherwise. Since the method needs to be used by the template, which is ‘external’ to the class, it needs to be public. That’s how I think about it. Also in the test that allows us to decide what we need to test — any public method.
In each test have a setup function that sets up all required state and infrastructure for the test.

Instead of relying on the TestBed we shift its responsibilities to a setup function. We call that function in each test (or in beforeEach hook) and it returns to us an object that allows for specifying what is relevant to this test and constructing the class-under-test. In case of changes in the dependencies or the public API of the class (due to everchanging requirements), we’ll be able to update the test in a single place — the setup function.

4.1 Use autoSpy. That’s a function that can create an object with the methods of the class mocked automatically.

It allows the returned object to get used like:expect(o.method).hasBeenCalledWith('arg1'); and o.method.mockReturnValue(10).

This is a simple implementation. If a service needs to return a complex object you need to take the mock and add that behavior. See the example in the next section (5.) withTempUser method on the builder object.

A similar idea is implemented in the jasmine-auto-spies.

In the setup function use the builder pattern to set up the dependencies and construct the class under test. The builder pattern allows for dot-chain declaring of each particular test’s needs.

In the following example, we need to have a temporary user on our site which only stores their email in their localStorage . Only tested one of the methods for conciseness.

In the builder we have the withTempUser method that allows us to specify that there is a temp user with a certain email. That takes the messy mock code and:

moves it in one place, out of the test for improved test readability and maintainability
preserves the intention for the person reading so they can see what we wanted to have happen, instead of trying to guess by reading the implementation

For each business logic case , we can add a similar method that does a piece of dependency or state set up.

5.1. That (the setup function implementing the builder pattern) also allows for some automation. Basically, a tool that can read the class-under-test and create a test for it following these guidelines. And update that test when the class-under-test changes. See SCURI.

6. Use Jest. It has (almost) identical API to Jasmine so migrating existing tests and testing skills is trivial. Jest has a bit better errors test than jasmine, like showing you exactly what is the difference between the expected and the actual value in a failed test. It does not depend on starting a server and running a browser. Instead, it uses the JsDOMlibrary and everything runs in a node.js process. It parallelizes the tests using all available CPU cores. It supports mocking js modules so that your tests see the mocked ../my-service.js instead of the actual ../my-service.js Don’t rely on this for all unit tests, but this feature saved our butts on a few occasions.

Finally — for our use case at propy.com— we could not start Chrome on our build machine and that was the main turning point to switch to our Angular unit tests using Jest.

Switching to Jest is even simpler when using this Jest Schematic.

Finally, Jest has a nice console UI when running in jest --watch mode. Lets you filter test by file name, test name, status failed or just changed i.e. understands git changes and runs only the currently changed files — which makes a lot of sense.

An error report from Jest. From the jestjs.io site.

Using Jest’s snapshot feature proves to be marginally useful and a major pain to maintain. For the 6 months we used it we had maybe 1 or 2 instances that it may be caught something. That is — during a code review, I noticed that after changing something in a component a whole section disappeared from its rendered HTML (which is what we did a snapshot on). I am now not doing snapshots on the new components I write.

See this great article for a stronger opinion on that https://medium.com/@tomgold_48918/why-i-stopped-using-snapshot-testing-with-jest-3279fe41ffb2

For testing the actual UI , like button clicking and input typing (what the user experiences) create UI (aka end-to-end) tests that actually exercise the UI as a user would. I use Puppeteer ( https://pptr.dev/) because it’s developer friendly, but have also used Protractor ( https://www.protractortest.org/#/) and heard good things about Cypress ( https://www.cypress.io/)

Bonus thoughts:

Unit tests that do button clicking and event dispatching I find expensive to write and very low return on investment ( ROI ). I tend to not write any of those. Instead, I control the instantiation of the class-under-test (component, directive, service) via the setup builder then invoke the public methods and examine the results, trusting that the DOM and/or Angular will call my code what I declared I wanted it called and when I call them— they will do their job.

They are expensive to write because I need to uncover the underlying DOM calls, usually hidden by Angular (e.g. dispatchEvent, addClass, focus) all the while Angular actually provides that functionality and has tested it thoroughly.

Hey, thanks for reading and happy to discuss — how do you do your testing?