@junobuild/functions 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Dal Busco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+[![npm][npm-badge]][npm-badge-url]
+[![license][npm-license]][npm-license-url]
+
+[npm-badge]: https://img.shields.io/npm/v/@junobuild/functions
+[npm-badge-url]: https://www.npmjs.com/package/@junobuild/functions
+[npm-license]: https://img.shields.io/npm/l/@junobuild/functions
+[npm-license-url]: https://github.com/junobuild/juno-js/blob/main/LICENSE
+
+# Juno Config
+
+JavaScript and TypeScript utilities for [Juno] Serverless Functions.
+
+<!-- TSDOC_START -->
+
+<!-- TSDOC_END -->
+
+## License
+
+MIT © [David Dal Busco](mailto:david.dalbusco@outlook.com)
+
+[juno]: https://juno.build

package/dist/browser/index.js

@@ -0,0 +1,2 @@
+import{jsonReplacer as t,jsonReviver as e}from"@dfinity/utils";var a=o=>JSON.parse(__juno_satellite_datastore_raw_data_to_text(o),e),p=o=>__juno_satellite_datastore_raw_data_from_text(JSON.stringify(o,t));export{a as decodeDocData,p as encodeDocData};
+//# sourceMappingURL=index.js.map

package/dist/browser/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/sdk/datastore.sdk.ts"],
+  "sourcesContent": ["import {jsonReplacer, jsonReviver} from '@dfinity/utils';\nimport type {RawData} from '../hooks/core';\n\nexport const decodeDocData = <T>(data: RawData): T =>\n  JSON.parse(__juno_satellite_datastore_raw_data_to_text(data), jsonReviver);\n\nexport const encodeDocData = <T>(data: T): RawData =>\n  __juno_satellite_datastore_raw_data_from_text(JSON.stringify(data, jsonReplacer));\n"],
+  "mappings": "AAAA,OAAQ,gBAAAA,EAAc,eAAAC,MAAkB,iBAGjC,IAAMC,EAAoBC,GAC/B,KAAK,MAAM,4CAA4CA,CAAI,EAAGF,CAAW,EAE9DG,EAAoBD,GAC/B,8CAA8C,KAAK,UAAUA,EAAMH,CAAY,CAAC",
+  "names": ["jsonReplacer", "jsonReviver", "decodeDocData", "data", "encodeDocData"]
+}

package/dist/index.js

@@ -0,0 +1 @@
+export * from './browser/index.js';

package/dist/types/configs/assert.config.d.ts

@@ -0,0 +1,30 @@
+import type { AssertSetDocContext } from '../hooks/context';
+import type { CollectionsConfig } from './collection.config';
+import type { SatelliteConfigEnv } from './satellite.config';
+/**
+ * The generic configuration for assertion hooks that manage collections.
+ */
+export interface AssertAssertConfig extends CollectionsConfig {
+    assertSetDoc: never;
+}
+/**
+ * A configuration object that includes the `assertSetDoc` function.
+ * This function is called to validate a document before it is created or updated.
+ */
+export interface AssertSetDocConfig extends Omit<AssertAssertConfig, 'assertSetDoc'> {
+    /**
+     * A function that runs synchronously before a document is set in the Datastore.
+     * This can be used to enforce your validation rules.
+     *
+     * @param {AssertSetDocContext} context - Provides details about the document being validated.
+     * @throws {Error} If your validation fails, throw an exception to prevent the document from being saved.
+     *
+     */
+    assertSetDoc: (context: AssertSetDocContext) => void;
+}
+export type AssertConfig = AssertSetDocConfig;
+export type AssertFn = (config: SatelliteConfigEnv) => AssertConfig;
+export type AssertFnOrObject = AssertConfig | AssertFn;
+export declare function defineAssert(config: AssertConfig): AssertConfig;
+export declare function defineAssert(config: AssertFn): AssertFn;
+export declare function defineAssert(config: AssertFnOrObject): AssertFnOrObject;

package/dist/types/configs/collection.config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Defines the collections where a hook or assertion should run.
+ */
+export interface CollectionsConfig {
+    /**
+     * A list of collection names where the hook or assertion will be executed.
+     */
+    collections: string[];
+}

package/dist/types/configs/hook.config.d.ts

@@ -0,0 +1,28 @@
+import type { OnSetDocContext } from '../hooks/context';
+import type { CollectionsConfig } from './collection.config';
+import type { SatelliteConfigEnv } from './satellite.config';
+/**
+ * The generic configuration for hooks that manage collections.
+ */
+export interface OnHookConfig extends CollectionsConfig {
+    onSetDoc: never;
+}
+/**
+ * A configuration object that includes the `onSetDoc` function.
+ * This function is called when a document is created or updated.
+ */
+export interface OnSetDocConfig extends Omit<OnHookConfig, 'onSetDoc'> {
+    /**
+     * A function that runs when a document is set in the Datastore.
+     *
+     * @param {OnSetDocContext} context - Provides details about the document being saved.
+     * @returns {Promise<void>} Resolves when your operation is complete.
+     */
+    onSetDoc: (context: OnSetDocContext) => Promise<void>;
+}
+export type HookConfig = OnSetDocConfig;
+export type HookFn = (config: SatelliteConfigEnv) => HookConfig;
+export type HookFnOrObject = HookConfig | HookFn;
+export declare function defineHook(config: HookConfig): HookConfig;
+export declare function defineHook(config: HookFn): HookFn;
+export declare function defineHook(config: HookFnOrObject): HookFnOrObject;

package/dist/types/configs/satellite.config.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Placeholder for future environment-specific configurations.
+ *
+ * Currently unused, but it may support features such as:
+ * - Defining the execution mode (e.g., staging or production).
+ * - Providing environment-specific values like `ckBtcLedgerId` for test or production.
+ */
+export type SatelliteConfigEnv = object;

package/dist/types/global.d.ts

@@ -0,0 +1,6 @@
+import type {RawData} from './hooks/core';
+
+declare global {
+  function __juno_satellite_datastore_raw_data_to_text(data: RawData): string;
+  function __juno_satellite_datastore_raw_data_from_text(data: string): RawData;
+}

package/dist/types/hooks/context.d.ts

@@ -0,0 +1,50 @@
+import type { RawUserId } from './core';
+import type { DocAssertSet, DocUpsert } from './datastore';
+/**
+ * Represents the context provided to hooks, containing information about the caller and related data.
+ *
+ * @template T - The type of data associated with the hook.
+ */
+export interface HookContext<T> {
+    /**
+     * The user who originally triggered the function that in turn triggered the hook.
+     */
+    caller: RawUserId;
+    /**
+     * The data associated with the hook execution.
+     */
+    data: T;
+}
+/**
+ * Represents the context of a document operation within a collection.
+ *
+ * @template T - The type of data associated with the document.
+ */
+export interface DocContext<T> {
+    /**
+     * The name of the collection where the document is stored.
+     */
+    collection: string;
+    /**
+     * The unique key identifying the document within the collection.
+     */
+    key: string;
+    /**
+     * The data associated with the document operation.
+     */
+    data: T;
+}
+/**
+ * The context provided to the `onSetDoc` hook.
+ *
+ * This context contains information about the document being created or updated,
+ * along with details about the user who triggered the operation.
+ */
+export type OnSetDocContext = HookContext<DocContext<DocUpsert>>;
+/**
+ * The context provided to the `assertSetDoc` hook.
+ *
+ * This context contains information about the document being validated before
+ * it is created or updated. If validation fails, the developer should throw an error.
+ */
+export type AssertSetDocContext = HookContext<DocContext<DocAssertSet>>;

package/dist/types/hooks/core.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Represents a timestamp in nanoseconds since the Unix epoch.
+ *
+ * Used for tracking when events occur, such as document creation and updates.
+ */
+export type Timestamp = bigint;
+/**
+ * Represents a version number for tracking changes.
+ *
+ * This is typically incremented with each update to ensure consistency.
+ */
+export type Version = bigint;
+/**
+ * Represents raw binary data.
+ *
+ * This is used to store unstructured data in a document.
+ */
+export type RawData = Uint8Array;
+/**
+ * Represents a raw principal identifier.
+ *
+ * Principals are unique identities used in authentication and authorization.
+ */
+export type RawPrincipal = Uint8Array;
+/**
+ * Represents a raw user identifier.
+ *
+ * This is a principal associated with a user.
+ */
+export type RawUserId = RawPrincipal;

package/dist/types/hooks/datastore.d.ts

@@ -0,0 +1,85 @@
+import type { RawData, RawUserId, Timestamp, Version } from './core';
+/**
+ * Represents a document update operation.
+ *
+ * This is used in hooks where a document is either being created or updated.
+ */
+export interface DocUpsert {
+    /**
+     * The previous version of the document before the update.
+     * Undefined if this is a new document.
+     */
+    before?: Doc;
+    /**
+     * The new version of the document after the update.
+     */
+    after: Doc;
+}
+/**
+ * Represents a validation check before setting a document.
+ *
+ * The developer can compare the `current` and `proposed` versions and
+ * throw an error if their validation fails.
+ */
+export interface DocAssertSet {
+    /**
+     * The current version of the document before the operation.
+     * Undefined if this is a new document.
+     */
+    current?: Doc;
+    /**
+     * The proposed version of the document.
+     * This can be validated before allowing the operation.
+     */
+    proposed: SetDoc;
+}
+/**
+ * Represents a document stored in a collection.
+ */
+export interface Doc {
+    /**
+     * The user who owns this document.
+     */
+    owner: RawUserId;
+    /**
+     * The raw data of the document.
+     */
+    data: RawData;
+    /**
+     * An optional description of the document.
+     */
+    description?: string;
+    /**
+     * The timestamp when the document was first created.
+     */
+    created_at: Timestamp;
+    /**
+     * The timestamp when the document was last updated.
+     */
+    updated_at: Timestamp;
+    /**
+     * The version number of the document, used for consistency checks.
+     * If not provided, it's assumed to be the first version.
+     */
+    version?: Version;
+}
+/**
+ * Represents a request to set or update a document.
+ *
+ * This is used when submitting new document data.
+ */
+export interface SetDoc {
+    /**
+     * The raw data of the document.
+     */
+    data: RawData;
+    /**
+     * An optional description of the document.
+     */
+    description?: string;
+    /**
+     * The expected version number to ensure consistency.
+     * If provided, the operation will fail if the stored version does not match.
+     */
+    version?: Version;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+export type * from './configs/assert.config';
+export type * from './configs/collection.config';
+export type * from './configs/hook.config';
+export type * from './configs/satellite.config';
+export type * from './hooks/context';
+export type * from './hooks/core';
+export type * from './hooks/datastore';
+export * from './sdk/datastore.sdk';

package/dist/types/sdk/datastore.sdk.d.ts

@@ -0,0 +1,3 @@
+import type { RawData } from '../hooks/core';
+export declare const decodeDocData: <T>(data: RawData) => T;
+export declare const encodeDocData: <T>(data: T) => RawData;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@junobuild/functions",
+  "version": "0.0.1",
+  "description": "JavaScript and TypeScript utilities for Juno Serverless Functions",
+  "author": "David Dal Busco (https://daviddalbusco.com)",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/browser/index.js",
+  "module": "./dist/browser/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/browser/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "rmdir": "node ../../scripts/rmdir.mjs",
+    "ts-declaration": "tsc --emitDeclarationOnly --outDir dist/types && cp -R src/*.d.ts dist/types/",
+    "build": "npm run rmdir && mkdir -p dist && node esbuild.mjs && npm run ts-declaration",
+    "prepack": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/junobuild/juno-js.git",
+    "directory": "packages/functions"
+  },
+  "bugs": {
+    "url": "https://github.com/junobuild/juno-js"
+  },
+  "homepage": "https://juno.build",
+  "peerDependencies": {
+    "@dfinity/utils": "^2"
+  }
+}