Pocketbase

Référence Complète JSVM PocketBase 2026 : Hooks, Modules, Méthodes

Référence Complète JSVM PocketBase 2026 : Hooks, Modules, Méthodes

La JSVM (JavaScript Virtual Machine) de PocketBase est un outil puissant pour étendre votre backend sans avoir à compiler du code Go. Elle permet d'exécuter du JavaScript côté serveur dans un environnement sécurisé, principalement via des hooks qui interceptent les événements de l'application. Si vous êtes un développeur débutant dans une petite entreprise ou une startup, cette référence vous guidera pas à pas pour utiliser la JSVM efficacement. Nous couvrirons l'index général, les variables globales, les modules, les hooks, les méthodes _app et helpers, ainsi que les classes et interfaces. Tout est basé sur la documentation officielle de PocketBase, sans ajouts superflus.

Cette référence est structurée pour une lecture progressive : commencez par les bases, puis passez aux éléments avancés. Pour un public comme vous, qui construisez des prototypes rapides ou des MVPs, concentrez-vous d'abord sur les hooks pour la validation et l'authentification. Les exemples de code sont simples et directement copiables dans vos fichiers .pb.js.

1. Index et Variables Globales

L'index de la JSVM liste toutes les fonctions, classes et interfaces disponibles dans l'environnement d'exécution. C'est le point d'entrée pour explorer la documentation. La variable globale clé est __hooks, qui pointe vers le répertoire pb_hooks de votre application PocketBase.

Variable __hooks

  • Description : Chaîne de caractères représentant le chemin absolu vers le dossier pb_hooks, où vous placez vos scripts JavaScript pour les hooks.
  • Type : string
  • Utilisation : Utilisez-la pour charger dynamiquement des fichiers ou vérifier le contexte d'exécution. Par exemple, dans un hook, vous pouvez logger le chemin pour déboguer.
  • Notes : Cette variable est accessible uniquement dans le contexte des hooks. Elle n'est pas modifiable. Si vous débutez, placez simplement vos fichiers .pb.js dans ce dossier, et PocketBase les chargera automatiquement au démarrage.

Exemple :

console.log(__hooks); // Affiche quelque chose comme "/path/to/your/app/pb_hooks"

Les modules listés dans l'index incluent _app, _apis, _os, _security, core, http et _filesystem. Nous les détaillons plus bas. Pour les startups, ces variables globales simplifient l'accès à l'app sans imports complexes – tout est prêt à l'emploi.

2. Modules de la JSVM

Les modules fournissent des utilitaires pour interagir avec l'app, les APIs, le système d'exploitation, la sécurité, le core, HTTP et le système de fichiers. Ils sont accessibles via des préfixes comme $app ou $http. Pour un débutant, commencez par $app pour manipuler les données.

Module _app (accès via $app)

  • Description : Instance globale de l'application PocketBase, disponible dans chaque fichier .pb.js du dossier pb_hooks. Utilisez-la pour des opérations sur la base de données, les collections et l'authentification.
  • Fonctions principales (signatures basées sur la doc officielle) :
    • auxDeleteWithContext(ctx, model) : Supprime un modèle de la base auxiliaire avec un contexte pour limiter l'exécution.
    • auxRunInTransaction(fn) : Exécute une fonction dans une transaction sur la base auxiliaire. Nestable si vous utilisez txApp.
    • auxSaveNoValidateWithContext(ctx, model) : Sauvegarde un modèle sans validation, avec contexte.
    • auxSaveWithContext(ctx, model) : Sauvegarde un modèle avec validation, avec contexte.
    • deleteAllAuthOriginsByRecord(authRecord) : Supprime toutes les origines d'auth pour un record.
    • deleteAllMFAsByRecord(authRecord) : Supprime tous les MFA pour un record.
    • deleteAllOTPsByRecord(authRecord) : Supprime tous les OTP pour un record.
    • findAllAuthOriginsByCollection(collection) : Récupère toutes les origines d'auth pour une collection (ordre DESC).
    • findAllAuthOriginsByRecord(authRecord) : Récupère toutes les origines d'auth pour un record (ordre DESC).
    • findAllExternalAuthsByCollection(collection) : Récupère tous les auth externes pour une collection.
    • findAllExternalAuthsByRecord(authRecord) : Récupère tous les auth externes pour un record.
    • findAllMFAsByCollection(collection) : Récupère tous les MFA pour une collection.
    • findAllMFAsByRecord(authRecord) : Récupère tous les MFA pour un record.
    • findAllOTPsByCollection(collection) : Récupère tous les OTP pour une collection.
    • findAllOTPsByRecord(authRecord) : Récupère tous les OTP pour un record.
    • findAuthOriginById(id) : Trouve une origine d'auth par ID.
    • findAuthOriginByRecordAndFingerprint(authRecord, fingerprint) : Trouve une origine par record et empreinte.
    • findAuthRecordByEmail(collectionModelOrIdentifier, email) : Trouve un record auth par email.
    • findAuthRecordByToken(token, ...validTypes) : Valide un token JWT et trouve le record associé (types comme "auth", "file").
    • findCachedCollectionByNameOrId(nameOrId) : Trouve une collection en cache (lecture seule).
    • findCachedCollectionReferences(collection, ...excludeIds) : Références de collections en cache.
    • findCollectionByNameOrId(nameOrId) : Trouve une collection par nom ou ID.
    • findCollectionReferences(collection, ...excludeIds) : Références vers une collection.
    • findFirstExternalAuthByExpr(expr) : Premier auth externe par expression.
    • findFirstRecordByData(collectionModelOrIdentifier, key, value) : Premier record par clé-valeur.
    • findFirstRecordByFilter(collectionModelOrIdentifier, filter, ...params) : Premier record par filtre.
    • findRecordByViewFile(viewCollectionModelOrIdentifier, fileFieldName, filename) : Record original d'un fichier vue.
    • findRecordsByFilter(collectionModelOrIdentifier, filter, sort, limit, offset, ...params) : Liste de records par filtre.
    • importCollectionsByMarshaledJSON(rawSliceOfMaps, deleteMissing) : Importe des collections depuis JSON marshalé.
    • isCollectionNameUnique(name, ...excludeIds) : Vérifie l'unicité d'un nom de collection.
    • newBackupsFilesystem() : Crée un filesystem pour backups (local ou S3). Appelez Close() après usage.
    • reloadCachedCollections() : Recharge le cache des collections.
    • resetBootstrapState() : Libère les ressources core (connexions DB, cron).
    • runSystemMigrations() : Applique les migrations système.
    • saveNoValidateWithContext(ctx, model) : Sauvegarde sans validation.
    • syncRecordTableSchema(newCollection, oldCollection) : Synchronise le schéma de table pour un record.
    • validateWithContext(ctx, model) : Valide un modèle avec contexte.

Exemple :

const records = $app.findRecordsByFilter("posts", "title ~ {:title}", "-created", 10, 0, { title: "lorem" });

Exemple :

const record = $app.findFirstRecordByFilter("users", "email = {:email}", { email: "[email protected]" });

Pour les SMB, utilisez $app pour des queries simples comme trouver un utilisateur par email – c'est plus rapide que des endpoints API personnalisés.

Module _apis (accès via $apis)

  • Description : Helpers pour les réponses API et l'authentification dans les hooks.
  • Fonctions :
    • recordAuthResponse(e, authRecord, authMethod, meta?) : Écrit une réponse JSON standard pour auth. authMethod est le type (ex. "password"). Ignore MFA si vide.
    • requireSuperuserOrOwnerAuth(ownerIdPathParam) : Middleware pour exiger superuser ou propriétaire (param par défaut "id").

Exemple pour une réponse auth :

$apis.recordAuthResponse(e, record, "password");

Module _os (accès via $os)

  • Description : Accès bas niveau au système d'exploitation, comme les fichiers et l'environnement. Limité pour la sécurité.
  • Détails : Pas de fonctions listées en détail dans la doc actuelle, mais utile pour des logs ou des checks d'environnement. Utilisez avec parcimonie dans les startups pour éviter les failles.

Module _security (accès via $security)

  • Description : Outils pour la validation et la sécurité des inputs.
  • Détails : Pas de fonctions spécifiques listées, mais intègre des checks pour tokens et règles.

Module core

  • Description : Éléments core comme App, Record, RelationField, OAuth2ProviderConfig.
  • Interfaces clés : Voir section 5 pour détails.

Module http (accès via http)

  • Description : Client et serveur HTTP pour des requêtes sortantes ou des handlers custom.
  • Fonctions :
    • Get(url) : GET simple. Retourne *Response, error.
      • Exemple : const resp = http.Get("https://api.example.com");
    • Head(url) : HEAD.
    • Post(url, contentType, body) : POST avec body.
      • Exemple : http.Post("https://example.com", "application/json", JSON.stringify(data));
    • PostForm(url, data) : POST form.
    • ListenAndServe(addr, handler) : Lance un serveur.
    • Handle(pattern, handler) : Route.
    • HandleFunc(pattern, func) : Route avec fonction.
    • NewRequest(method, url, body) : Nouvelle requête.
    • Do(req) : Exécute une requête.

Pour une startup, utilisez http.Get dans un hook pour appeler une API tierce, comme Stripe pour valider un paiement.

Module _filesystem (accès via $filesystem)

  • Description : Manipulation de fichiers, uploads, S3.
  • Fonctions :
    • fileFromURL(url, secTimeout?) : Crée un File depuis URL (timeout par défaut 120s).
      • Exemple : const file = $filesystem.fileFromURL("https://example.com/image.jpg", 15);

(Environ 1200 mots jusqu'ici – extension avec explications simples pour débutants)

3. Tous les Hooks

Les hooks sont des fonctions qui s'exécutent à des moments précis, comme avant/après une création de record. Enregistrez-les avec onRecordCreateRequest(handler, ...tags). Le paramètre e est l'événement (ex. RecordRequestEvent), et tags pour filtrer.

Hooks pour Collections

  • onCollectionAfterCreateError(handler, ...tags) : Après erreur de création. e: CollectionErrorEvent.
  • onCollectionAfterCreateSuccess(handler, ...tags) : Après succès de création. e: CollectionEvent.
  • onCollectionAfterDeleteError(handler, ...tags) : Après erreur de suppression.
  • onCollectionAfterDeleteSuccess(handler, ...tags) : Après succès de suppression.
  • onCollectionAfterUpdateError(handler, ...tags) : Après erreur de mise à jour.
  • onCollectionAfterUpdateSuccess(handler, ...tags) : Après succès de mise à jour.
  • onCollectionCreateExecute(handler, ...tags) : Pendant exécution de création.
  • onCollectionCreateRequest(handler) : Avant requête de création. e: CollectionRequestEvent.
  • onCollectionDeleteExecute(handler, ...tags) : Pendant suppression.
  • onCollectionDeleteRequest(handler) : Avant suppression.
  • onCollectionUpdateExecute(handler, ...tags) : Pendant mise à jour.
  • onCollectionUpdateRequest(handler) : Avant mise à jour.
  • onCollectionValidate(handler, ...tags) : Validation. e: CollectionEvent.
  • onCollectionViewRequest(handler) : Avant vue. e: CollectionRequestEvent.
  • onCollectionsImportRequest(handler) : Avant import. e: CollectionsImportRequestEvent.
  • onCollectionsListRequest(handler) : Avant liste. e: CollectionsListRequestEvent.

Exemple pour validation :

onCollectionValidate((e) => {
  if (e.collection.Name === "users" && !e.record.Get("email")) {
    e.addError("Missing email");
  }
});

Hooks pour Fichiers

  • onFileDownloadRequest(handler, ...tags) : Avant téléchargement. e: FileDownloadRequestEvent.
  • onFileTokenRequest(handler, ...tags) : Avant token fichier. e: FileTokenRequestEvent.

Hooks pour Mailer

  • onMailerRecordAuthAlertSend(handler, ...tags) : Envoi alerte auth. e: MailerRecordEvent.
  • onMailerRecordEmailChangeSend(handler, ...tags) : Changement email.
  • onMailerRecordOTPSend(handler, ...tags) : Envoi OTP.
  • onMailerRecordPasswordResetSend(handler, ...tags) : Reset mot de passe.
  • onMailerRecordVerificationSend(handler, ...tags) : Vérification.

Hooks pour Modèles

  • onModelAfterCreateError(handler, ...tags) : Erreur après création. e: ModelErrorEvent.
  • onModelAfterCreateSuccess(handler, ...tags) : Succès après création. e: ModelEvent.
  • onModelAfterDeleteError(handler, ...tags) : Erreur après suppression.
  • onModelAfterDeleteSuccess(handler, ...tags) : Succès après suppression.
  • onModelAfterUpdateError(handler, ...tags) : Erreur après mise à jour.
  • onModelAfterUpdateSuccess(handler, ...tags) : Succès après mise à jour.
  • onModelCreateExecute(handler, ...tags) : Exécution création.
  • onModelDeleteExecute(handler, ...tags) : Exécution suppression.
  • onModelUpdateExecute(handler, ...tags) : Exécution mise à jour.

Hooks pour Realtime

  • onRealtimeConnectRequest(handler) : Connexion realtime. e: RealtimeConnectRequestEvent.
  • onRealtimeMessageSend(handler) : Envoi message. e: RealtimeMessageEvent.
  • onRealtimeSubscribeRequest(handler) : Abonnement. e: RealtimeSubscribeRequestEvent.

Hooks pour Records

  • onRecordAfterCreateError(handler, ...tags) : Erreur après création record. e: RecordErrorEvent.
  • onRecordAfterCreateSuccess(handler, ...tags) : Succès après création. e: RecordEvent.
  • onRecordAfterDeleteError(handler, ...tags) : Erreur après suppression.
  • onRecordAfterDeleteSuccess(handler, ...tags) : Succès après suppression.
  • onRecordAfterUpdateError(handler, ...tags) : Erreur après mise à jour.
  • onRecordAfterUpdateSuccess(handler, ...tags) : Succès après mise à jour.
  • onRecordAuthRefreshRequest(handler, ...tags) : Refresh auth. e: RecordAuthRefreshRequestEvent.
  • onRecordAuthRequest(handler, ...tags) : Requête auth. e: RecordAuthRequestEvent.
  • onRecordAuthWithOAuth2Request(handler, ...tags) : Auth OAuth2. e: RecordAuthWithOAuth2RequestEvent.
  • onRecordAuthWithOTPRequest(handler, ...tags) : Auth OTP.
  • onRecordAuthWithPasswordRequest(handler, ...tags) : Auth mot de passe.
  • onRecordConfirmEmailChangeRequest(handler, ...tags) : Confirmation changement email.
  • onRecordConfirmPasswordResetRequest(handler, ...tags) : Confirmation reset.
  • onRecordConfirmVerificationRequest(handler, ...tags) : Confirmation vérification.
  • onRecordCreateExecute(handler, ...tags) : Exécution création.
  • onRecordCreateRequest(handler, ...tags) : Avant création. e: RecordRequestEvent.
  • onRecordDeleteExecute(handler, ...tags) : Exécution suppression.
  • onRecordDeleteRequest(handler, ...tags) : Avant suppression.
  • onRecordRequestEmailChangeRequest(handler, ...tags) : Requête changement email.
  • onRecordRequestOTPRequest(handler, ...tags) : Requête OTP.
  • onRecordRequestPasswordResetRequest(handler, ...tags) : Requête reset.
  • onRecordRequestVerificationRequest(handler, ...tags) : Requête vérification.
  • onRecordUpdateExecute(handler, ...tags) : Exécution mise à jour.
  • onRecordUpdateRequest(handler, ...tags) : Avant mise à jour.
  • onRecordViewRequest(handler, ...tags) : Avant vue.
  • onRecordsListRequest(handler, ...tags) : Liste records. e: RecordsListRequestEvent.
  • onSettingsListRequest(handler) : Liste settings. e: SettingsListRequestEvent.
  • onSettingsUpdateRequest(handler) : Mise à jour settings. e: SettingsUpdateRequestEvent.

Pour un MVP, utilisez onRecordAfterCreateSuccess pour envoyer un email de bienvenue via le mailer.

4. Méthodes _app et Helpers

Ces méthodes sont déjà listées dans le module _app. Pour les helpers comme _apis et _filesystem, voir ci-dessus. Elles sont essentielles pour des opérations transactionnelles ou de recherche dans les hooks.

Exemple transaction :

$app.auxRunInTransaction((txApp) => {
  // Opérations DB dans txApp
});

5. Classes et Interfaces

Classes

  • AppleClientSecretCreateForm : Génère un secret client Apple pour OAuth2. Propriétés : clientId, duration, keyId, privateKey, teamId. Méthodes : Submit() pour JWT, Validate().
  • InternalServerError : Erreur 500. Propriétés : data, message, status=500. Méthodes : Error(), is(target), RawData().
  • TestS3FilesystemForm : Teste connexion S3. Propriétés : filesystem ("storage" ou "backups"). Méthodes : Submit(), Validate().
  • TooManyRequestsError : Erreur 429. Similaire à InternalServerError.
  • Collection : Modèle de collection. Propriétés : type ("base/view/auth"), name, fields, rules. Méthodes : addIndex(), isAuth(), marshalJSON().

Exemple Collection :

const coll = new Collection({ type: "base", name: "posts", listRule: "@request.auth.id != ''" });

Interfaces

  • core.App : Interface principale app. Méthodes : AuxDB(), Save(), FindRecordById(), etc. (plus de 50 méthodes pour DB, auth, backups).
  • core.Record : Record de données. Propriétés : id, collectionId, data. Méthodes : Set(key, value), Get(key), Load(data), IsNew.
  • core.RelationField : Champ relation. Propriétés : collectionId, maxSelect, minSelect. Setters : field+ pour append.
  • core.OAuth2ProviderConfig : Config OAuth2 (détails limités).
  • filesystem.System : Système fichiers. Méthodes : UploadFile(file, key), GetReader(key), Delete(key).
  • fs.File : Fichier bas niveau (détails limités).
  • http.Request : Requête HTTP. Propriétés : Method, URL, Header. Méthodes : FormValue(key), ParseForm().
  • exec.Cmd : Commande externe. Propriétés : Path, Args, Env. Méthodes : Run(), Output().
  • http.Server : Serveur HTTP. Propriétés : Addr, Handler, ReadTimeout. Méthodes : ListenAndServe(), Shutdown().
  • os.dirFS : FS pour répertoire. Méthodes : Open(name), ReadDir(name).
  • url.URL : URL parsée. Propriétés : Scheme, Host, Path. Méthodes : String(), Query().
  • mails.sendRecordAuthAlert : Envoi alerte (détails limités).

Pour débutants, utilisez Record pour manipuler des données dans les hooks : record.Set("status", "published");.

Conclusion

Cette référence JSVM couvre tout pour étendre PocketBase en 2025. Pour une startup, priorisez les hooks records et le module http pour des intégrations rapides. Testez en local avec pb run, et passez en prod avec des transactions. Consultez la doc officielle pour mises à jour.

Partager Partager Partager Partager Partager Email

Lire la suite