@withstudiocms/kysely

v0.2.1 GitHub npm Journal des modifications

Kysely (https://kysely.dev/^) est un générateur de requêtes SQL avec sûreté du typage pour TypeScript. Il offre une méthode puissante et flexible pour interagir avec les bases de données, tout en garantissant la sûreté du typage et en réduisant les erreurs d’exécution. Kysely prend en charge diverses bases de données SQL, notamment PostgreSQL, MySQL, SQLite et bien d’autres. Il permet aux développeurs de construire des requêtes SQL à l’aide d’une API fluide, simplifiant ainsi la lecture et la maintenance des interactions avec la base de données dans les applications TypeScript.

Actuellement, StudioCMS prend uniquement en charge les bases de données libSQL (SQLite), MySQL et PostgreSQL via Kysely. À l’avenir, la prise en charge d’autres dialectes de bases de données pourra être ajoutée selon les besoins ou sur demande.

Vous souhaitez qu’un autre dialecte de base de données soit pris en charge ? Consultez la documentation de Kysely sur les dialectes^ et ouvrez un ticket sur le dépôt GitHub de StudioCMS^.

Le paquet client de Kysely

Un client de base de données offrant la sûreté du typage et un système de migration pour StudioCMS, basé sur Kysely^. Il fournit une interface unifiée pour travailler avec les bases de données libSQL, MySQL et PostgreSQL avec gestion des schémas de l’environnement d’exécution et des migrations.

Fonctionnalités

Opérations de base de données avec sûreté du typage - Prise en charge complète de TypeScript grâce au générateur de requêtes avec sûreté du typage de Kysely
Compatible avec plusieurs bases de données - Fonctionne avec libSQL (SQLite), MySQL et PostgreSQL
Gestion des schémas de l’environnement d’exécution - Création et validation de schémas dynamiques
Gestion des erreurs - Types d’erreurs personnalisés pour un meilleur débogage
Migrations reposant sur TypeScript - Migrations reposant sur des fichiers avec suivi automatique
Introspection des schémas - Inspecter et valider les schémas de base de données lors de l’exécution
Intégration avec Effect-ts - Modèles de programmation fonctionnelle avec Effect-ts

Exemple de code

Configuration de base du client

import { getDBClientLive } from '@withstudiocms/kysely';
import type { StudioCMSDatabaseSchema } from '@withstudiocms/sdk/tables';
import { libsqlDriver } from '@withstudiocms/kysely/drivers/libsql';
import { ConfigProvider, Effect } from 'studiocms/effect';

export const getDbClient = Effect.gen(function* () {
  // Configurez le pilote LibSQL avec une URL de base de données à partir de la configuration.
  const dialect = yield* libsqlDriver.pipe(
    Effect.withConfigProvider(
      ConfigProvider.fromJson({
        CMS_LIBSQL_URL: 'file:./test.db',
      })
    )
  );

  // Renvoyez le client DB de Kysely avec les utilitaires d'Effect
  return yield* getDBClientLive<StudioCMSDatabaseSchema>(dialect);
});

Exemple pour obtenir les utilisateurs

import { getDBClientLive } from '@withstudiocms/kysely';
import type { StudioCMSDatabaseSchema } from '@withstudiocms/sdk/tables';
import { libsqlDriver } from '@withstudiocms/kysely/drivers/libsql';
import { ConfigProvider, Effect } from 'studiocms/effect';

export const getDbClient = Effect.gen(function* () {
  // Configurez le pilote LibSQL avec une URL de base de données à partir de la configuration.
  const dialect = yield* libsqlDriver.pipe(
    Effect.withConfigProvider(
      ConfigProvider.fromJson({
        CMS_LIBSQL_URL: 'file:./test.db',
      })
    )
  );

  // Renvoyez le client DB de Kysely avec les utilitaires d'Effect
  return yield* getDBClientLive<StudioCMSDatabaseSchema>(dialect);
});
// ---cut---
import { Schema } from 'studiocms/effect';
import { StudioCMSUsersTable } from '@withstudiocms/sdk/tables';

export const getUsers = Effect.gen(function* () {
    const { withDecoder } = yield* getDbClient;

  const getUsers = withDecoder({
    decoder: Schema.Array(StudioCMSUsersTable.Select),
    callbackFn: (db) =>
      db((client) =>
        client.selectFrom('StudioCMSUsersTable')
        .selectAll()
        .execute()
      ),
  });

  const users = yield* getUsers();
//        ^?

  console.log('Users:', users);
});

Exemple pour insérer un nouvel utilisateur (`withEncoder`)

import { getDBClientLive } from '@withstudiocms/kysely';
import type { StudioCMSDatabaseSchema } from '@withstudiocms/sdk/tables';
import { libsqlDriver } from '@withstudiocms/kysely/drivers/libsql';
import { ConfigProvider, Effect } from 'studiocms/effect';

export const getDbClient = Effect.gen(function* () {
  // Configurez le pilote LibSQL avec une URL de base de données à partir de la configuration.
  const dialect = yield* libsqlDriver.pipe(
    Effect.withConfigProvider(
      ConfigProvider.fromJson({
        CMS_LIBSQL_URL: 'file:./test.db',
      })
    )
  );

  // Renvoyez le client DB de Kysely avec les utilitaires d'Effect
  return yield* getDBClientLive<StudioCMSDatabaseSchema>(dialect);
});
// ---cut---
import { Schema } from 'studiocms/effect';
import { StudioCMSUsersTable } from '@withstudiocms/sdk/tables';

export const insertUser = Effect.gen(function* () {
    const { withEncoder } = yield* getDbClient;

  const insertUser = withEncoder({
    encoder: StudioCMSUsersTable.Insert,
    callbackFn: (db, newUser) =>
      db((client) =>
        client.insertInto('StudioCMSUsersTable')
        .values(newUser)
        .executeTakeFirst()
      ),
  });

  const data = {
    username: 'nouvel_utilisateur',
    email: '[email protected]',
    password: null,
    avatar: null,
    emailVerified: false,
    name: 'utilisateur',
    notifications: '',
    url: null,
    id: crypto.randomUUID(),
    updatedAt: new Date().toISOString(),
    createdAt: new Date().toISOString(),
  };

  const newUser = yield* insertUser(data);
//        ^?
  console.log('Nouvel utilisateur ajouté :', newUser);
});

Exemple pour insérer un nouvel utilisateur (`withCodec`)

import { getDBClientLive } from '@withstudiocms/kysely';
import type { StudioCMSDatabaseSchema } from '@withstudiocms/sdk/tables';
import { libsqlDriver } from '@withstudiocms/kysely/drivers/libsql';
import { ConfigProvider, Effect } from 'studiocms/effect';

export const getDbClient = Effect.gen(function* () {
  // Configurez le pilote LibSQL avec une URL de base de données à partir de la configuration.
  const dialect = yield* libsqlDriver.pipe(
    Effect.withConfigProvider(
      ConfigProvider.fromJson({
        CMS_LIBSQL_URL: 'file:./test.db',
      })
    )
  );

  // Renvoyez le client DB de Kysely avec les utilitaires d'Effect
  return yield* getDBClientLive<StudioCMSDatabaseSchema>(dialect);
});
// ---cut---
import { Schema } from 'studiocms/effect';
import { StudioCMSUsersTable } from '@withstudiocms/sdk/tables';

export const insertUser = Effect.gen(function* () {
    const { withCodec } = yield* getDbClient;

  const insertNewUser = withCodec({
    encoder: StudioCMSUsersTable.Insert,
    decoder: StudioCMSUsersTable.Select,
    callbackFn: (db, newUser) =>
      db((client) =>
        client
          .insertInto('StudioCMSUsersTable')
          .values(newUser)
          .returningAll()
          .executeTakeFirstOrThrow()
      ),
  });

  const data = {
    username: 'utilisateur_codec',
    email: '[email protected]',
    password: null,
    avatar: null,
    emailVerified: false,
    name: 'utilisateur',
    notifications: '',
    url: null,
    id: crypto.randomUUID(),
    updatedAt: new Date().toISOString(),
    createdAt: new Date().toISOString(),
  };

  const insertedUser = yield* insertNewUser(data);
//        ^?
  console.log('Utilisateur ajouté avec codec :', insertedUser);
});

Exemple de récupération d’un utilisateur par son ID

import { getDBClientLive } from '@withstudiocms/kysely';
import type { StudioCMSDatabaseSchema } from '@withstudiocms/sdk/tables';
import { libsqlDriver } from '@withstudiocms/kysely/drivers/libsql';
import { ConfigProvider, Effect } from 'studiocms/effect';

export const getDbClient = Effect.gen(function* () {
  // Configurez le pilote LibSQL avec une URL de base de données à partir de la configuration.
  const dialect = yield* libsqlDriver.pipe(
    Effect.withConfigProvider(
      ConfigProvider.fromJson({
        CMS_LIBSQL_URL: 'file:./test.db',
      })
    )
  );

  // Renvoyez le client DB de Kysely avec les utilitaires d'Effect
  return yield* getDBClientLive<StudioCMSDatabaseSchema>(dialect);
});
// ---cut---
import { Schema } from 'studiocms/effect';
import { StudioCMSUsersTable } from '@withstudiocms/sdk/tables';

export const insertUser = Effect.gen(function* () {
    const { withCodec } = yield* getDbClient;

  const getUserById = withCodec({
    encoder: Schema.String,
    decoder: Schema.UndefinedOr(StudioCMSUsersTable.Select),
    callbackFn: (db, id) =>
      db((client) =>
        client.selectFrom('StudioCMSUsersTable')
        .selectAll()
        .where('id', '=', id)
        .executeTakeFirst()
      ),
  });

  const user = yield* getUserById('un-identifiant-utilisateur');
//        ^?
  console.log('Utilisateur par identifiant :', user);
});

Lectures complémentaires

Pour plus d’informations sur la façon dont StudioCMS utilise Kysely en interne, consultez la documentation du SDK pour apprendre comment l’utiliser dans votre projet StudioCMS !