ccs-react-native

React Native compatible CCS/Freeschema core package.

This package intentionally excludes browser-only pieces from mftsccs-browser: widgets, DOM rendering, service workers, BroadcastChannel, and IndexedDB.

Install From Local Folder

npm install ../react-package-ccs

Install from npm

npm install ccs-react-native

Configure

import AsyncStorage from "@react-native-async-storage/async-storage";
import {
  init,
  LoginToBackend,
  LocalTransaction,
  FreeschemaQuery,
  FreeschemaQueryApi,
} from "ccs-react-native";

await init({
  baseUrl: "https://your-csharp-api.example.com",
  nodeUrl: "https://your-node-api.example.com",
  applicationName: "your-app",
  storage: AsyncStorage,
});

const login = await LoginToBackend("[email protected]", "password");

storage is optional. Without it, local concepts/connections work in memory for the current app session. With a React Native storage adapter, pending local data and profile metadata can survive restarts.

Asynchronous Initialization in React Native (useEffect)

Because initialization (init) is asynchronous (it hydrates local state and tokens from storage), you should initialize it within a root-level useEffect hook and defer rendering your main components until it is ready:

import React, { useEffect, useState } from 'react';
import { ThemeProvider } from 'react-navigation';
import { init } from 'ccs-react-native';
import AppTabs from './components/app-tabs';

export default function AppLayout() {
  const [isCcsReady, setIsCcsReady] = useState(false);

  useEffect(() => {
    async function initializeCCS() {
      try {
        await init({
          baseUrl: process.env.EXPO_PUBLIC_BASE_URL || 'https://api.example.com',
          nodeUrl: process.env.EXPO_PUBLIC_NODE_URL || 'https://node.example.com',
          applicationName: process.env.EXPO_PUBLIC_APP_NAME || 'my-app',
        });
      } catch (error) {
        console.error('Failed to initialize ccs-react-native:', error);
      } finally {
        setIsCcsReady(true);
      }
    }

    initializeCCS();
  }, []);

  if (!isCcsReady) {
    return <SplashOverlay />; // Or loading spinner
  }

  return <AppTabs />;
}

Why is this pattern used?

1. Prevents Race Conditions: Querying or storing concepts/connections before the local state is fully hydrated will result in reading stale/empty values or calling unauthorized backend endpoints.
2. Loads Cached Authentication: The init function hydrates saved user profiles and tokens from persistent storage so that the session can be restored before making backend calls.
3. Ensures Thread Safety: React Native uses asynchronous native modules for storage. Blocking the rendering tree guarantees that components trying to interact with the connection system on mount will have the necessary state available immediately.

Local Concepts And Connections

const transaction = new LocalTransaction();
await transaction.initialize();

const person = await transaction.MakeTheInstanceConceptLocal(
  "the_person",
  "Alice",
  true,
  101,
  4
);

const email = await transaction.MakeTheInstanceConceptLocal(
  "the_email",
  "[email protected]",
  false,
  101,
  4
);

await transaction.CreateConnection(person, email, "the_person_email");
await transaction.commitTransaction();

Included Core APIs

• MakeTheInstanceConceptLocal
• MakeTheTypeConceptLocal
• CreateTheConceptLocal
• CreateTheConnectionLocal
• CreateConnection
• CreateConnectionBetweenTwoConceptsLocal
• LocalTransaction
• GetTheConcept
• GetConceptBulk / get_concept_bulk
• GetConnectionBulk / get_connection_bulk
• GetConceptByCharacter
• GetConceptByCharacterValue
• GetConceptByCharacterAndType
• LoginToBackend
• Signin
• Signup
• SignupEntity
• FreeschemaQuery
• FreeschemaQueryApi
• uploadAttachment
• uploadImage
• uploadImageV2
• uploadFile
• getUploadFileLimit
• GetImageApi
• GetFreeschemaImage
• GetFreeschemaImageUrl

Uploading Files & Caching Images

This package provides helper functions to handle file/image uploading and CDN image caching.

File/Image Uploading

import { uploadAttachment } from "ccs-react-native";

// In React Native, obtain file metadata from a picker (e.g. expo-document-picker)
const file = {
  uri: "file://path/to/image.jpg",
  name: "profile.jpg",
  type: "image/jpeg"
};

const res = await uploadAttachment(file);
if (res.success) {
  console.log("Uploaded URL:", res.url);
}

CDN Caching for Images

Use GetFreeschemaImageUrl to fetch the optimized, CDN-cached image URL:

import { GetFreeschemaImageUrl } from "ccs-react-native";

// Get standard CDN cached URL
const cachedUrl = GetFreeschemaImageUrl("https://my-backend.com/images/123.jpg");

// Get a smaller thumbnail size version of the CDN cached URL
const smallUrl = GetFreeschemaImageUrl("https://my-backend.com/images/123.jpg", "small");

Not Included

• Widgets and widget rendering
• Browser DOM helpers
• Service worker routing
• IndexedDB caches
• Browser event listeners