Jinaga

https://jinaga.com/documents/
Admin
Jinaga is a data management framework for building offline-first mobile, web, and distributed...
Tokens:26,158
Snippets:261
Trust Score:6.7
Update:11 months ago
Show doc for...
Tokens:
Raw
### Create React App with TypeScript Template

Source: https://jinaga.com/documents/create-an-app/create-react-app

Initializes a new React application using Create React App with the TypeScript template. This is the recommended setup for Jinaga. Ensure Node.js is installed and running in WSL on Windows.

```bash
npx create-react-app my-application --template typescript
```

--------------------------------

### Setup PostgreSQL for Jinaga Replicator with Docker

Source: https://jinaga.com/documents/replicator

These Docker commands pull a pre-configured PostgreSQL image for Jinaga facts, create a container named 'jinaga-postgres' listening on port 5432, and start it. Environment variables are used to set up database credentials and names. This is for users who prefer to run their own PostgreSQL instance.

```bash
docker pull jinaga/jinaga-postgres-fact-keystore
docker create --name jinaga-postgres -p5432:5432 \
  -e POSTGRES_PASSWORD=secretpw \
  -e APP_USERNAME=appuser \
  -e APP_PASSWORD=apppw \
  -e APP_DATABASE=appdb \
  jinaga/jinaga-postgres-fact-keystore
docker start jinaga-postgres
```

--------------------------------

### Start React Application

Source: https://jinaga.com/documents/create-an-app/create-react-app

Starts the React development server from within the VS Code terminal. This command compiles and serves the React application, making it accessible for development.

```bash
npm start
```

--------------------------------

### Install Jinaga Packages with npm

Source: https://jinaga.com/documents/create-an-app/install-jinaga

Installs the necessary Jinaga packages for a project using npm. This includes the core Jinaga library and the React integration.

```bash
npm install jinaga jinaga-react
```

--------------------------------

### Factual File Example for Blog Site

Source: https://jinaga.com/documents/exporting-facts/factual-file-format

Illustrates a practical example of the Factual file format, demonstrating the declaration of a blog site, a blog post, and its title. This example shows the syntax for fields and single/array predecessors.

```javascript
let f1: Blog.Site = {
    domain: "example.com"
}

let f2: Blog.Post = {
    createdAt: "2023-05-20T10:30:00Z",
    site: f1
}

let f3: Blog.Post.Title = {
    post: f2,
    value: "My First Blog Post",
    prior: []
}
```

--------------------------------

### Jinaga Specification Language Example

Source: https://jinaga.com/documents/replicator/read

An example of a Jinaga specification to read blog posts. It defines input facts, a specification body to filter posts, and projections to shape the output.

```jinaga
let site: Blog.Site = {
    domain: "qedcode.com"
}

(site: Blog.Site) {
    post: Blog.Post [
        post->site: Blog.Site = site
        !E {
            deleted: Blog.Post.Deleted [
                deleted->post: Blog.Post = post
            ]
        }
    ]
} => {
    id = #post
    createdAt = post.createdAt
    titles = {
        title: Blog.Post.Title [
            title->post: Blog.Post = post
            !E {
                next: Blog.Post.Title [
                    next->prior: Blog.Post.Title = title
                ]
            }
        ]
    } => title.value
}
```

--------------------------------

### Install and Configure Jinaga Server in Node.js

Source: https://jinaga.com/documents/replicator

This Node.js code snippet demonstrates how to install the 'jinaga-server' package, set up an Express application, and create a JinagaServer instance. It configures the server to use a PostgreSQL connection and listen on port 8080, making the replicator ready to receive requests at '/jinaga'.

```typescript
import express = require("express");
import * as http from "http";
import { JinagaServer } from "jinaga-server";
import process = require("process");

process.on('SIGINT', () => {
  console.log("\n\nStopping replicator\n");
  process.exit(0);
});

const app = express();
const server = http.createServer(app);

app.set('port', process.env.PORT || 8080);
app.use(express.json());
app.use(express.text());

const pgConnection = process.env.JINAGA_POSTGRESQL ||
  'postgresql://appuser:apppw@localhost:5432/appdb';
const { handler } = JinagaServer.create({
  pgStore: pgConnection
});

app.use('/jinaga', handler);

server.listen(app.get('port'), () => {
  console.log(`  Replicator is running at http://localhost:${app.get('port')} in ${app.get('env')} mode`);
  console.log('  Press CTRL-C to stop\n');
});
```

--------------------------------

### Install jinaga-export-postgres globally using npm

Source: https://jinaga.com/documents/exporting-facts/exporting-from-postgres

This command installs the jinaga-export-postgres command-line tool globally on your system, making it accessible from any terminal location. Ensure you have npm installed and configured.

```bash
npm install -g jinaga-export-postgres
```

--------------------------------

### Start New Jinaga Replicator Container with New Volume

Source: https://jinaga.com/documents/replicator/upgrading

This sequence pulls the latest Jinaga replicator image, creates a new container named 'my-replicator', maps port 8080, and mounts the 'my-replicator-db' volume to '/var/lib/postgresql/data'. Finally, it starts the newly created container.

```bash
docker pull jinaga/jinaga-replicator:latest
docker create --name my-replicator \
  -p8080:8080 \
  -v my-replicator-db:/var/lib/postgresql/data \
  jinaga/jinaga-replicator
docker start my-replicator
```

--------------------------------

### Initialize Jinaga Client in TypeScript

Source: https://jinaga.com/documents/create-an-app/install-jinaga

Initializes a Jinaga client instance using the JinagaBrowser provider. It reads the Replicator URL from environment variables. This is suitable for browser or React Native applications.

```typescript
import { JinagaBrowser } from "jinaga";

export const j = JinagaBrowser.create({
    httpEndpoint: process.env.REACT_APP_JINAGA_REPLICATOR_URL,
});
```

--------------------------------

### Jinaga Fact Language Example

Source: https://jinaga.com/documents/replicator/write

An example demonstrating how to declare facts, including a site, a blog post, and its titles, using the Jinaga fact language. It shows the structure for defining fact types and their fields, including predecessors and arrays.

```jinaga-fact-language
let site: Blog.Site = {
    domain: "qedcode.com"
}

let post: Blog.Post = {
    createdAt: "2022-08-16T15:23:13.231Z",
    site
}

let title: Blog.Post.Title = {
    post,
    value: "Introducing Jinaga Replicator",
    prior: []
}
let title2: Blog.Post.Title = {
    post,
    value: "Introduction to the Jinaga Replicator",
    prior: [ title ]
}
```

--------------------------------

### Create Jinaga Site Object

Source: https://jinaga.com/documents/create-an-app/initialize-a-starting-point

This TypeScript function demonstrates how to create a 'Site' fact using the Jinaga instance 'j'. It assumes 'Site' is defined in './model/blog' and 'j' is imported from './jinaga-config'. The function returns the created 'Site' object.

```typescript
import { j } from "./jinaga-config";
import { Site } from "./model/blog";

async function makeSite() {
  const site = await j.fact(new Site("qedcode.com"));
  return site;
}
```

--------------------------------

### Configure Jinaga Replicator URL in .env

Source: https://jinaga.com/documents/create-an-app/install-jinaga

Sets the Jinaga Replicator URL in a .env file. This environment variable is used by the Jinaga client to establish a connection to the specified Replicator endpoint.

```env
REACT_APP_JINAGA_REPLICATOR_URL=https://rep.jinaga.com/xyz123....
```

--------------------------------

### Manage Site State in React Component

Source: https://jinaga.com/documents/create-an-app/initialize-a-starting-point

This React component code snippet shows how to initialize and manage the 'Site' object state. It uses React's useState and useEffect hooks to fetch the site data when the component mounts. The 'makeSite' function is called once to populate the state.

```javascript
function App() {
  const [ site, setSite ] = React.useState<Site | null>(null);
  React.useEffect(() => {
    makeSite().then(setSite);
  }, [ setSite ]);

  // ...
}
```

--------------------------------

### Jinaga Projection Example

Source: https://jinaga.com/documents/replicator/read

Demonstrates a simple Jinaga projection to select specific fields from matching facts, reshaping the output of a specification.

```jinaga
=> {
    id = #post
    createdAt = post.createdAt
}
```

--------------------------------

### Command-Line Execution for Deployment

Source: https://jinaga.com/documents/replicator/authorization

Example of how to run the NPM script to deploy authorization rules. It passes the replicator's authorization endpoint and a secret token as command-line arguments to the `deploy:authorization` script.

```bash
npm run deploy:authorization https://rep.jinaga.com/xxxxxxx/authorization yyyyyyy
```

--------------------------------

### Example Jinaga Facts in JSON

Source: https://jinaga.com/documents/exporting-facts/json-file-format

An example of a JSON array containing multiple Jinaga fact objects, illustrating the structure for 'Blog.Site', 'Blog.Post', and 'Blog.Post.Title' types.

```json
[
  {
    "hash": "SV3Yseb0FJ/uQoL4IelHHbo1g4PZjnP4bx+aivMiiCkSTn2vSaNR6314KXL+PgO9lX9jmJzWoZABTRHjiFHWdQ==",
    "type": "Blog.Site",
    "predecessors": {},
    "fields": {
      "domain": "example.com"
    }
  },
  {
    "hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
    "type": "Blog.Post",
    "predecessors": {
      "site": {
        "hash": "SV3Yseb0FJ/uQoL4IelHHbo1g4PZjnP4bx+aivMiiCkSTn2vSaNR6314KXL+PgO9lX9jmJzWoZABTRHjiFHWdQ==",
        "type": "Blog.Site"
      }
    },
    "fields": {
      "createdAt": "2023-05-20T10:30:00Z"
    }
  },
  {
    "hash": "z6y5x4w3v2u1t0s9r8q7p6o5n4m3l2k1j0i9h8g7f6e5d4c3b2a1",
    "type": "Blog.Post.Title",
    "predecessors": {
      "post": {
        "hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
        "type": "Blog.Post"
      }
    },
    "fields": {
      "value": "My First Blog Post",
      "prior": []
    }
  }
]
```

--------------------------------

### Deploy Jinaga Replicator with Docker

Source: https://jinaga.com/documents/replicator

These Docker commands pull the Jinaga Replicator image, create a container named 'my-replicator' listening on port 8080, and start the container. This method is suitable for deploying replicators on your own infrastructure.

```bash
docker pull jinaga/jinaga-replicator
docker create --name my-replicator -p8080:8080 jinaga/jinaga-replicator
docker start my-replicator
```

--------------------------------

### Jinaga Fact Declaration Example

Source: https://jinaga.com/documents/replicator/read

Example of declaring a fact in Jinaga, similar to how it would be used for the /write endpoint. This fact serves as a parameter for a specification.

```jinaga
let site: Blog.Site = {
    domain: "qedcode.com"
}
```

--------------------------------

### Jinaga Specification Body Example

Source: https://jinaga.com/documents/replicator/read

Illustrates the specification body in Jinaga, which defines how to match facts based on their relationships. It shows path conditions and existential conditions.

```jinaga
post: Blog.Post [
    post->site: Blog.Site = site
    !E {
        deleted: Blog.Post.Deleted [
            deleted->post: Blog.Post = post
        ]
    }
]
```

--------------------------------

### Jinaga Nested Projection Example

Source: https://jinaga.com/documents/replicator/read

Shows how to use nested specifications within a Jinaga projection to retrieve related data and structure complex results.

```jinaga
titles = {
    title: Blog.Post.Title [
        title->post: Blog.Post = post
        !E {
            next: Blog.Post.Title [
                next->prior: Blog.Post.Title = title
            ]
        }
    ]
} => title.value
```

--------------------------------

### Creating the Jinaga Model

Source: https://jinaga.com/documents/reference/buildmodel

This example shows the final step of creating a Jinaga `Model` by calling the `buildModel` function with a configured `ModelBuilder`. The `ModelBuilder` can be composed of multiple type definitions.

```typescript
const model = buildModel(b => b
  .with(blogModel)
);
```

--------------------------------

### Share a Specification with Users in TypeScript

Source: https://jinaga.com/documents/reference/distributionrules

Demonstrates how to use the `share` method to define a specification and then chain it with a method to specify who it should be shared with. This example shares a specification related to blogs and posts.

```typescript
const distribution = (r: DistributionRules) => r
  .share(model.given(Blog).match(blog =>
    blog.successors(Post, post => post.blog)
      .exists(post => post.successors(Publish, publish => publish.post))
  )). // Then describe who to share it with
```

--------------------------------

### Command Line Execution for Distribution Deployment

Source: https://jinaga.com/documents/replicator/distribution

An example of how to execute the npm script to deploy Jinaga distribution rules. It passes the distribution endpoint URL and a bearer token as command-line arguments to the `npm run` command. This is typically used in development environments or directly on CI/CD servers.

```bash
npm run deploy:distribution https://rep.jinaga.com/xxxxxxx/distribution yyyyyyy
```

--------------------------------

### Registering a Fact Type with Predecessors

Source: https://jinaga.com/documents/reference/buildmodel

This example demonstrates how to register a fact type (e.g., `Post`) that has predecessors (e.g., `site` of type `Site`). The `type` method takes a second argument, a function that defines the predecessors.

```typescript
.type(Post, m => m
    .predecessor("site", Site)
  )
```

--------------------------------

### Define a Jinaga Specification with given and match

Source: https://jinaga.com/documents/reference/given-match

This is a basic example of a Jinaga specification. It uses `model.given` to declare the input facts and `match` to define the query logic. The specification retrieves projects for a user, excluding deleted projects and selecting their identifiers and names.

```typescript
const projectsForUser = model.given(User).match(user =>
  user.successors(Project, project => project.owner)
    .notExists(project => project.successors(ProjectDeleted, deleted => deleted.project))
    .select(project => ({
      hash: j.hash(project),
      identifier: project.identifier,
      names: project.successors(ProjectName, name => name.project)
        .notExists(name => name.successors(ProjectName, next => next.prior))
        .select(name => name.value)
    }))
);
```

--------------------------------

### Example JSON Structure for Exported Facts

Source: https://jinaga.com/documents/exporting-facts

This example demonstrates the structure of facts exported in JSON format. It includes fields like hash, type, predecessors, and data fields, which are essential for data interchange and analysis with JSON-compatible tools.

```json
[
  {
    "hash": "SV3Yseb0FJ/uQoL4IelHHbo1g4PZjnP4bx+aivMiiCkSTn2vSaNR6314KXL+PgO9lX9jmJzWoZABTRHjiFHWdQ==",
    "type": "Blog.Post",
    "predecessors": {
      "site": {
        "hash": "abc123",
        "type": "Blog.Site"
      }
    },
    "fields": {
      "createdAt": "2023-04-28T23:53:00Z"
    }
  }
]
```

--------------------------------

### OpenID Connect Authentication Provider for Jinaga

Source: https://jinaga.com/documents/reference/jinagabrowser-create

Implements the AuthenticationProvider interface for OpenID Connect. It provides methods to get authorization headers and reauthenticate by refreshing tokens. This is used to authenticate with the Jinaga replicator.

```typescript
interface AuthenticationProvider {
    getHeaders(): Promise<{ [key: string]: string; }>;
    reauthenticate(): Promise<boolean>;
}

class OpenIDConnectAuthenticationProvider implements AuthenticationProvider {
    async getHeaders(): Promise<{ [key: string]: string; }> {
        const token = await this.getBearerToken(); // Assume getBearerToken() is implemented
        return Promise.resolve({
            "Authorization": `Bearer ${token}`
        });
    }

    async reauthenticate(): Promise<boolean> {
        const succeeded = await this.refreshToken(); // Assume refreshToken() is implemented
        return succeeded;
    }

    // Placeholder methods for illustration - actual implementation needed
    private async getBearerToken(): Promise<string> {
        console.log('Getting bearer token...');
        // Replace with actual token retrieval logic
        return "dummy-token";
    }

    private async refreshToken(): Promise<boolean> {
        console.log('Refreshing token...');
        // Replace with actual token refresh logic
        return true;
    }
}

const authenticationProvider = new OpenIDConnectAuthenticationProvider();
```

--------------------------------

### Jinaga: Select Specific Fields

Source: https://jinaga.com/documents/reference/given-match

Demonstrates using the `select` function to project the results of a specification into a desired shape. This example selects the `value` field of `ProjectName` facts.

```typescript
const projectNames = model.given(Project).match(project =>
  project.successors(ProjectName, name => name.project)
    .notExists(name => name.successors(ProjectName, next => next.prior))
    .select(name => name.value)
);
```

--------------------------------

### Registering a Fact Type without Predecessors

Source: https://jinaga.com/documents/reference/buildmodel

This example shows how to register a fact type (e.g., `Site`) with the `ModelBuilder` when it has no predecessors. The `type` method is called with just the fact class.

```typescript
.type(Site)
```

--------------------------------

### Share a Specification with Everyone in TypeScript

Source: https://jinaga.com/documents/reference/distributionrules

This example shows how to share a specification with all users using the `withEveryone` method. It's useful for public data or general access to certain information, like published posts.

```typescript
export const distribution = (r: DistributionRules) => r
  // Everyone can see published posts
  .share(model.given(Blog).match(blog =>
    blog.successors(Post, post => post.blog)
      .exists(post => post.successors(Publish, publish => publish.post))
  )).withEveryone()
```

--------------------------------

### Jinaga: Navigate Siblings with Successors

Source: https://jinaga.com/documents/reference/given-match

Illustrates using the `successors` method to find sibling facts by starting from a common predecessor. This allows retrieving other projects within the same company.

```typescript
const otherProjectsInCompany = model.given(Project).match(project =>
  project.company.successors(Project, other => other.company)
    // ...
);
```

--------------------------------

### Declare a Jinaga Fact with Predecessor

Source: https://jinaga.com/documents/replicator/write

Shows how to declare a fact that has a predecessor. This example defines a 'Post' fact and sets its 'site' field to the previously declared 'site' fact.

```jinaga-fact-language
let post: Blog.Post = {
    createdAt: "2022-08-16T15:23:13.231Z",
    site: site
}
```

--------------------------------

### Build a Jinaga Model (Construction)

Source: https://jinaga.com/documents/concepts/facts

Constructs a Jinaga model by defining types and their relationships. This example shows how to add the 'Project' type to a model builder, specifying its 'creator' predecessor, which links it to the 'User' type.

```typescript
const constructionModel = (b: ModelBuilder) => b
  .type(Project, m => m
    .predecessor("creator", User)
  )
  ;
```

--------------------------------

### Declare a Jinaga Fact with Array Predecessors

Source: https://jinaga.com/documents/replicator/write

Shows how to define an array of predecessors. This example declares a 'Post.Title' fact and includes a previously defined 'title' fact in its 'prior' array.

```jinaga-fact-language
let title2: Blog.Post.Title = {
    post,
    value: "Introduction to the Jinaga Replicator",
    prior: [ title ]
}
```

--------------------------------

### Jinaga: Get Current Fact using Predecessor

Source: https://jinaga.com/documents/reference/given-match

Demonstrates a pattern using `predecessor` to retrieve the fact itself, often used in distribution rules to match the user.

```typescript
const distribution = (r: DistributionRules) => r
  .share(model.given(User).match(user =>
    user.successors(UserName, name => name.user)
      .notExists(name => name.successors(UserName, next => next.prior))
  )).with(user => user.predecessor())
```

--------------------------------

### Define Jinaga Authorization Rules

Source: https://jinaga.com/documents/reference/authorizationrules

This example demonstrates how to define a comprehensive set of authorization rules for creating facts in Jinaga. It uses methods like any, no, type, and with to build a composite authorization strategy. Dependencies include AuthorizationRules, AnybodyCanCreate, NobodyCanCreate, PredecessorCanCreate, SiblingCanCreate, and other authorization functions.

```typescript
const authorization = (a: AuthorizationRules) => a
  .any(AnybodyCanCreate)
  .no(NobodyCanCreate)
  .type(PredecessorCanCreate, x => x.predecessor)
  .type(SiblingCanCreate, siblingSpecification)
  .with(otherAuthorizationFunction)
  ;
```

--------------------------------

### Declare a Jinaga Fact with Empty Array Predecessor

Source: https://jinaga.com/documents/replicator/write

Illustrates how to define an empty array for predecessors. This example shows the declaration of a 'Post.Title' fact with an empty 'prior' array.

```jinaga-fact-language
let title: Blog.Post.Title = {
    post,
    value: "Introducing Jinaga Replicator",
    prior: []
}
```

--------------------------------

### Jinaga: Select Many Related Facts

Source: https://jinaga.com/documents/reference/given-match

Shows how to use `selectMany` to retrieve multiple related facts for each fact in the current stream. This example retrieves all tasks associated with a user's projects.

```typescript
const allProjectTasksForUser = model.given(User).match(user =>
  user.successors(Project, project => project.owner)
    .selectMany(project => project.successors(Task, task => task.project))
);
```

--------------------------------

### Run Jinaga Specification with j.query (JavaScript)

Source: https://jinaga.com/documents/reference/j-query

The j.query function executes a Jinaga specification to fetch data. It requires a specification (like 'projectsForUser') and a user context. The function is asynchronous and returns an array of objects, each containing a 'hash' and 'identifier' as demonstrated in the example.

```javascript
const projectsForUser = model.given(User).match(user =>
  user.successors(Project, project => project.owner)
    .select(project => ({
      hash: j.hash(project),
      identifier: project.identifier
    }))
);

const projects = await j.query(projectsForUser, user);

// projects = [{
//   hash: "..."
//   identifier: "..."
// }, ...]
```

--------------------------------

### Jinaga: Filter Facts that Exist

Source: https://jinaga.com/documents/reference/given-match

Shows how to use the `exists` method to filter facts based on the presence of a successor fact. This example finds published posts by checking for a `PostPublished` successor.

```typescript
const publishedPosts = model.given(Site).match(site =>
  site.successors(Post, post => post.site)
    .exists(post => post.successors(PostPublished, published => published.post))
    // ...
);
```

--------------------------------

### Export Jinaga Postgres data to Factual format and save to file

Source: https://jinaga.com/documents/exporting-facts/exporting-from-postgres

This example demonstrates exporting data from a Jinaga PostgreSQL database in Factual format and saving it to a file named 'output.fact'. Ensure you provide the correct connection parameters for your PostgreSQL instance.

```bash
npx jinaga-export-postgres --host localhost --port 5432 --database mydb --user myuser --password mypassword --format factual > output.fact
```

--------------------------------

### Define Jinaga Specification for Posts in a Site (TypeScript)

Source: https://jinaga.com/documents/create-an-app/match-successor-facts

Defines a Jinaga specification to match 'Post' facts that are successors of a given 'Site' fact. This involves starting with the model, specifying the 'Site' context, and then matching 'Post' facts based on their relationship to the 'Site'.

```typescript
import { model } from '../model';
import { Post, Site } from '../model/blog';

const postsInSite = model.given(Site).match(site =>
  site.successors(Post, post => post.site)
);
```

--------------------------------

### Export Jinaga Postgres data to JSON and save to file

Source: https://jinaga.com/documents/exporting-facts/exporting-from-postgres

This example shows how to export data from a Jinaga PostgreSQL database in JSON format and redirect the output to a file named 'output.json'. Replace placeholders with your actual database credentials and host information.

```bash
npx jinaga-export-postgres --host localhost --port 5432 --database mydb --user myuser --password mypassword --format json > output.json
```

--------------------------------

### Navigate to React App Directory and Open VS Code

Source: https://jinaga.com/documents/create-an-app/create-react-app

Changes the current directory to the newly created React application folder and opens the project in VS Code. This step is common for both React and React Native projects.

```bash
cd my-application
code .
```

--------------------------------

### Create React Native App with Expo TypeScript Template

Source: https://jinaga.com/documents/create-an-app/create-react-app

Initializes a new React Native application using Expo with a blank TypeScript template. This command should be run in PowerShell on Windows, not WSL.

```bash
npx create-expo-app my-application -t expo-template-blank-typescript
```

--------------------------------

### Create Jinaga Instance for Testing

Source: https://jinaga.com/documents/reference/jinagatest-create

Creates a Jinaga instance for unit tests, allowing configuration of authorization, user, device, and initial state. All parameters are optional.

```typescript
var j: Jinaga;

beforeEach(() => {
  j = JinagaTest.create({
    authorization: authorization,
    user: new User("public key"),
    device: new Device("public key"),
    initial state: [
      fact1,
      fact2,
      ...
    ]
  });
});
```

--------------------------------

### Create Jinaga Browser Instance with Configuration

Source: https://jinaga.com/documents/reference/jinagabrowser-create

Creates a Jinaga instance for browser applications. It configures the HTTP and WebSocket endpoints for the Jinaga replicator, specifies the IndexedDB name for local storage, sets an HTTP timeout, and provides an authentication provider. All parameters are optional.

```typescript
import { JinagaBrowser } from "jinaga";

// Assume authenticationProvider is defined elsewhere
// const authenticationProvider = { getHeaders: () => Promise.resolve({}), reauthenticate: () => Promise.resolve(true) };

export const j = JinagaBrowser.create({
    httpEndpoint: process.env.REACT_APP_JINAGA_REPLICATOR_URL,
    wsEndpoint: process.env.REACT_APP_JINAGA_REPLICATOR_WS,
    indexedDb: 'dbname',
    httpTimeoutSeconds: 30,
    httpAuthenticationProvider: authenticationProvider
});
```

--------------------------------

### Initialize Jinaga Server with Purge Conditions

Source: https://jinaga.com/documents/replicator/purge-conditions

This code snippet shows how to initialize a Jinaga server, including the PostgreSQL store configuration and the previously declared purge conditions. The `purgeConditions` are passed during the `JinagaServer.create` call, enabling the runtime to enforce data purging rules.

```typescript
const { handler, j } = JinagaServer.create({
    pgStore: process.env.JINAGA_POSTGRESQL ||
        'postgresql://appuser:apppw@localhost:5432/appdb',
    purgeConditions
});
```

--------------------------------

### Initialize Jinaga State with Facts for Testing

Source: https://jinaga.com/documents/reference/jinagatest-create

Loads a list of facts into the Jinaga instance before running tests using the 'initial state' parameter. Authorization rules are not evaluated for these facts, making it useful for setting up preconditions that the logged-in user might not be authorized to create.

```typescript
const fact1 = new Fact1();
const fact2 = new Fact2(fact1);

var j: Jinaga;

beforeEach(() => {
  j = JinagaTest.create({
    initialState: [
      fact1,
      fact2
    ]
  });
});
```

--------------------------------

### Simulate Local Device for Testing

Source: https://jinaga.com/documents/reference/jinagatest-create

Simulates a local device by providing a Device fact to JinagaTest.create. This is useful for testing authorization rules for backend services or replicators by combining it with the authorization parameter.

```typescript
var j: Jinaga;

beforeEach(() => {
  j = JinagaTest.create({
    device: new Device("public key")
  });
});

it("should be local device", () => {
  const device = await j.local<Device>();
  expect(j.publicKey).toEqual("public key");
});
```

--------------------------------

### Deploy Jinaga Distribution Rules using Node.js

Source: https://jinaga.com/documents/replicator/distribution

A Node.js script that describes Jinaga distribution rules to text format and posts them to a replicator endpoint. It requires the `jinaga` library and uses `fetch` to send a POST request with the distribution rules and an authorization bearer token. The script expects the replicator URL and bearer token as command-line arguments.

```typescript
import { describeDistributionRules } from "jinaga";
import { distribution } from "./model";

const postData = describeDistributionRules(distribution);
const url = process.argv[2];
const bearerToken = process.argv[3];

// POST the distribution rules to the replicator.
fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "text/plain",
    "Authorization": `Bearer ${bearerToken}`
  },
  body: postData
}).then(response => {
  if (response.status === 201) {
    console.log("Distribution rules updated.");
  } else {
    console.log(`Error updating distribution rules: ${response.status} ${response.statusText}`);
    process.exit(1);
  }
});
```

--------------------------------

### Login User and Get Fact

Source: https://jinaga.com/documents/concepts/facts

Logs in a user and retrieves a user fact. This is an asynchronous operation that returns a user and their profile. It's a fundamental step for user-based operations in Jinaga.

```typescript
const { userFact: user, profile } = await testClient.login<User>();
```

--------------------------------

### Query Projects Created by User in Jinaga

Source: https://jinaga.com/documents/concepts/predecessors

This snippet demonstrates how to define a Jinaga query to find all projects created by a specific user. It first creates a couple of projects and then uses the `given` and `match` methods with `successors` to define the query. The query is then executed using `j.query`.

```typescript
const projectB = await j.fact(new Project(user, crypto.randomUUID()));
const projectC = await j.fact(new Project(user, crypto.randomUUID()));

const projectsCreatedByUser = model.given(User).match(u =>
  u.successors(Project, p => p.creator)
);

const projects = await j.query(projectsCreatedByUser, user);
```

--------------------------------

### Describe and Deploy Authorization Rules (TypeScript)

Source: https://jinaga.com/documents/replicator/authorization

Generates a text representation of authorization rules and POSTs it to a replicator endpoint. This script uses `describeAuthorizationRules` to convert the rules into a deployable format and `fetch` to send them. It requires the replicator URL and a bearer token as command-line arguments.

```typescript
import { describeAuthorizationRules } from "jinaga";
import { authorization, model } from "./model";

const postData = describeAuthorizationRules(model, authorization);
const url = process.argv[2];
const bearerToken = process.argv[3];

// POST the authorization rules to the replicator.
fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "text/plain",
    "Authorization": `Bearer ${bearerToken}`
  },
  body: postData
}).then(response => {
  if (response.status === 201) {
    console.log("Authorization rules updated.");
  } else {
    console.log(`Error updating authorization rules: ${response.status} ${response.statusText}`);
    process.exit(1);
  }
});
```

--------------------------------

### NPM Script for Deploying Distribution Rules

Source: https://jinaga.com/documents/replicator/distribution

An npm script that compiles a TypeScript file containing Jinaga distribution rules and then runs the compiled JavaScript file using Node.js. This script automates the deployment process by first transpiling the TypeScript code to JavaScript and then executing it with provided command-line arguments for the replicator endpoint and bearer token.

```json
"scripts": {
  "deploy:distribution": "tsc ./src/output-distribution.ts --outDir ./deploy && node ./deploy/output-distribution.js"
}
```

--------------------------------

### Create Jinaga Fact Instance in TypeScript

Source: https://jinaga.com/documents/conventions/typescript

This example shows how to create a Jinaga fact instance using the `new` operator with a previously defined TypeScript class, such as `Tag`. The `j.fact()` function is then used to persist the fact.

```typescript
const tagReact = await j.fact(new Tag("React"));
```

--------------------------------

### NPM Script for Deploying Authorization

Source: https://jinaga.com/documents/replicator/authorization

An NPM script that compiles and runs the authorization deployment file. It first compiles the TypeScript file using `tsc` and then executes the compiled JavaScript file using `node`, passing the replicator URL and bearer token as arguments.

```json
"scripts": {
  "deploy:authorization": "tsc ./src/output-authorization.ts --outDir ./deploy && node ./deploy/output-authorization.js"
}
```

--------------------------------

### Initialize Composite Jinaga Model in TypeScript

Source: https://jinaga.com/documents/create-an-app/define-a-model

Initializes the composite Jinaga model by building it with the blogModel. This is the entry point for defining the application's data model.

```typescript
import { buildModel } from "jinaga";
import { blogModel } from "./blog";

export const model = buildModel(b => b
  .with(blogModel)
);
```

--------------------------------

### Create a Jinaga Fact Instance

Source: https://jinaga.com/documents/concepts/facts

Creates and saves a new 'Project' fact using the Jinaga client. This asynchronous operation persists the fact locally and initiates synchronization with other clients. It requires a user and a unique project ID.

```typescript
const projectA = await testClient.fact(new Project(user, crypto.randomUUID()));
```

--------------------------------

### Watch a Specification and Receive Results - JavaScript

Source: https://jinaga.com/documents/reference/j-watch

Use j.watch to execute a Jinaga specification and get results as they change. The callback function is invoked for each result added to the set. This is the primary method for observing data changes in Jinaga.

```javascript
const projectsForUser = model.given(User).match(user =>
  user.successors(Project, project => project.owner)
    .select(project => ({
      hash: j.hash(project),
      identifier: project.identifier
    }))
);

const projectWatch = j.watch(projectsForUser, user, (newProject) => {
  // Respond to a project being added to the result set.
  // newProject = {
  //   hash: "...",
  //   identifier: "..."
  // }
});
```

--------------------------------

### Create Jinaga Client with IndexedDB

Source: https://jinaga.com/documents/concepts

This code snippet demonstrates how to create a Jinaga client instance configured to use IndexedDB for local data persistence. It requires the `JinagaClient` class and specifies the HTTP endpoint for the replicator and the name of the IndexedDB database. This is suitable for production environments where local state needs to be saved.

```typescript
import { JinagaClient } from "jinaga";

const j = JinagaClient.create({
  // Connect to the Jinaga replicator that you host yourself, or that we host for you.
  httpEndpoint: "https://rep.jinaga.com/myreplicator",

  // Use the SQLite store to persist data locally.
  indexedDb: "my-application-state"
});
```

--------------------------------

### Define and Build Jinaga Model with TypeScript

Source: https://jinaga.com/documents/reference/buildmodel

This snippet demonstrates how to define fact types (Site, Post) using TypeScript classes and build a Jinaga model. It utilizes `ModelBuilder` to register types and their predecessors, composing them with the `with` method and finally creating the model using `buildModel`.

```typescript
const blogModel = (b: ModelBuilder) => b
  .type(Site)
  .type(Post, m => m
    .predecessor("site", Site)
  )
;

const model = buildModel(b => b
  .with(blogModel)
);
```

--------------------------------

### Simulate Logged-in User for Testing

Source: https://jinaga.com/documents/reference/jinagatest-create

Simulates a logged-in user by providing a User fact to JinagaTest.create. This allows testing user-specific authorization rules and interactions, such as creating facts where the user is the predecessor.

```typescript
var j: Jinaga;

beforeEach(() => {
  j = JinagaTest.create({
    user: new User("public key")
  });
});

it("should be logged in", () => {
  const user = await j.login<User>();
  expect(j.publicKey).toEqual("public key");
});

it("should allow the user to create a fact with herself as predecessor", async () => {
  const user = await j.login<User>();
  await expect(j.fact(new PredecessorCanCreate(user))).resolves.not.toThrow();
});

it("should not allow the user to create a fact with another as predecessor", async () => {
  const otherUser = new User("other public key");
  await expect(j.fact(new PredecessorCanCreate(otherUser))).rejects.toThrow();
});
```

--------------------------------

### Generate Hash of a Fact using j.hash

Source: https://jinaga.com/documents/reference/given-match

This snippet demonstrates how to retrieve the hash of a Jinaga fact using the `j.hash` function. It's typically used within a `select` clause to get a unique identifier for a fact. The input is a Jinaga fact, and the output is its hash.

```typescript
const projectHashes = model.given(Project).match(project =>
  project.predecessor()
    .select(project => j.hash(project))
);
```

--------------------------------

### Declare a Jinaga Fact with Simplified Predecessor

Source: https://jinaga.com/documents/replicator/write

Demonstrates a shorthand syntax for declaring a predecessor when the predecessor variable name matches the field name. This simplifies the declaration of the 'site' field in the 'Post' fact.

```jinaga-fact-language
let post: Blog.Post = {
    createdAt: "2022-08-16T15:23:13.231Z",
    site
}
```

--------------------------------

### Configure Authorization Rules for Testing

Source: https://jinaga.com/documents/reference/jinagatest-create

Defines authorization rules for Jinaga using AuthorizationRules. This configuration can be used in unit tests to verify authorization logic by asserting that j.fact throws exceptions when users are not authorized.

```typescript
const authorization = (a: AuthorizationRules) => a
  .any(AnybodyCanCreate)
  .no(NobodyCanCreate)
  .type(PredecessorCanCreate, x => x.predecessor)
  .type(SiblingCanCreate, siblingSpecification)
  .with(otherAuthorizationFunction) 
  ;

var j: Jinaga;

beforeEach(() => {
  j = JinagaTest.create({
    authorization: authorization
  });
});

it("should not allow anybody to create a fact", async () => {
  await expect(j.fact(new NobodyCanCreate())).rejects.toThrow();
});
```

--------------------------------

### Define Distribution Rules with TypeScript

Source: https://jinaga.com/documents/reference/distributionrules

This snippet shows the basic structure of defining distribution rules using a function that accepts a `DistributionRules` object. It's the entry point for all distribution rule definitions.

```typescript
export const distribution = (r: DistributionRules) => r
    // rules...
```

--------------------------------

### Create Initial Project Name Fact

Source: https://jinaga.com/documents/concepts/mutable-properties

Creates the first 'ProjectName' fact for a given project. It is initialized with an empty 'prior' array, indicating it's the initial value.

```typescript
const projectAName1 = await j.fact(new ProjectName(projectA, "Cheyenne Expansion", []));
```

--------------------------------

### Create Composite Objects

Source: https://jinaga.com/documents/reference/given-match

This snippet shows how to create composite objects by returning an object from a callback, often within a `selectMany` clause. It combines information from different facts into a single structure. Properties can be fields, hashes, facts, or sub-specifications, but not predecessors directly. The input is a user, and the output is an object containing project hashes and company facts.

```typescript
const projectHashesAndCompaniesForUser = model.given(User).match(user =>
  user.successors(Project, project => project.owner)
    .selectMany(project => project.company.successors(Company, company => company)
      .select(company => ({
        projectHash: j.hash(project),
        company: company
      }))
    )
);
```

```typescript
const projectHashesAndCompaniesForUser = model.given(User).match(user =>
  user.successors(Project, project => project.owner)
    .select(project => ({
      projectHash: j.hash(project),
      company: project.company      // Incorrect.
    }))
);
```

--------------------------------

### Create Jinaga Test Client with In-Memory Store

Source: https://jinaga.com/documents/concepts

This code snippet shows how to create a Jinaga client specifically for unit testing purposes, utilizing an in-memory store. It uses the `JinagaTest` class and requires a `User` object to identify the test user. This is useful for testing Jinaga functionality without actual data persistence.

```typescript
import { JinagaTest } from "jinaga";

const testClient = JinagaTest.create({
  user: new User("--- TEST USER ---")
});
```

--------------------------------

### Share a Specification with Specific Users in TypeScript

Source: https://jinaga.com/documents/reference/distributionrules

Illustrates how to use the `with` method to share a specification with a carefully selected group of users. This allows for fine-grained access control, such as allowing creators to see all posts and comments, or authors to see their own comments.

```typescript
export const distribution = (r: DistributionRules) => r
  // The creator can see all posts and comments
  .share(model.given(Blog).select(blog => ({
    posts: blog.successors(Post, post => post.blog),
    comments: blog.successors(Comment, comment => comment.post.blog)
  }))).with(model.given(Blog).match(blog =>
    blog.creator.predecessor()
  ))
  // A comment author can see their own comments on published posts
  .share(model.given(Blog, User).match((blog, author) =>
    blog.successors(Post, post => post.blog)
      .exists(post => post.successors(Publish, publish => publish.post))
      .selectMany(post => post.successors(Comment, comment => comment.post)
        .join(comment => comment.author, author)
      )
  )).with(model.given(Blog, User).select((blog, author) =>
    author
  ))
```

--------------------------------

### Copy Data from Old to New Replicator Volume

Source: https://jinaga.com/documents/replicator/upgrading

This command pulls the latest Ubuntu image and runs a temporary container. It mounts the old volume (identified by its name, e.g., 'd656e6e25c8aad61cc3b0425939342e5e3ed80faf43b78b7c7fde670770b6da1') as '/source' and the new volume ('my-replicator-db') as '/dest'. A bash command then copies all contents from the source to the destination, migrating the database data.

```bash
docker pull ubuntu:latest
docker run --rm \
  -v d656e6e25c8aad61cc3b0425939342e5e3ed80faf43b78b7c7fde670770b6da1:/source \
  -v my-replicator-db:/dest \
  ubuntu:latest \
  bash -c "cp -R /source/* /dest/"
```

--------------------------------

### Display Post Titles in React (JavaScript)

Source: https://jinaga.com/documents/create-an-app/select-a-sub-specification

This React code snippet demonstrates how to render a list of post titles obtained from a Jinaga specification. It maps over the `data` array, displaying each post's hash as a key and joining its candidate titles with a comma. This handles cases where multiple titles exist due to concurrent edits.

```javascript
{ data ? <ul>
    { data.map(post =>
      <li key={post.hash}>{post.titles.join(', ')}</li>
    ) }
  </ul> : null }
```

--------------------------------

### Use Jinaga Specification in React Component (TypeScript)

Source: https://jinaga.com/documents/create-an-app/match-successor-facts

Demonstrates how to use the 'useSpecification' hook from 'jinaga-react' to retrieve data based on a defined Jinaga specification. It shows how to pass the Jinaga instance, the specification, and the context (site) to the hook, and how to access loading, data, and error states.

```typescript
import { useSpecification } from 'jinaga-react';
import { j } from '../jinaga-config';

export function SiteContainer({ site }: SiteContainerProps) {
  const { loading, data, error } = useSpecification(j, postsInSite, site);
  //...
}
```

--------------------------------

### Compose Distribution Functions with 'with' in TypeScript

Source: https://jinaga.com/documents/reference/distributionrules

Shows how to combine different distribution functions using the `with` method. This allows for modularity and reusability in defining complex distribution rules.

```typescript
const otherDistributionFunction = (r: DistributionRules) => r
  // ...
  ;
const distribution = (r: DistributionRules) => r
  .with(otherDistributionFunction)
  ;
```

--------------------------------

### Jinaga: Navigate Predecessors

Source: https://jinaga.com/documents/reference/given-match

Explains how to use the `predecessor` method to retrieve the preceding fact in a relationship. This is useful for navigating up the fact hierarchy.

```typescript
const companyOfProject = model.given(Project).match(project =>
  project.company.predecessor()
    // ...
);
```

--------------------------------

### Configure httpYac for Jinaga Portal

Source: https://jinaga.com/documents/replicator

This configuration snippet is for httpYac when using the Jinaga Portal. It defines the replicator URL, OAuth2 endpoints and credentials, and authorization/distribution endpoints. These values should be replaced with actual details obtained after setting up authentication and authorization.

```env
replicatorUrl=https://rep.jinaga.com/xyz123

oauth2_authorizationEndpoint=https://rep.jinaga.com/xyz123/auth/apple
oauth2_tokenEndpoint=https://rep.jinaga.com/xyz123/auth/token
oauth2_clientId=xyz123
oauth2_usePkce=true

authorizationEndpoint=https://app.jinaga.com/xyz123/authorization
distributionEndpoint=https://app.jinaga.com/xyz123/distribution
secret=zyx321
```

--------------------------------

### Query and Display Jinaga Projections

Source: https://jinaga.com/documents/concepts/projections

This code snippet shows how to query Jinaga projections and display the results. It uses `j.query` with the previously defined `projectsWithNamesCreatedByUser` projection and iterates through the results to log the project ID and its associated names to the console.

```typescript
const projections = await j.query(projectsWithNamesCreatedByUser, user);

projections.forEach(p => {
  console.log(`${p.projectId}: [${p.names.join(", ")}]`);
});
```

--------------------------------

### Composing Model Builders

Source: https://jinaga.com/documents/reference/buildmodel

This snippet illustrates how to compose multiple type builder functions into a single `ModelBuilder` using the `with` method. This allows for modular definition of fact types.

```typescript
.with(blogModel)
```

--------------------------------

### Define Project Distribution Rules in TypeScript

Source: https://jinaga.com/documents/replicator/distribution

Defines distribution rules for a Jinaga project, specifying which invited users can access project details and invitations. It leverages model definitions and helper functions like `invitedUsers` to create granular access controls. This code assumes a pre-defined Jinaga model.

```typescript
const invitedUsers = (project: LabelOf<Project>) =>
  project.successors(Invitation, invitation => invitation.project)
    .selectMany(invitation => invitation.guest.predecessor());

export const projectDistribution = (model: Model) => (d: DistributionRules) => d
  // Share the project name with invited users.
  .share(model.given(Project).match(project =>
    project.successors(ProjectName, projectName => projectName.project)
      .notExists(projectName => projectName.successors(ProjectName, next => next.prior))
  ))
  .with(model.given(Project).match(project => invitedUsers(project)))

  // Share all project invitations with invited users.
  .share(model.given(Project).match(project =>
    project.successors(Invitation, invitation => invitation.project)
  ))
  .with(model.given(Project).match(project => invitedUsers(project)))

  // Share invitations with the user who was invited.
  .share(model.given(User).match(self =>
    self.successors(Invitation, invitation => invitation.user)
  ))
  .with(model.given(User).match(self =>
    self.predecessor()
  ));
```
Tokens:
Raw