Merge pull request #4616 from logto-io/gao-init-org-tables

feat(schemas): init organization tables

packages/schemas/alterations/next-1696657546-organization-tables.ts

@@ -0,0 +1,150 @@
+import { type CommonQueryMethods, sql } from 'slonik';
+
+import type { AlterationScript } from '../lib/types/alteration.js';
+
+const getDatabaseName = async (pool: CommonQueryMethods) => {
+  const { currentDatabase } = await pool.one<{ currentDatabase: string }>(sql`
+    select current_database();
+  `);
+
+  return currentDatabase.replaceAll('-', '_');
+};
+
+const enableRls = async (pool: CommonQueryMethods, database: string, table: string) => {
+  const baseRoleId = sql.identifier([`logto_tenant_${database}`]);
+
+  await pool.query(sql`
+    create trigger set_tenant_id before insert on ${sql.identifier([table])}
+      for each row execute procedure set_tenant_id();
+
+    alter table ${sql.identifier([table])} enable row level security;
+
+    create policy ${sql.identifier([`${table}_tenant_id`])} on ${sql.identifier([table])}
+      as restrictive
+      using (tenant_id = (select id from tenants where db_user = current_user));
+
+    create policy ${sql.identifier([`${table}_modification`])} on ${sql.identifier([table])}
+      using (true);
+
+    grant select, insert, update, delete on ${sql.identifier([table])} to ${baseRoleId};
+  `);
+};
+
+const alteration: AlterationScript = {
+  up: async (pool) => {
+    const database = await getDatabaseName(pool);
+
+    await pool.query(sql`
+      create table organizations (
+        tenant_id varchar(21) not null
+          references tenants (id) on update cascade on delete cascade,
+        /** The globally unique identifier of the organization. */
+        id varchar(21) not null,
+        /** The organization's name for display. */
+        name varchar(128) not null,
+        /** A brief description of the organization. */
+        description varchar(256),
+        /** When the organization was created. */
+        created_at timestamptz not null default(now()),
+        primary key (id)
+      );
+
+      create index organizations__id
+        on organizations (tenant_id, id);
+    `);
+    await enableRls(pool, database, 'organizations');
+
+    await pool.query(sql`
+      create table organization_roles (
+        tenant_id varchar(21) not null
+          references tenants (id) on update cascade on delete cascade,
+        /** The globally unique identifier of the organization role. */
+        id varchar(21) not null,
+        /** The organization role's name, unique within the organization template. */
+        name varchar(128) not null,
+        /** A brief description of the organization role. */
+        description varchar(256),
+        primary key (id),
+        constraint organization_roles__name
+          unique (tenant_id, name)
+      );
+
+      create index organization_roles__id
+        on organization_roles (tenant_id, id);
+    `);
+    await enableRls(pool, database, 'organization_roles');
+
+    await pool.query(sql`
+      create table organization_scopes (
+        tenant_id varchar(21) not null
+          references tenants (id) on update cascade on delete cascade,
+        /** The globally unique identifier of the organization scope. */
+        id varchar(21) not null,
+        /** The organization scope's name, unique within the organization template. */
+        name varchar(128) not null,
+        /** A brief description of the organization scope. */
+        description varchar(256),
+        primary key (id),
+        constraint organization_scopes__name
+          unique (tenant_id, name)
+      );
+
+      create index organization_scopes__id
+        on organization_scopes (tenant_id, id);
+    `);
+    await enableRls(pool, database, 'organization_scopes');
+
+    await pool.query(sql`
+      create table organization_role_user_relations (
+        tenant_id varchar(21) not null
+          references tenants (id) on update cascade on delete cascade,
+        organization_id varchar(21) not null
+          references organizations (id) on update cascade on delete cascade,
+        organization_role_id varchar(21) not null
+          references organization_roles (id) on update cascade on delete cascade,
+        user_id varchar(21) not null
+          references users (id) on update cascade on delete cascade,
+        primary key (tenant_id, organization_id, organization_role_id, user_id)
+      );
+    `);
+    await enableRls(pool, database, 'organization_role_user_relations');
+
+    await pool.query(sql`
+      create table organization_role_scope_relations (
+        tenant_id varchar(21) not null
+          references tenants (id) on update cascade on delete cascade,
+        organization_role_id varchar(21) not null
+          references organization_roles (id) on update cascade on delete cascade,
+        organization_scope_id varchar(21) not null
+          references organization_scopes (id) on update cascade on delete cascade,
+        primary key (tenant_id, organization_role_id, organization_scope_id)
+      );
+    `);
+    await enableRls(pool, database, 'organization_role_scope_relations');
+
+    await pool.query(sql`
+      create table organization_user_relations (
+        tenant_id varchar(21) not null
+          references tenants (id) on update cascade on delete cascade,
+        organization_id varchar(21) not null
+          references organizations (id) on update cascade on delete cascade,
+        user_id varchar(21) not null
+          references users (id) on update cascade on delete cascade,
+        primary key (tenant_id, organization_id, user_id)
+      );
+    `);
+    await enableRls(pool, database, 'organization_user_relations');
+  },
+  down: async (pool) => {
+    await pool.query(sql`
+      drop table organization_role_scope_relations;
+      drop table organization_role_user_relations;
+      drop table organization_scopes;
+      drop table organization_roles;
+      drop table organization_user_relations;
+      drop table organizations;
+    `);
+  },
+};
+
+export default alteration;

packages/schemas/src/foundations/schemas.ts

@@ -1,5 +1,5 @@
 import { type SchemaLike } from '@logto/shared/universal';
-import type { ZodObject, ZodType, ZodOptional } from 'zod';
+import type { ZodObject, ZodType, ZodOptional, ZodTypeAny } from 'zod';
 
 export type { SchemaLike, SchemaValue, SchemaValuePrimitive } from '@logto/shared/universal';
 
@@ -7,13 +7,23 @@ type ParseOptional<K> = undefined extends K
   ? ZodOptional<ZodType<Exclude<K, undefined>>>
   : ZodType<K>;
 
-export type CreateGuard<T extends Record<string, unknown>> = ZodObject<{
-  [key in keyof T]-?: ParseOptional<T[key]>;
-}>;
+export type CreateGuard<T extends Record<string, unknown>> = ZodObject<
+  {
+    [key in keyof T]-?: ParseOptional<T[key]>;
+  },
+  'strip',
+  ZodTypeAny,
+  T
+>;
 
-export type Guard<T extends Record<string, unknown>> = ZodObject<{
-  [key in keyof T]: ZodType<T[key]>;
-}>;
+export type Guard<T extends Record<string, unknown>> = ZodObject<
+  {
+    [key in keyof T]: ZodType<T[key]>;
+  },
+  'strip',
+  ZodTypeAny,
+  T
+>;
 
 export type GeneratedSchema<
   CreateSchema extends SchemaLike,

packages/schemas/src/gen/index.ts

@@ -12,12 +12,15 @@ import pluralize from 'pluralize';
 import { generateSchema } from './schema.js';
 import type { FileData, Table, Field, Type, GeneratedType, TableWithType } from './types.js';
 import {
+  type ParenthesesMatch,
   findFirstParentheses,
   normalizeWhitespaces,
   parseType,
   removeUnrecognizedComments,
   splitTableFieldDefinitions,
   stripLeadingJsDocComments as stripComments,
+  stripLeadingJsDocComments as stripLeadingJsDocumentComments,
+  getLeadingJsDocComments as getLeadingJsDocumentComments,
 } from './utils.js';
 
 const directory = 'tables';
@@ -50,14 +53,18 @@ const generate = async () => {
 
         // Parse Table statements
         const tables = statements
-          .filter((value) => value.toLowerCase().startsWith('create table'))
-          .map((value) => findFirstParentheses(value))
-          // eslint-disable-next-line unicorn/prefer-native-coercion-functions
-          .filter((value): value is NonNullable<typeof value> => Boolean(value))
-          .map<Table>(({ prefix, body }) => {
+          .filter((value) =>
+            stripLeadingJsDocumentComments(value).toLowerCase().startsWith('create table')
+          )
+          .map(
+            (value) => [findFirstParentheses(stripLeadingJsDocumentComments(value)), value] as const
+          )
+          .filter((value): value is NonNullable<[ParenthesesMatch, string]> => Boolean(value[0]))
+          .map<Table>(([{ prefix, body }, raw]) => {
             const name = normalizeWhitespaces(prefix).split(' ')[2];
             assert(name, 'Missing table name: ' + prefix);
 
+            const comments = getLeadingJsDocumentComments(raw);
             const fields = splitTableFieldDefinitions(body)
               .map((value) => normalizeWhitespaces(value))
               .filter((value) =>
@@ -70,7 +77,7 @@ const generate = async () => {
               )
               .map<Field>((value) => parseType(value));
 
-            return { name, fields };
+            return { name, comments, fields };
           });
 
         // Parse enum statements

packages/schemas/src/gen/schema.ts

@@ -1,23 +1,54 @@
 // LOG-88: Refactor '@logto/schemas' type gen
 
-import { conditionalString } from '@silverhand/essentials';
+import { condArray, condString, conditionalString } from '@silverhand/essentials';
 import camelcase from 'camelcase';
 import pluralize from 'pluralize';
 
 import type { TableWithType } from './types.js';
 
+const createTypeRemark = (originalType: string) => [
+  '',
+  '@remarks This is a type for database creation.',
+  '@see {@link ' + originalType + '} for the original type.',
+];
+
 // Tenant ID should be optional for create types since it'll be generated by the database trigger
 const tenantId = 'tenant_id';
 
-export const generateSchema = ({ name, fields }: TableWithType) => {
+type PrintCommentsOptions = {
+  tabSize?: number;
+  newLine?: boolean;
+};
+const printComments = (
+  comments?: string | string[],
+  { tabSize = 2, newLine = true }: PrintCommentsOptions = {}
+) =>
+  condString(
+    comments &&
+      condArray<string>(
+        ' '.repeat(tabSize),
+        Array.isArray(comments)
+          ? ['/**', ...comments.map((comment) => ` * ${comment}`), ' */'].join(
+              '\n' + ' '.repeat(tabSize)
+            )
+          : `/** ${comments} */`,
+        newLine && '\n'
+      ).join('')
+  );
+
+export const generateSchema = ({ name, comments, fields }: TableWithType) => {
   const modelName = pluralize(camelcase(name, { pascalCase: true }), 1);
   const databaseEntryType = `Create${modelName}`;
 
   return [
+    printComments([...condArray(comments), ...createTypeRemark(modelName)], {
+      tabSize: 0,
+      newLine: false,
+    }),
     `export type ${databaseEntryType} = {`,
     ...fields.map(
       ({ name, comments, type, isArray, nullable, hasDefaultValue }) =>
-        conditionalString(comments && `  /**${comments}*/\n`) +
+        printComments(comments) +
         `  ${camelcase(name)}${conditionalString(
           (nullable || hasDefaultValue || name === tenantId) && '?'
         )}: ${type}${conditionalString(isArray && '[]')}${conditionalString(
@@ -26,10 +57,11 @@ export const generateSchema = ({ name, fields }: TableWithType) => {
     ),
     '};',
     '',
+    printComments(comments, { tabSize: 0, newLine: false }),
     `export type ${modelName} = {`,
     ...fields.map(
       ({ name, comments, type, isArray, nullable, hasDefaultValue }) =>
-        conditionalString(comments && `  /**${comments}*/\n`) +
+        printComments(comments) +
         `  ${camelcase(name)}: ${type}${conditionalString(isArray && '[]')}${
           nullable && !hasDefaultValue ? ' | null' : ''
         };`

packages/schemas/src/gen/types.ts

@@ -26,11 +26,12 @@ export type GeneratedType = Type & {
 
 export type Table = {
   name: string;
+  /** The JSDoc comment for the table. */
+  comments?: string;
   fields: Field[];
 };
 
-export type TableWithType = {
-  name: string;
+export type TableWithType = Omit<Table, 'fields'> & {
   fields: FieldWithType[];
 };
 

packages/schemas/src/gen/utils.ts

@@ -7,14 +7,14 @@ export const normalizeWhitespaces = (string: string): string =>
   string.replaceAll(/\s+/g, ' ').trim();
 
 // eslint-disable-next-line unicorn/prevent-abbreviations -- JSDoc is a term
-const leadingJsDocRegex = /^\s*\/\*\*([^*]*?)\*\//;
+const leadingJsDocRegex = /^\s*\/\*\* *([^*]*?) *\*\//;
 
 // eslint-disable-next-line unicorn/prevent-abbreviations -- JSDoc is a term
 export const stripLeadingJsDocComments = (string: string): string =>
   string.replace(leadingJsDocRegex, '').trim();
 
 // eslint-disable-next-line unicorn/prevent-abbreviations -- JSDoc is a term
-const getLeadingJsDocComments = (string: string): Optional<string> =>
+export const getLeadingJsDocComments = (string: string): Optional<string> =>
   leadingJsDocRegex.exec(string)?.[1];
 
 // Remove all comments not start with @

packages/schemas/tables/organization_role_scope_relations.sql

@@ -0,0 +1,12 @@
+/* init_order = 2 */
+
+/** The relations between organization roles and organization scopes. It indicates which organization scopes are available to which organization roles. */
+create table organization_role_scope_relations (
+  tenant_id varchar(21) not null
+    references tenants (id) on update cascade on delete cascade,
+  organization_role_id varchar(21) not null
+    references organization_roles (id) on update cascade on delete cascade,
+  organization_scope_id varchar(21) not null
+    references organization_scopes (id) on update cascade on delete cascade,
+  primary key (tenant_id, organization_role_id, organization_scope_id)
+);

packages/schemas/tables/organization_role_user_relations.sql

@@ -0,0 +1,14 @@
+/* init_order = 2 */
+
+/** The relations between organizations, organization roles, and users. A relation means that a user has a role in an organization. */
+create table organization_role_user_relations (
+  tenant_id varchar(21) not null
+    references tenants (id) on update cascade on delete cascade,
+  organization_id varchar(21) not null
+    references organizations (id) on update cascade on delete cascade,
+  organization_role_id varchar(21) not null
+    references organization_roles (id) on update cascade on delete cascade,
+  user_id varchar(21) not null
+    references users (id) on update cascade on delete cascade,
+  primary key (tenant_id, organization_id, organization_role_id, user_id)
+);

packages/schemas/tables/organization_roles.sql

@@ -0,0 +1,19 @@
+/* init_order = 1 */
+
+/** The roles defined by the organization template. */
+create table organization_roles (
+  tenant_id varchar(21) not null
+    references tenants (id) on update cascade on delete cascade,
+  /** The globally unique identifier of the organization role. */
+  id varchar(21) not null,
+  /** The organization role's name, unique within the organization template. */
+  name varchar(128) not null,
+  /** A brief description of the organization role. */
+  description varchar(256),
+  primary key (id),
+  constraint organization_roles__name
+    unique (tenant_id, name)
+);
+
+create index organization_roles__id
+  on organization_roles (tenant_id, id);

packages/schemas/tables/organization_scopes.sql

@@ -0,0 +1,19 @@
+/* init_order = 1 */
+
+/** The scopes (permissions) defined by the organization template. */
+create table organization_scopes (
+  tenant_id varchar(21) not null
+    references tenants (id) on update cascade on delete cascade,
+  /** The globally unique identifier of the organization scope. */
+  id varchar(21) not null,
+  /** The organization scope's name, unique within the organization template. */
+  name varchar(128) not null,
+  /** A brief description of the organization scope. */
+  description varchar(256),
+  primary key (id),
+  constraint organization_scopes__name
+    unique (tenant_id, name)
+);
+
+create index organization_scopes__id
+  on organization_scopes (tenant_id, id);

packages/schemas/tables/organization_user_relations.sql

@@ -0,0 +1,12 @@
+/* init_order = 2 */
+
+/** The relations between organizations and users. It indicates membership of users in organizations. */
+create table organization_user_relations (
+  tenant_id varchar(21) not null
+    references tenants (id) on update cascade on delete cascade,
+  organization_id varchar(21) not null
+    references organizations (id) on update cascade on delete cascade,
+  user_id varchar(21) not null
+    references users (id) on update cascade on delete cascade,
+  primary key (tenant_id, organization_id, user_id)
+);

packages/schemas/tables/organizations.sql

@@ -0,0 +1,19 @@
+/* init_order = 1 */
+
+/** Organizations defined by [RFC 0001](https://github.com/logto-io/rfcs/blob/HEAD/active/0001-organization.md). */
+create table organizations (
+  tenant_id varchar(21) not null
+    references tenants (id) on update cascade on delete cascade,
+  /** The globally unique identifier of the organization. */
+  id varchar(21) not null,
+  /** The organization's name for display. */
+  name varchar(128) not null,
+  /** A brief description of the organization. */
+  description varchar(256),
+  /** When the organization was created. */
+  created_at timestamptz not null default(now()),
+  primary key (id)
+);
+
+create index organizations__id
+  on organizations (tenant_id, id);