DEV Community: Htech

Trabajando con registros privados

Israel Olvera — Mon, 14 Mar 2022 19:30:05 +0000

El contenido presentado es orientado al ambiente de desarrollo con JS y TS, y hay una gran cantidad de recursos que pueden explicar este contenido, pero yo trataré de explicarlo de la forma más clara y sencilla que me sea posible.

Claro está que también compartiré las cosas con las que me he encontrado y te daré la solución con un fundamento detrás para que no solo hagas copy/paste

Los registros privados son muy comunes, en el entorno empresarial; cuando se requiere alojar múltiples módulos de uso interno, sin necesidad de pagar por el servicio organizacional de npm. También servicios de alojamiento de repositorios como Github y GitLab ofrecen la funcionalidad de tener esta característica.

Contenidos

Login
- Login con 2FA activo
Instalación

Login

El login es sencillo, recordemos que por defecto siempre se va a apuntar al registro público de npm, entonces, para hacer el login basta con ejecutar:

npm login

ó bien para apuntar a un registro privado:

npm login --registry <dirección-del-registro>

Cambiar la configuración del registro por defecto, también es fácil:

npm config set registry <dirección-del-registro>

con esta modificación se puede ejecutar npm login y el login será directo a la dirección del registro que se asignó

NOTA: Esta configuración solo será aplicada de forma "local", pero para que las modificaciones tomen efecto para todo el sistema recuerda usar la bandera --global

Login con 2FA activo

Cuando se hace uso del Two-Factor Authentication (2FA), se requiere un token para poder hacer un login "exitoso". Si se realiza un login sin el token y se trata de instalar alguna dependencia organizacional o de un repositorio privado; la instalación fallará.

Para lograr realizar la instalación se tiene que realizar lo siguiente:

1.- Ejecutar: npm login
2.- Obtener el token que se ha creado

Este token se genera automáticamente, se encuentra en el archivo .npmrc ubicado en el directorio $HOME

En Windows es: C:/Users/ y en Linux, si soy sincero, no lo recuerdo y no quiero obtener la respuesta de google; quiero reforzar un poco la memoria. Pero puedes obtener la ruta del directorio con $HOME.

El token es la cadena de texto dentro de las comillas después de :authToken=, este a su vez deberá corresponder de la dirección del registro a la cual está asignada.

3.- Volver a ejecutar el login pero agregando el token al final de la siguiente forma:

npm login --registry <dirección-del-registro>/:_authToken=<token>

4.- Volver a tratar de instalar las dependencias

Instalación

Cuando se hace uso de los registros que proveen servicios como Gitlab, se requiere un token (con los permisos para acceder al registro), puedes encontrar más información en Gitlab | Package Registry.

NOTA: El token para la instalación de dependencias no es el mismo que el token que se requiere para hacer el login

Es común que en los proyectos se llegue a ver un archivo .npmrc dentro del proyecto, con la configuración para poder conocer los scopes (alcances) de las dependencias que el proyecto requiere

NOTA: Es IMPORTANTE que NUNCA, NUNCA, NUNCA se agreguen tokens o keys dentro de estos, por cuestiones de seguridad, es más conveniente que se usen variables de entorno para asignarlos.

Como se puede ver en Gitlab, hay varias formas de identificar a los módulos/dependencias de un proyecto. En la documentación se centra en el CI/CD, pero se puede realizar a nivel instancia, como se expondrá en este articulo.

Primero en el proyecto, debe de existir el fichero .npmrc, en el que se deberá identificar al registro del cual se obtendrán las dependencias, como por ejemplo:

@foo:registry=https://gitlab.example.com/api/v4/packages/npm/
//gitlab.example.com/api/v4/packages/npm/:_authToken=${TOKEN}

NOTA: Es importante que se mantenga la sección ${TOKEN}, esto; tomará el valor de la variable que se indica entre las llaves

Ahora, deberás generar un token, como ya se mencionó este token deberá tener permisos para poder acceder al registro.

Este token puede ser usado como variable del entorno, si se ejecuta el siguiente comando:

export TOKEN=<token>

Esto funcionará siempre en entornos *NIX, en sistemas Windows, en lo personal uso Git Bash pero desafortunadamente con esta ultima opción; esto no persiste en el entorno. En entornos Windows con sub kernel de linux, desconozco si funciona.

Hecho esto, ya se podrán instalar las dependencias desde los registros privados.

Managing the state in Vue (responsibly)

Jesús Escamilla — Thu, 02 Sep 2021 22:29:54 +0000

Summary:

Learn different ways to manage state.
Review some examples.
Evolution.
Recommend a good structure.
Conclusions.

In this post, we will be covering the most common ways to manage state in a Vue app. I will share some of my personal experience and the evolution of our implementation in our workplace, which allows us to structure them depending on our objectives.

Here we go!!!

A lot of different ways to manage state

In summary, we can classify them in:

Local state inside component.
Global state in the window object.
Global state with vuex.
Shared observables.
Shared reactives.

Examples

The examples are written for Vue 2 or Vue 3 and some code may be omitted, the objective is to specify the parts about state management. Of course I'm here to help you if something is unclear.

Local state inside component

export default {
  data() {
    return {
      text: ''
    }
  },
  methods: {
    updateText(value: string) {
      this.text = value;
    }
  }
}

import { ref } from 'vue';

export default {
  setup() {
    let isLoading = ref(false);

    const setLoading = (status: boolean) => {
      isLoading.value = status;
    }

    return {
      isLoading,
      setLoading
    };
  }
}

For both Vue versions the example is essentially the same, shown in two different ways. Basically a var updated by a method.

That could be the simplest form of state management; you may consider that updating the variable directly is better, but I recommend using a method. Primarily because a method is better for understanding the objective and possible values (especially if you are using typescript).

As a recommendation, try and maintain the most amount of data separated, in its own component, don't share data unless you truly need to.

Global state in the window object

Have you used something like this?

window.global.config= {};

Spoiler, I wouldn't recommend doing this in this way for most cases because there are no controls in place. Although, in a simple app, it could be a fast way to share some high level data.

Another popular use in Vue is:

window.global.eventBus = new Vue();

We'll leave communication between components for another post, here we will talk within the context of state management.

I've decided to include this here because I consider this a shortcut if you only need to share a small amount of data, as a method or an utility. Keep in mind that this is for small amounts of data, for larger amounts of data, please consider the following option:

Global state with vuex

Now a general example for a posts vuex module:


import * as types from '../mutation-types';

const state = {
  isLoading: false,
  posts: []
};

const getters = {
  isLoading: () => state.isLoading,
  posts: () => state.posts,
  unreadedPosts: () => state.posts
    .filter((post) => post.readed === false)
};

const actions = {
  setLoading({ commit }, status) {
    commit(types.SET_LOADING, status);
  },
  loadPosts({ commit }, posts) {
    commit(types.LOAD_POSTS, posts);
  }
};

const mutations = {
  [types.SET_LOADING](_, isLoading) {
    state.isLoading = isLoading;
  },
  [types.LOAD_POSTS](_, posts) {
    state.posts = posts;
  }
};

export default {
  state,
  getters,
  actions,
  mutations
};

And the Vue 2 component implementation

import { mapGetters, mapActions } from 'vuex';
import api form './api';

export default {
  computed: {
    ...mapGetters(['posts'])
  },
  methods: {
    ...mapActions(['loadPosts']),
    async getPosts() {
      const posts = await api.getPosts();
      this.loadPosts(posts);
    }
  }

As you can see I added a basic api method to get posts and send them to the state.

I commonly see people make the api request in the vuex action, I used to do it that way too, but now I highly recommend separating the concerns no matter how simple the code might seem to be. You'll thank me later, as the code gets larger.

Also remember that executing an action, calling a mutation, updating a state and reading getters make up a beautiful cycle that you need to respect and keep as simple as possible.

So, if you need a vuex, keep actions limited to (at most) validating the entrance of data, never asynchronous or unpredictable methods. Keeping mutations only to update the state and getters only to provide data or basic filtering/formatting.

Finally, when exactly do you need vuex? Anytime you need to retrieve data that all the application needs, within different views and modules.

Shared observables

As simple as this:

import Vue from 'vue';

export default Vue.observable({
  isOpen: true
});

A Vue observable exposes a reactive object that could be accessed and updated in different components such as:

import sidenavState from './sidenavState';

export default {
  computed: {
    isOpenSidenav() {
      return sidenavState.isOpen;
    }
  },
  methods: {
    setSidenavStatus(status: boolean) {
      sidenavState.isOpen = status;
    }
  }
}

It's not a law, but I highly recommend reading the observable by a computed property (which becomes useful later if you need to listen to it by a watch) and updating by a method (remember the update methods I listed in the examples).

The advantage here is that other components can read from the same observable and get updated with the same data.

In principle it’s a simpler alternative to vuex, but without actions and mutations.

In general, remember to add methods or computed properties to keep it manageable.

Also, I recommend vue observables for small-medium things, like data shared between views in the same module, but with a data nesting or no direct relation that allows props/emits communication.

Shared reactives

In Vue 3 composition api, the evolution of observables are here:

import { reactive, readonly } from 'vue';

const state = reactive({
  isMovile: false
});

const setMovile = (status: boolean) => {
  state.isMovile = status;
};

export default {
  state: readonly(state),
  setMovile
};

In this example, we keep them if the app is in mobile state, it can be used for taking responsive decisions or hiding/showing components.

Finally, expose a method to update and, woah, a readonly helper to help us prevent someone from directly updating the state.

That is the main advantage I see in comparison to observables. I really recommend exposing the state as a readonly and update by the methods I've described.

I see a lot of potential in that structure and recommend it thoroughly for all application levels and replacement of observables if you're migrating from Vue 2 to Vue 3.

An important recommendation I can give you is to not use only one state file, it's much better to divide them into single concerns and locate them in the corresponding app level (component, view, module or app).

Also remember to keep exposed methods simple, never asynchronous, complex stuff or business logic.

Evolution from vuex to reactives

I started (like many others) with a flux styles strategy, coming from react and redux, in vue (2.x), with vuex as expected.

Our projects started very small, so we used vuex for everything, what could go wrong?

We were thinking in a lineal flow, where data is generated as the user progresses through to the final view. We considered 4 or 5 views, simple enough, one vuex module per view.

All was well at first, but as new views were added, alternate flows, processes that came in and out of external sites (say goodbye to your saved state), it all became a nightmare to maintain.

That is when we started exploring observables and even more recently reactives, introducing Vue 3 to our projects.

We found that major cases really don't need much data to be shared globally so vuex was omitted in new projects. Now, Reactive stores have been introduced, they are simpler because they can be divided on each app level that requires it. Also because most data only needs to be in its respective component.

Structuring

Now the best part, how to organize this? I propose a hierarchical way, so it can be easy to understand the scope of the state.

This is not limited to one specific state management method, but I will recommend something for each level based on my experience.

Component

Use internal data options, some refs or reactives. Data received by apis lives only in this component and is shared to others by props or events.

If it is a big amount of data, it may be taken out to another file in the same folder level.

View/module

This is similar to Component level, but, think of a view as a classic routed component, and a module as a more complex component (header, menus, etc.). So consider three more possible things:

There are more than two nesting levels.
So many props are required for many sub components.
Some get/set methods are required to share too.

Using Observables or reactives in a specific file at the view/module level is a good option.

Between views/modules

First of all, if we talk about sub-views or low-level modules, the escenario may be similar to the previous level. Here, we are talking mostly about first level views or modules, and between them we need to share state.

Here, we use an app level shared state. It may be created with reactives or vuex modules but remember to organize based on objectives or entities, not in view names or module names (if this is the case, go back to previous level).

App

If you got here, we can talk about data that is not related to any view, module, or component, like some authentication status, or user configurations may be.

Reactives or Vuex are recommended but the main difference with previews level is, as you can imagine, that the state managed here is independent of all and, by definition, may be useful for each part of the application.

Top to down

At this point you might say, if I have a state value in App level, I can access them in any component, but that is a bad idea. Going back to the hierarchical proposal, low level components must get data only from props.

For example, a view component can access data from app level state and share it to children by props. This can be done easily and ensures that the children remain independent, no need to know more about higher levels, while making them more shareables.

Bonus: Vue reactives vs vuex

I think a tool is only as strong as the user. So I wouldn’t say no to vuex. In our projects we found there are very limited cases to use it because the composition api utilities and a good structure as shown before give us a simpler and more maintainable way.

If you do, in fact, need all the power and beauty of vuex, remember the previous recommendations.

If you need simplicity and flexibility use the composition api reactive.

Conclusions

Everything I’ve said can be condensed as... the state is something you could have under control, organized, easy-breezy, or you could have a snowball running down hill, about to crush you.

So remember to use the least global state possible, keep it only in its respective components and share it directly by props and events, while maintaining it in specific files within the required level.

Update the state view specific methods to ensure data quality and don't attach low level components to higher levels without reason.

I hope this will help you improve your project structure and keep in order your app state, so that you can have a happier life.

Follow us to get more posts about Vue soon.

Exploring vertical slices in dotnet core

Mig Salazar — Fri, 05 Mar 2021 21:25:58 +0000

Talking about software architecture is complex, often due to the technical aspects but largely due to the fact that there's no single answer, rarely conclusions and always depends on the context.

Why it depends on the context? because it can contains a lot concerns; the strategy and business model, cost and time constraints, team capabilities and skills of each individual team-member, technologies/techniques and their accidental complexity, etc. So, our technical decisions might be biased by all of these things and will change our path toward desired state.

The fact is, technical debt is inherent in software and this gives us enough reasons to look for answers and the best way to build software; even, when the reality can be quite painful.

Our context

Recently at HTech, we started a project that aims to manage the features of other software products. From a digital product perspective, it could be categorized as a back-office software. For me, it represents a set of rules that acts as an interface of business rules from other products. Some considerations about our project are:

The interface rules -inside of our back-office software- of a specific product, must be built by the team that knows the business rules that the specific product has. This means that one team should be able to add functionality without fear of impacting the functionality of another team.
The team is variable depending on the their time and anyone could select for development a jira-issue and work on it.
From (1) and (2) it's likely that the work will be triggered in a bounded time, and there will be a lot of commits of multiple teams at the same time. Communication channels complexity here?
The functionalities are clearly independent from others and also this tasks are generally feature oriented.

Software layers

Generally, in the software architecture space, what we're looking for is an appropriate component segregation. The traditional way is separate the software in layers, and we understand as "layer", as a segregation oriented to non-functional responsibilities; sometimes it's just in a logical and chaotic way; and at best, physical and orderly.

The real struggle and non-trivial thing about layered architecture, is how this layers interact with each other. Some of the most popular software architecture approaches, and accepted in the community, are the concentric-like architectures. For example hexagonal architecture, onion architecture, domain driven design, clean architecture, etcetera.

Something that these approaches have in common is that all of these are trying to keep the core/business layer (a.k.a domain) independent of frameworks and isolated from the rest of the layers. My mental representation of this looks like:

In our backend, generally, we follow these approaches. Although I agree with this, it's true that for many contexts these approaches might not be suitable -or at least not from the beginning-. These architectures are usually complex by nature, they have rigid rules of inversion of control, a lot of abstractions and in many cases they are unnecessary.

My aim here isn't to break with the separation of concerns -and other benefits that these approaches bring us- but given the conditions of our context, such as the fact that the team could be constantly rotating in a bounded time, I am looking for a way to reduce the learning curve that the concentric architectures has. But, at the same time, without losing the notion of the fact that the domain must be pushed toward the center and keeping the ubiquitous language.

Vertical slices

The first time I heard the "vertical-slices" term was in the agile world; and recently, I had the opportunity to listen an online talk by Jimmy Bogard, who promotes an architecture oriented to vertical slices. Basically, his approach is in the following way:

The way he describes this is:

When adding or changing a feature in an application, I'm typically touching many different "layers" in an application. I'm changing the user interface, adding fields to models, modifying validation, and so on. Instead of coupling across a layer, we couple vertically along a slice. Minimize coupling between slices, and maximize coupling in a slice.

So, We can assume that the separation by features can be done simply by organizing the code with the following structure:

|-- src
|   |-- OurProject.csproj
|   |-- Program.cs
|   |-- appsettings.json
|   |-- Feature1
|   |   |-- Controllers
|   |   |-- Services
|   |   |-- Models
|   |-- Feature2
|   |   |-- Controllers
|   |   |-- Services
|   |   |-- Models
|   |-- SharedLogic
|   |   |-- Services
|   |   |-- Models

However, the problem with this -and I have always seen with backend APIs- is that we tend to build a lot of application/domain services, something like this:

This leads us to build a kind of main service that acts as an orchestrator in a typical procedural way; at other hand, this makes us lose notion of which service we need to use when adding new functionality and, even, where to physically locate that service. After a while it becomes chaotic, and indirectly causes, just to mention an example, that our domain entities become into anemic domain models.

Given that, the need to have an intermediary that works as an orchestrator and avoid the use of domain and/or application services for this purpose. One way to solve this is through the mediator pattern.

At this point, we find Mediatr, which is a library that implements the mediator pattern by decoupling the in-process sending of messages from handling messages. The approach, considering the organization by features, is given by the following way:

Walkthrough

Register handlers

First of all, assuming we are using ASP.NET Core and its built-in injection dependency pattern, we need to configure the Mediatr dependencies to register our handlers:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMediatR(typeof(Startup));
}

Handlers

We can think that the Handlers acts -in some way- as the Use Cases of clean architecture. This is the entry point of our feature, from a business logic perspectie. A brief example:

public static class GetBy
{
    public class Query : IRequest<Result>
    {
        public Guid Id { get; set; }
    }

    public class Result
    {
        public Order Order { get; set; }
    }

    public class Handler : IRequestHandler<Query, Result>
    {
        public async Task<Result> Handle(Query query, CancellationToken cancellationToken)
        {
            // our logic here
        }
    }
}

As you notice, there are two nested classes: Query and Result. This two types are scoped under GetBy static class in order to -logically- structure the use case of our feature. That means, this isn't a generic input/output, this is only used in a specific case GetBy. With this, the inputs and outputs of our API are easily to identify and gives us more evident the use of CQRS pattern -which by the way is more like conceptual pattern rather than archiectural pattern-.

But, What's CQRS?. From Greg Young's post:

CQRS is simply the creation of two objects where there was previously only one. The separation occurs based upon whether the methods are a command or a query (the same definition that is used by Meyer in Command and Query Separation, a command is any method that mutates state and a query is any method that returns a value).

There are some other libraries to implement this, even from scratch, but at this time I'm using the same Mediatr library, implementing IRquest and IRequestHandler interfaces.

These concerns (Querys/Commands, Handler and DTO's) can be written in the same file. However, I prefer -but not for all cases- to separate each of these into single files, namespaced by static partial class.

Refactoring our controllers

Then, our controller methods will take the following form:

// obvious code here omitted for brevity

public OurController(IMediator mediator)
    => _mediatr = mediator;

[HttpGet("{id}")]
public async Task<IActionResult> GetBy(GetBy.Query query)
    => Ok(await _mediatr.Send(query));

[HttpPost]
public async Task<IActionResult> Create(Create.Command command)
    => Ok(await _mediatr.Send(command));

Take note that the goal here, is to turn the controller into a logic-agnostic component that just represent a set of input/outputs points for our api.

With this approach, each vertical slice can decide how to manage their request/response:

Pushing the domain

Under this organization, the important thing is to take care the growth of our Handlers. Is extremely important consider the capabilities of our team, to timely detect code-smells and push logic down into domain layer and out of Handlers. There are some code-smells that I consider are very likely to occur with this approach and we must bear in mind.

For example, this bad smells in logic and/or behavioral code:

Large Class
Long Method
Duplicated Code
Combinatorial Explosion
Repeated Switches
Feature Envy
Conditional Complexity
Inappropriate Intimacy
Middle Man

We can use refactoring techniques that are very well documented by Martin Fowler, such as:

Extract Class
Extract Subclass
Extract Interface
Extract Method
Replace Method with Method Object
Move Function
Compose Method
Inline function
Replace parameter with Query

Eventually, if we're on the right way, the approach will take on a domain-centric style.

Also, we can organize our input and output rules through pipelines around the core. This pipelines can be implemented with the same Mediatr library:

So...

This approach will helps us, in addition to orchestrating certain logic, to be able to recognize what we must push to the domain or to external layers, without worrying at the beginning of our project. And, mainly, it can guide to the team to work on independent features without conflicts and minimize problems to identify how the architecture works.

My aim with this is to experiment another approach to organize our code and try to measure in order to find if this really brings productivity to the team; but, without losing sight of SOLID principles, keeping technical debt out and promoting refactoring as a daily practice.

[WIP] The complete demo of this post can be found here

Creating a Vue module with Rollup and Typescript

Jesús Escamilla — Tue, 02 Feb 2021 20:08:57 +0000

Summary:

Install vue-sfc-rollup for scaffolding.
Create a Vue2 module setting with typescript support.
Run for internal development.
Pack and install in other local project.
Publish to NPM.

This post is about a step by step guid for creating a Vue2 module with Rollup and setting typescript support. Finally is explained the basis for running, installing and publishing.

We start with Rollup

I found in rollup a great tool for creating npm modules. Is particulary easy to understend, no need so much configuration but it's open for add more extras depending of your needs.

And... exists vue-sfc-rollup a cli module for scaffolding Vue SFC components, it may be for one component or a library.

1 - Install it globally

npm i -g vue-sfc-rollup

This allows to work the cli on any location.

2 - Go to your project's folder and run:

sfc-init

The wizard ask for some options as follows.

3 - Is Single component or Library?

We select the second.

3 - What's the name?

4 - Prefer Javascript or Typescript?

Of course we select the second now.

5 - And the location?

Remember don't need to create the project folder at first, is created with this prompt.

And that's all, wizard ends, go to your new module folder.

The module guts

vue-sfc-rollup create for us this structure.

Now I explain a little each one by folder:

build

Host the rollup configuration and nothing else.

dev

Here you can do everything you need to see works the module before installing in other place. As you can see contains a basic component to import the library code.

src

Of course has the real library code organized in lib-components subfolder.

That index.ts file is specific to englobe all library components.

The entry.ts file is big important. It expose the library to rollup build process. Generaly you don't need to modify entry.ts except for expose another type of file. I use for exporting Non-vue utilities usualy.

The rest of the files are some browser, babel and typescript config. Update depending of your needs.

Install and Run

The scaffolding create this without installing node modules. Run npm install and npm run serve then.

Is created a local server on 8080 port by default. The current configuration validates typescript syntax here.

If you open the url you can see the default component example.

Add more components

Here was created a library starting with a default component but more could be added.

Only remember to add into index.ts like following.

The presented syntax is so cool. You may change this but the objective is to import and export in one line.

Using Typescript

As shown in the example you can implement Typescript, and it's specially useful in this case for validating the common options into the component, I recomend to create the interfaces, classes and other structures in specific files.

Also the default example shows a particular syntax to get data from component state. I recommend to change in tsconfig.ts settings the noImplicitThis property to false because we ussualy don't need to validate "this" in Vue with options api.

Now simplificate the component as next.

Is not the intention to create a complex library, that's for other post. So now go to local installation.

Packing in a box

Seeing the package.json, it has some commands to build the library in the dist folder depending of the distribution way.

build:ssr, For Server Side Rendering.
build:es, Build as Ecma Script module, this is usualy what we want on a common Vue/Spa project.
build:unpkg, Use this if need to link directly in browser, by a CDN for example.
build, You can use all of previews as one if preffered.

Also I recomend to add this script:

"prepublish": "npm run build"

That is becouse you need to create the bundles before publish (or pack if is the local scenario).

Also in package json is found the configuration to set the correspondig entry point matching with distribution way. And the files to include into the packed module.

As you can see the *d.ts file is include to provide typescript information about the library.

The src folder may be not included except if you want to provide another way to import the components. With the bundles, the parent project only take care on implementing (if compatible). With the source code the parent project now need to asure to build correctly too, posiblelly you as library creator must know a little more about who will use your library in order to maintain compatibility.

Finally we run npm pack. This create a gziped file into the project (remember don't commit it).

Go to other project and install it pointing to the relative gziped file path.

Each change you do in the source code, new pack and new install on to do, the pros of this is no need to update version neither expose uncompleted changes to public.

Publish to npm

If it's ready, now publish to the public NPM repository or a private if case.

Remember to login (npm login) with your npm credentials

Finally run npm publish, keep calm and exhale too.

As explained before the prepublish command runs before send to the repository.

And it's over, now you have a Vue module made easy with rollup and well validated thanks to typescript.

In the future we are going to create content to profundice on some areas about javascript, vue modules, and a something more.

Thankyou for reading.