@sierralabs/forms-api v1.3.0

Sierra Labs Forms API

Sierra Labs Forms API Library for managing form schemas, form templates, form data as well as generating/publishing form tables. The library consists of:

• TypeORM entities:
  • FormSchema - Stores latest working draft of a form schema JSON. The form schema JSON is based on TypeORM's EntitySchema data type.
  • FormSchemaVersion - Stores published versions of the schema JSON. The schema JSON should match exactly 1:1 with the published Form table.
  • FormSchemaDelta - Stores history of all form schema changes allowing for undo/redo and operational transformation logic. The Delta json is based on the @sierralabs/track-changes module.
  • FormTemplate - Stores latest working draft of a form template JSON. The form template JSON is based on the StateNodeConfig data type from the @sierralabs/state-machine.
  • FormTemplateVersion - Stores published versions of the form template JSON.
• NestJS Form API endpoints:
  • Form Schema API
  • Form Template API
  • Form API
  • Form Permission Guards
  • Schema Table Migration library

Getting Started

Install the @sierralabs/forms-api package along with peer dependencies

# for npm
$ npm install @sierralabs/core @sierralabs/forms-core @sierralabs/track-changes @sierralabs/state-machine @sierralabs/nest-utils @sierralabs/forms-api

# or for yarn
$ yarn add @sierralabs/core @sierralabs/forms-core @sierralabs/track-changes @sierralabs/state-machine @sierralabs/nest-utils @sierralabs/forms-api

Modify your project's AppModule to import the FormModule and configure the API permissions (See FormModulePermissions interface for more details). The API permissions are based on @sierralabs/user-api user permissions.

import {
  FormModule,
  FormSchema,
  FormSchemaDelta,
  FormSchemaVersion,
  FormTemplate,
  FormTemplateVersion,
} from '@sierralabs/forms-api';

@Module({
  imports: [
    ConfigModule.forRoot(),
    TypeOrmModule.forRoot({
      ...
      entities: [
        __dirname + '/entities/**.entity{.ts,.js}',
        //Include the below entities from the forms-api package
        FormSchema,
        FormSchemaVersion,
        FormSchemaDelta,
        FormTemplate,
        FormTemplateVersion,
      ],
      ...
    }),
    ...
    // You can set up basic permissions by passing in the `permissions` options property
    FormModule.forRoot({ permissions: { roles: ['Admin'] } }),

    // For more granular permissions you can set roles for each Entity CRUD
    FormModule.forRoot({ permissions: {
      schema: {
        create: { role: 'Admin' }, // You can use a role name string
        read: { roles: ['$everyone'] }, // You can pass in an array of role names
        update: { roles: ['Admin'] },
        delete: { guard: CustomGuard } // write your own custom NestJS Guard
      },
      template: {...},
      form: {...}
     } }),
  ],
  ...
})
export class AppModule {}

Development & Contributing

To develop and contribute to the @sierralabs/forms-api project from another project that has a dependency on this module you can use Yalc. Yalc works better then yarn/npm link due to node_module dependency issues with symlinking that impact modules like typeorm and nestjs.

# Install yalc if you don't already have it installed
$ npm install -g yalc

# Publish `@sierralabs/forms-api` into your local yalc repo
$ yalc publish

# On the project that is using `@sierralabs/forms-api` run
dependent-project $ yalc link @sierralabs/forms-api

# Now back on the `@sierralabs/forms-api` folder you can push changes to the linked projects by
$ yalc push

# Lastly, to undo the yalc link reference, you'll need to force the package install on the dependent project
dependent-project $ yarn install --force